Azure Time Series Insights Gen1 参照データ API

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

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

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

API の概要

参照データ管理 API はバッチ API です。

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

• 置く
• Patch
• プロパティの削除
• 削除
• 取得

参照データ項目の配置

参照データ項目全体 $.put[i] (キー put を持つ配列内の i^番目の項目) を挿入または置換します。 コミットの単位は $.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
      }
    ]
  }
  

検証とエラー処理

参照データ管理 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"
  }
]

名前 contoso とキー deviceId が String タイプで設定され、以下の構造を持つ参照データ項目について考えてみましょう。

イベント ハブ メッセージ内の 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 の場合、キー以外のプロパティが交差してはなりません。
• 参照データセットは、イベントにのみ直接結合され、他の参照データセット (およびイベント) には結合されません。 参照データ項目をイベントに結合するには、参照データ項目で使用されるすべてのキー・プロパティーがイベントに存在する必要があります。 また、キー・プロパティーは、他の参照データ項目を介してイベントに結合された非キー・プロパティーから取得してはなりません。

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

現在の制限

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

こちらも参照ください

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

要求および認証パラメーターについては、「 認証および承認」を参照してください。

HTTP リクエストとレスポンスのテストを支援するツールには、次のものがあります。

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

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