Azure Time Series Insights Gen1 クエリ API

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

注意事項

これは Gen1 の記事です。

この記事では、さまざまな REST クエリ API について説明します。 REST API は、一部の HTTP 操作 (メソッド) をサポートするサービスエンドポイントであり、Gen1 環境Azure Time Series Insightsクエリを実行できます。

重要

Azure Time Series Insights Gen1 では、環境の取得、環境の可用性の取得、メタデータの取得、環境イベントの取得、環境集計 API の取得に HTTPS プロトコルが使用されます。
Azure Time Series Insights Gen1 では、Get Environment Events Streamed API と Get Aggregates Streamed API に WebSocket Secure (WSS) プロトコルが使用されます。

環境 API を取得する

Get Environments API は、呼び出し元がアクセスを許可されている環境の一覧を返します。

エンドポイントと操作:

GET https://api.timeseries.azure.com/environments?api-version=2016-12-12

要求本文の例: 適用できません

応答本文の例:

{
  "environments": [
    {
      "displayName":"Sensors",
      "environmentFqdn": "00000000-0000-0000-0000-000000000000.env.timeseries.azure.com",
      "environmentId":"00000000-0000-0000-0000-000000000000",
      "resourceId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/RdxProdAssetsEastUs/providers/Microsoft.TimeSeriesInsights/environments/Sensors",
      "roles": [
        "Reader",
        "Contributor"
      ]
    }
  ]
}

注意

応答プロパティ environmentFqdn は、環境ごとのクエリ API 要求で使用される環境の一意の完全修飾ドメイン名です。

Get Environment Availability API

Get Environment Availability API は、イベントタイムスタンプ $tsに対するイベント数の分布を返します。環境の可用性はキャッシュされ、応答時間は環境内のイベントの数に依存しません。

ヒント

Get Environment Availability API を使用して、フロントエンド UI エクスペリエンスを初期化できます。

エンドポイントと操作:

GET https://<environmentFqdn>/availability?api-version=2016-12-12

要求本文の例: 適用できません

応答本文の例:

{
  "range": {
    "from": "2016-08-01T01:02:03Z",
    "to": "2016-08-31T03:04:05Z"
  },
  "intervalSize": "1h",
  "distribution": {
    "2016-08-01T00:00:00Z": 123,
    "2016-08-31T03:00:00Z": 345
  }
}

イベントのない環境では、空のオブジェクトが返されます。

環境メタデータ API の取得

Get Environment Metadata API は、特定の検索スパンの環境メタデータを返します。メタデータは、プロパティ参照のセットとして返されます。 Azure Time Series Insights Gen1 は内部的にメタデータをキャッシュして近似し、検索スパンの正確なイベントに存在するより多くのプロパティを返す場合があります。

エンドポイントと操作:

POST https://<environmentFqdn>/metadata?api-version=2016-12-12

入力ペイロード構造:
- 検索スパン句 (必須)

要求本文の例

{
   "searchSpan": {
     "from": {"dateTime":"2016-08-01T00:00:00.000Z"},
     "to": {"dateTime":"2016-08-31T00:00:00.000Z"}
   }
}

応答本文の例:

{
   "properties": [
     {
       "name": "sensorId",
       "type": "String"
     },
     {
       "name": "sensorValue",
       "type": "Double"
     },
     {
       "name": "iothub-connection-device-id",
       "type": "String"
     }
   ]
}

空 properties の配列は、環境が空の場合、または検索範囲にイベントがない場合に返されます。

組み込みプロパティは、プロパティの一覧では返されません。

環境イベント API の取得

Get Environment Events API は、検索範囲と述語に一致する未加工のイベントの一覧を返します。

エンドポイントと操作:

POST https://<environmentFqdn>/events?api-version=<apiVersion>

入力ペイロード構造:
- 検索スパン句 (必須)
- Predicate 句 (省略可能)
- Limit 句 (必須)
要求本文の例
```
{
  "searchSpan": {
    "from": {
      "dateTime": "2019-12-30T00:00:00.000Z"
    },
    "to": {
      "dateTime": "2019-12-31T23:00:00.000Z"
    }
  },
  "predicateString": "PointValue.Double = 3.14",
  "top": {
    "sort": [
      {
        "input": {
          "builtInProperty": "$ts"
        },
          "order": "Asc"
        }
    ],
    "count": 1000
  }
}
```
注意
- 入れ子になった並べ替え (つまり、2 つ以上のプロパティによる並べ替え) は現在サポートされていません。
- イベントは並べ替え可能で、上部に限定できます。
- 並べ替えは、すべてのプロパティの種類でサポートされています。並べ替えは、 ブール式に対して定義されている比較演算子に依存します。

応答本文の例:

{
  "warnings": [],
  "events": [
    {
      "schema": {
        "rid": 0,
        "$esn" : "buildingsensors",
        "properties" : [{
          "name" : "sensorId",
          "type" : "String"
        }, {
          "name" : "sensorValue",
          "type" : "String"
        }]
      },
      "$ts" : "2016-08-30T23:20:00Z",
      "values" : ["IndoorTemperatureSensor", 72.123]
    }, {
      "schemaRid" : 0,
      "$ts" : "2016-08-30T23:21:00Z",
      "values" : ["IndoorTemperatureSensor", 72.345]
    }
  ]
}

Get Environment Events Streamed API

Get Environment Events Streamed API は、検索スパンと述語に一致する未加工のイベントの一覧を返します。

この API では、WebSocket Secure Protocol を使用してストリーミングを実行し、部分的な結果を返します。常に追加のイベントを返します。つまり、新しいメッセージは前のメッセージに追加されます。新しいメッセージには、前のメッセージに含まれていない新しいイベントが含まれています。前のメッセージは、新しいメッセージが追加されたときに保持する必要があります。

エンドポイントと操作:

GET wss://<environmentFqdn>/events?api-version=<apiVersion>

入力ペイロード構造:
- 検索スパン句 (必須)
- Predicate 句 (省略可能)
- Limit 句 (必須)

要求メッセージの例:

{
  "headers" : {
    "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>",
    "x-ms-client-request-id" : "132gae-w343-41a1-2342-w23ta4532"
  },
  "content": {
    "searchSpan": {
      "from": "2017-04-30T23:00:00.000Z",
      "to": "2017-05-01T00:00:00.000Z"
    },
    "top": {
      "sort": [
        {
          "input": {
            "builtInProperty": "$ts"
          },
          "order": "Asc"
        }
      ],
      "count": 1000
    }
  }
}

注意

入れ子になった並べ替え (つまり、2 つ以上のプロパティによる並べ替え) は現在サポートされていません。
イベントは並べ替え可能で、上部に限定できます。
並べ替えは、すべてのプロパティの種類でサポートされています。並べ替えは、 ブール式に対して定義されている比較演算子に依存します。

応答メッセージの例:

{
  "headers": {
    "x-ms-request-id": "a325-a345-sy43-w332-a4qat36a2262"
  },
  "content": {
    "events": [
      {
        "schema": {
          "rid": 0,
          "$esn": "devicedata",
          "properties": [
            {
              "name": "Id",
              "type": "String"
            },
            {
              "name": "TemperatureControlLevel",
              "type": "Double"
            },
            {
              "name": "Type",
              "type": "String"
            },
            {
              "name": "UnitVersion",
              "type": "String"
            },
            {
              "name": "Station",
              "type": "String"
            },
            {
              "name": "ProductionLine",
              "type": "String"
            },
            {
              "name": "Factory",
              "type": "String"
            },
            {
              "name": "Timestamp",
              "type": "DateTime"
            }
          ]
        },
        "$ts": "2017-04-30T23:00:00Z",
        "values": [
          "82faa3c1-f11d-44f5-a1ca-e448f6123eee",
          0.9835468282931982,
          "temp control rate",
          "1.1.7.0",
          "Station5",
          "Line1",
          "Factory2",
          "2017-04-30T23:00:00Z"
        ]
      },
      {
        "schemaRid": 0,
        "$ts": "2017-04-30T23:00:00Z",
        "values": [
          "acb2f926-62cc-4a88-9246-94a26ebcaee3",
          0.8542095381579537,
          "temp control rate",
          "1.1.7.0",
          "Station2",
          "Line1",
          "Factory3",
          "2017-04-30T23:00:00Z"
        ]
      }
    ]
  },
  "warnings": [],
  "percentCompleted": 100
}

Get Environment Aggregates API

Get Environment 集計 API は、必要に応じて他のプロパティの値を測定する際に、指定されたプロパティによってイベントをグループ化します。

注意

バケット境界では 、数値ヒストグラムに合わせ、より適切にサポートするために、 10ⁿ、2×10ⁿ、または 5×10ⁿ の値がサポートされます。

エンドポイントと操作:

POST https://<environmentFqdn>/aggregates?api-version=<apiVersion>

入力ペイロード構造:
- 検索スパン句 (必須)
- Predicate 句 (省略可能)
- Aggregates 句 (必須)

要求本文の例

{
 "searchSpan": {
   "from": {
     "dateTime": "2019-12-30T00:00:00.000Z"
   },
   "to": {
     "dateTime": "2019-12-31T23:00:00.000Z"
   }
 },
 "predicateString": "PointValue.Double > 1000",
 "aggregates": [
   {
     "dimension": {
       "uniqueValues": {
         "input": {
           "property": "iothub-connection-device-id",
           "type": "String"
         },
         "take": 100
       }
     },
     "aggregate": {
       "dimension": {
         "dateHistogram": {
           "input": {
             "builtInProperty": "$ts"
           },
           "breaks": {
             "size": "1h"
           }
         }
       },
       "measures": [
         {
           "min": {
             "input": {
               "property": "series.flowRate",
               "type": "Double"
             }
           }
         },
         {
           "count": {}
         }
       ]
     }
   }
 ]
}

応答本文の例:

{
  "aggregates": [
    {
      "dimension": [
        "Test-Device-A11342"
      ],
      "aggregate": {
        "dimension": [
          "2019-12-30T23:00:00Z",
          "2019-12-31T00:00:00Z"
        ],
        "measures": [
          [
            [
              0.319668575730514,
              2678
            ],
            [
              0.08442680357734211,
              1238
            ]
          ]
        ]
      }
    }
  ],
  "warnings": []
}

メジャー式が指定されておらず、イベントの一覧が空の場合、応答は空になります。

メジャーが存在する場合、応答には、ディメンション値、count の値、0およびその他の種類のメジャーの値をnull含nullむ 1 つのレコードが含まれます。

Get Environment Aggregates Streamed API

Get Environment Aggregates Streamed API は、必要に応じて他のプロパティの値を測定する際に、指定されたプロパティによってイベントをグループ化します。

この API では、ストリーミングに WebSocket Secure Protocol を使用し、部分的な結果を返します。
すべての値の置換 (スナップショット) が常に返されます。
以前のパケットは、クライアントによって破棄できます。

注意

バケット境界では 、数値ヒストグラムに合わせ、より適切にサポートするために、 10ⁿ、2×10ⁿ、または 5×10ⁿ の値がサポートされます。

エンドポイントと操作:

GET wss://<environmentFqdn>/aggregates?api-version=<apiVersion>

入力ペイロード構造:
- 検索スパン句 (必須)
- Predicate 句 (省略可能)
- Aggregates 句 (必須)

要求メッセージの例:

{
  "headers":{  
    "Authorization":"Bearer <YOUR_AAD_OAUTH_TOKEN>"
  },
  "content":{  
    "predicate":{  
      "predicateString":""
    },
    "searchSpan":{  
      "from":"2017-04-30T23:00:00.000Z",
      "to":"2017-05-01T00:00:00.000Z"
    },
    "aggregates":[{  
      "dimension":{  
        "dateHistogram":{  
          "input":{  
            "builtInProperty":"$ts"
          },
          "breaks":{  
            "size":"1m"
          }
        }
      },
      "measures":[{  
        "count":{}
      }]
    }]
  }
}

応答メッセージの例:

{  
  "headers":{  
    "x-ms-request-id":"abc3243-23af-23ad-3224s-a32525age"
  },
  "content":[  
    {  
      "dimension":[  
        "2017-04-30T23:00:00Z",
        "2017-04-30T23:01:00Z",
        "2017-04-30T23:02:00Z",
        "2017-04-30T23:03:00Z",
        "2017-04-30T23:04:00Z"
      ],
      "measures":[  
        [ 722 ],
        [ 721 ],
        [ 722 ],
        [ 721 ],
        [ 722 ]
      ]
    }
  ],
  "warnings":[ ],
  "percentCompleted":100
}

メジャー式が指定されておらず、イベントの一覧が空の場合、応答は空になります。

制限

複数の環境とユーザー間でリソースを公平に利用するために、クエリの実行中に次の制限が適用されます。

該当する API	制限名	制限値	影響を受ける SKU	Notes
All	最大要求サイズ	32 KB	S1、S2
環境の可用性の取得、環境メタデータの取得、環境イベントの取得、環境集計のストリーミングの取得	環境あたりの同時要求の最大数	10	S1、S2
環境イベントの取得、ストリーミングされた環境の集計の取得	最大応答サイズ	16 MB	S1、S2
環境イベントの取得、ストリーミングされた環境の集計の取得	述語内の一意のプロパティ参照の最大数 (述語文字列式を含む)	50	S1、S2
環境イベントの取得、ストリーミングされた環境の集計の取得	述語文字列にプロパティ参照がないフルテキスト検索用語の最大数	2	S1、S2	例: `HAS 'abc'`、`'abc'`
環境イベントを取得する	応答内のイベントの最大数	10,000	S1、S2
Get Environment Aggregates Streamed	ディメンションの最大数	5	S1、S2
Get Environment Aggregates Streamed	すべてのディメンションのカーディナリティの合計の最大値	150,000	S1、S2
Get Environment Aggregates Streamed	メジャーの最大数	20	S1、S2

エラー処理と解決

プロパティが見つかりません動作

述語の一部または集計 (メジャー) の一部としてクエリで参照されるプロパティの場合、既定では、クエリは環境のグローバル検索スパン内のプロパティの解決を試みます。プロパティが見つかった場合、クエリは成功します。プロパティが見つからない場合、クエリは失敗します。

ただし、この動作を変更して、プロパティを既存のものとして扱うことができますが、環境内に存在しない場合は値を使用 null します。これを行うには、オプションの要求ヘッダーに値 UseNullを設定しますx-ms-property-not-found-behavior。

要求ヘッダーに使用できる値は、 UseNull または ThrowError (既定値) です。値として設定 UseNull すると、プロパティが存在しない場合でもクエリは成功し、応答には見つからないプロパティを表示する警告が含まれます。

未解決のプロパティをレポートする

述語、ディメンション、メジャー式のプロパティ参照を指定できます。指定した検索範囲に対して特定の名前と型のプロパティが存在しない場合は、グローバルな期間にわたってプロパティを解決しようとします。

解決の成功に応じて、次の警告またはエラーが生成される場合があります。

グローバルな期間にわたって環境にプロパティが存在する場合は、適切に解決され、このプロパティの値が特定の検索範囲に対してであることを通知する警告が null 生成されます。
環境にプロパティが存在しない場合は、エラーが生成され、クエリの実行は失敗します。

エラー応答

クエリの実行が失敗した場合、JSON 応答ペイロードには、次の構造のエラー応答が含まれます。

{
  "error" : {
    "code" : "...",
    "message" : "...",
    "innerError" : {  
      "code" : "...",
      "message" : "...",
    }
  }
}

ここでは、 innerError は省略可能です。不適切な形式の要求などの基本的なエラーに加えて、次のエラーが返されます。

HTTP 状態コード	エラーコード	エラーメッセージの例	考えられる内部エラーコード
400	InvalidApiVersion	"API バージョン '2016' はサポートされていません。サポートされているバージョンは '2016-12-12' です。"
400	InvalidInput	"述語文字列を解析できません。"	`PredicateStringParseError`
400	InvalidInput	"述語文字列を変換できません。"	`InvalidTypes`, `LimitExceeded`, `MissingOperand`, `InvalidPropertyType`, `InvalidLiteral`, `PropertyNotFound`
400	InvalidInput	"複数の集計はサポートされていません。"
400	InvalidInput	"Predicate プロパティが見つかりません。"	`PropertyNotFound`
400	InvalidInput	"Measure プロパティが見つかりません。"	`PropertyNotFound`
400	InvalidInput	"Dimension プロパティが見つかりません。"	`PropertyNotFound`
400	InvalidInput	"メジャーの数が制限を超えました。"	`NumberOfMeasuresExceededLimit`
400	InvalidInput	"集計の深さが制限を超えました。"	`AggregateDepthExceededLimit`
400	InvalidInput	"カーディナリティの合計が制限を超えました。"	`TotalCardinalityExceededLimit`
400	InvalidInput	"プロパティ 'from' がありません。	`BreaksPropertyMissing`
400	InvalidInput	"プロパティ 'to' がありません。	`BreaksPropertyMissing`
400	InvalidInput	"要求サイズが制限を超えました。	`RequestSizeExceededLimit`
400	InvalidInput	"応答サイズが制限を超えました。"	`ResponseSizeExceededLimit`
400	InvalidInput	"イベント数が制限を超えました。	`EventCountExceededLimit`
400	InvalidInput	"プロパティ参照数が制限を超えました。	`PropertyReferenceCountExceededLimit`
400	InvalidMethod	"パス 'aggregates' では WebSocket 要求のみが許可されます。
400	InvalidUrl	"要求 URL '/a/b' を解析できませんでした。
408	RequestTimeout	"要求が '30' 秒後にタイムアウトしました。"
503	TooManyRequests	"環境 '95880732-01b9-44ea-8d2d-4d764dfe1904' の同時要求数 '10' を超えました。	`EnvRequestLimitExceeded`

警告

Query API 応答には、HTTP 応答または WebSocket 応答メッセージのルートの下に、警告の一覧がエントリとして "warnings" 含まれている場合があります。現在、特定の検索範囲に対してプロパティが見つからないが、グローバル期間の環境で見つかった場合、警告が生成されます。また、ヘッダーx-ms-property-not-found-behaviorがにUseNull設定され、参照されるプロパティがグローバル検索スパン内に存在しない場合にも生成されます。

各警告オブジェクトには、次のフィールドが含まれる場合があります。

フィールド名	フィールドの種類	Notes
code	String	定義済みの警告コードの 1 つ
message	String	詳細な警告メッセージ
target	String	警告の原因となった JSON 入力ペイロードエントリへのドット区切りの JSON パス
warningDetails	Dictionary	オプション;追加の警告の詳細 (述語文字列内の位置など)

次のコードは、述語、述語内の述語文字列、ディメンション、およびメジャーの警告の例を示しています。

"warnings": [
  {
    "code": "PropertyNotFound",
    "message": "Predicate property 'X' of type 'String' is not found in local search span.",
    "target": "predicate.and[0].eq.left.property.name"
  },
  {
    "code": "PropertyNotFound",
    "message": "Predicate string property 'X' is not found in local search span.",
    "target": "predicate.and[1].predicateString",
    "warningDetails": {
      "startPos": 1,
      "endPos": 2,
      "line": 1,
      "col": 1
    }
  },
  {
    "code": "PropertyNotFound",
    "message": "Dimension property 'X' of type 'String' is not found in local search span.",
    "target": "aggregates.dimension.uniqueValues.input.property"
  },
  {
    "code": "PropertyNotFound",
    "message": "Measure property 'X' of type 'String' is not found in local search span.",
    "target": "aggregates.aggregates.measures[0].min.input.property"
  }
]

Share via

Azure Time Series Insights Gen1 クエリ API

環境 API を取得する

Get Environment Availability API

環境メタデータ API の取得

環境イベント API の取得

Get Environment Events Streamed API

Get Environment Aggregates API

Get Environment Aggregates Streamed API

制限

エラー処理と解決

プロパティが見つかりません動作

未解決のプロパティをレポートする

エラー応答

警告

関連項目

その他のリソース