Azure Time Series Insights Gen1 リファレンス データ API

この記事では、参照データセット内のアイテムを管理するために使用される Azure Time Series Insights Gen1 リファレンス データ管理 API について説明します。 参照データセットが環境内に既に作成されていることを前提としています。

参照データには、変更頻度の低い製造元または場所のデータが含まれます。 参照データは、テレメトリ データをコンテキスト化するために使用され、テレメトリ データを比較するために機能します。

データセットは既存の固定であるため、デバイスによって送信される各データ パケットには同じ情報が含まれます。 そのため、参照データはデバイスから送信されず、Reference データ管理 API または Azure portalを使用してデータを管理します。

API の概要

リファレンス データ管理 API はバッチ API です。

有効な JSON 要求操作プロパティ名は次のとおりです。

• 置く
• [Patch]
• プロパティを削除する
• 削除
• Get

参照データ項目を配置する

参照データ項目全体 (配列内の i^番目の項目$.put[i]をキー put に置き換えます) を挿入または置換します。 コミットの単位は、 $.put[i]. 操作がべき等です。

• エンドポイントと操作:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 要求本文の例:

  {
    "put": [{
      "deviceId": "Fan1",
      "color": "Red",
      "maxSpeed": 5
    },
    {
      "deviceId": "Fan2",
      "color": "White",
      "floor": 2
    }]
  }
  

• 応答の例:

  {
    "put": [
      null,
      null
    ]
  }
  

パッチ参照データ項目

参照データ項目 の特定のプロパティを更新して挿入します$.patch[i]。

• エンドポイントと操作:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 要求本文の例:

  {
    "patch": [
      {
        "deviceId": "Fan1",
        "maxSpeed": 108
      },
      {
        "deviceId": "Fan2",
        "floor": 18
      }
    ]
  }
  

• 応答本文の例:

  {
    "patch": [
      null,
      null
    ]
  }
  

参照データ項目のプロパティを削除する

参照データ項目 から指定したプロパティを削除します $.deleteproperties[i]。

• エンドポイントと操作:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 要求本文の例:

  {
    "deleteProperties":[
      {
        "key":{
          "deviceId":"Fan2"
        },
        "properties":[
          "floor"
        ]
      }
    ]
  }
  

• 応答本文の例:

  {
    "deleteProperties": [
      null
    ]
  }
  

参照データ項目を削除する

各 $.delete[i]で指定されたキー プロパティ値によって識別される参照データ項目全体を削除します。

• エンドポイントと操作:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 要求本文の例:

  {
    "delete": [{
      "deviceId": "Fan1"
    }]
  }
  

• 応答本文の例:

  {
    "delete": [
      null
    ]
  }
  

参照データ項目を取得する

各 $.get[i]で指定されたキー プロパティ値によって識別される参照データ項目全体を取得します。

• エンドポイントと操作:

  POST https://<environmentFqdn>/referencedatasets/<referenceDataSetName>/$batch?api-version=2016-12-12
  

• 要求本文の例:

  {
    "get": [{
      "deviceId": "Fan1"
    },
    {
      "deviceId": "Fan2"
    }]
  }
  

• 応答本文の例:

  {
    "get": [
      {
        "code": "InvalidInput",
        "message": "Key not found.",
        "target": null,
        "details": null,
        "innerError": null
      },
      {
        "id": "Fan2",
        "floor": 18
      }
    ]
  }
  

検証とエラー処理

Reference データ管理 API は各項目を個別に処理します。1 つの項目でエラーが発生しても、他の項目が正常に書き込まれるのを妨げるわけではありません。 たとえば、要求に 100 個のアイテムがあり、1 つのアイテムにエラーがある場合、99 個のアイテムが書き込まれ、1 つが拒否されます。

項目のエラー コード

項目エラー コードは、HTTP 状態コード 200 を持つ正常な JSON 応答本文内で発生します。

• InvalidInput: キーが見つかりません。: クエリ対象のアイテムが参照データセットに見つからないことを示します。

  {
    "code": "InvalidInput",
    "message": "Key not found.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

• InvalidInput: ペイロード キーにキー以外のプロパティを含めないようにします。: JSON 要求本文のクエリ アイテムに、キー プロパティではないプロパティ (つまり、参照セット スキーマで指定されているプロパティ) を含めないことを示します。 主なプロパティは、Azure portalにあります。

  {
    "code": "InvalidInput",
    "message": "Payload key should not contain any non-key property.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

• InvalidInput: ペイロード アイテムにはすべてのキー プロパティが含まれている必要があります。: JSON 要求本文のクエリ アイテムに、すべてのキー プロパティ (つまり、参照セット スキーマで指定されているプロパティ) を含める必要があることを示します。 主要なプロパティは、Azure portalで見つけることができます。

  {
    "code": "InvalidInput",
    "message": "Payload item should contain all key properties.",
    "target": null,
    "details": null,
    "innerError": null
  }
  

参照データ結合の例

次の構造を持つイベント ハブ メッセージについて考えてみましょう。

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z"
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z"
  }
]

String 型の名前contosoとキー deviceId で設定され、次の構造を持つ参照データ項目を考えてみましょう。

イベント ハブ メッセージ内の 2 つのイベントAzure Time Series Insights Gen1 イングレス エンジンによって処理されると、それらは正しい参照データ項目と結合されます。 イベント出力の構造は次のとおりです。

[
  {
    "deviceId":"Fan1",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"Red",
    "maxSpeed":5
  },
  {
    "deviceId":"Fan2",
    "timestamp":"1/5/2015T00:10:30Z",
    "color":"White",
    "floor":2
  }
]

結合ルールとセマンティクス

参照データを結合する場合は、次の制約に従います。

• キー名の比較では、大文字と小文字が区別されます。
• キー値の比較では、文字列プロパティでは大文字と小文字が区別されます。

複数の参照データセットを持つ環境では、結合中にさらに 3 つの制約が適用されます。

• 参照データセット内の各項目は、キー以外のプロパティの独自のリストを指定できます。
• 任意の 2 つの参照データセット A と B の場合、キー以外のプロパティは交差してはなりません。
• 参照データセットは、他の参照データセット (およびイベント) には参加せず、イベントにのみ直接参加します。 参照データ項目をイベントに結合するには、参照データ項目で使用されるすべてのキー プロパティがイベントに存在する必要があります。 また、キー プロパティは、他の参照データ項目を介してイベントに参加しているキー以外のプロパティから取得しないでください。

これらの制約がある場合、結合エンジンは特定のイベントに対して任意の順序で結合を適用できます。 階層と順序は考慮されません。

現在の制限

Gen1 環境ごとに最大 2 つの参照データセットAzure Time Series Insights追加できます。 Azure Time Series Insights Gen1 参照データに関連するその他の制限事項を次の表に示します。

関連項目

アプリケーションの登録と Azure Active Directory プログラミング モデルの詳細については、「 開発者向け Azure Active Directory」を参照してください。

要求パラメーターと認証パラメーターの詳細については、「 認証と承認」を参照してください。

HTTP 要求と応答のテストに役立つツールは次のとおりです。

• Fiddler。 この無料の Web デバッグ プロキシでは、REST 要求をインターセプトできるため、HTTP 要求と応答メッセージを診断できます。
• JWT.io。 このツールを使用すると、ベアラー トークンに要求をすばやくダンプし、その内容を検証できます。
• Postman。 これは、REST API をデバッグするための無料の HTTP 要求および応答テスト ツールです。

Azure Time Series Insights Gen1 の詳細については、Gen1 のドキュメントを参照してください。