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

[アーティクル]
07/19/2023

注意事項

これは Gen1 の記事です。

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

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

ヒント

参照データセットを作成するには、「参照データセットを作成する方法」を参照してください。

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

API の概要

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

重要

この API に対するすべての操作は HTTP POST 操作です。
各操作は、要求ペイロードとして JSON オブジェクトを受け入れます。
HTTP 要求 JSON オブジェクトは、API によって実行される操作を指定する単一のプロパティ名を定義します。

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

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

重要

プロパティ値は、操作を適用する必要がある参照データ項目の配列です。
各項目は個別に処理され、1 つの項目でエラーが発生しても、他のアイテムが正常に書き込まれるのを妨げるわけではありません。たとえば、要求に 100 個のアイテムがあり、1 つのアイテムにエラーがある場合、99 個のアイテムが書き込まれ、1 つが拒否されます。
参照データ項目には、完全に列挙されたキープロパティを使用してクエリが実行されます。

注意

次の JSON 本文の例はすべて、 deviceId という名前と String 型の単一のプロパティキーを持つ参照データセットを想定 しています。

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

参照データ項目全体 (配列内の 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 で設定され、次の構造を持つ参照データ項目を考えてみましょう。

deviceId	color	maxSpeed	floor
Fan1	[赤]	5
Fan2	White		2

イベントハブメッセージ内の 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 参照データに関連するその他の制限事項を次の表に示します。

制限名	制限値	影響を受ける SKU	Notes
キープロパティの数	3	S1、S2	参照データセットごと。Azure Resource ManagerとAzure portalのみ
キープロパティのサイズ	1 KB	S1、S2	参照データセットごと
参照データ項目数	2,000/20,000 (S1/S2)	S1、S2	単位ごと;たとえば、4 ユニット S1 SKU = 8,000 項目 (4 x 2,000)
最大同時トランザクション数	2/10 (S1/S2)	S1、S2
参照データの最大トランザクション数	120/600 (S1/S2)	S1、S2	1 時間あたり
参照データ項目の最大数	1,000	S1、S2	トランザクションあたり
参照データ項目の最大サイズ	8,192 KB	S1、S2	トランザクションあたり

次の方法で共有

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

API の概要

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

パッチ参照データ項目

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

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

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

検証とエラー処理

項目のエラーコード

参照データ結合の例

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

現在の制限

関連項目

その他のリソース

次の方法で共有

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

API の概要

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

パッチ参照データ項目

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

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

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

検証とエラー処理

項目のエラー コード

参照データ結合の例

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

現在の制限

関連項目

その他のリソース

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

項目のエラーコード