Azure Time Series Insights Gen1 クエリ API
注意事項
これは 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 }メジャー式が指定されておらず、イベントの一覧が空の場合、応答は空になります。
メジャーが存在する場合、応答には、ディメンション値、count の値、
0およびその他の種類のメジャーの値をnull含nullむ 1 つのレコードが含まれます。
制限
複数の環境とユーザー間でリソースを公平に利用するために、クエリの実行中に次の制限が適用されます。
| 該当する 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"
}
]
関連項目
アプリケーションの登録と Azure Active Directory プログラミング モデルの詳細については、「 開発者向け Azure Active Directory」を参照してください。
要求パラメーターと認証パラメーターの詳細については、「 認証と承認」を参照してください。
HTTP 要求と応答のテストに役立つツールは次のとおりです。
- Fiddler。 この無料の Web デバッグ プロキシでは、REST 要求をインターセプトできるため、HTTP 要求と応答メッセージを診断できます。
- JWT.io。 このツールを使用すると、ベアラー トークンに要求をすばやくダンプし、その内容を検証できます。
- Postman。 これは、REST API をデバッグするための無料の HTTP 要求および応答テスト ツールです。
Azure Time Series Insights Gen1 の詳細については、Gen1 のドキュメントを参照してください。