Azure Time Series Insights Gen1 クエリ API

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

環境 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 要求で使用される環境の一意の完全修飾ドメイン名です。

環境可用性 API の取得

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

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

  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 の取得

環境メタデータの取得 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>
  

• 入力ペイロード構造:

  • 検索範囲句 (必須)
  • 述語句 (オプション)
  • 制限条項(必須)

• 要求本文の例

  {
    "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]
      }
    ]
  }
  

環境イベントストリーミング API の取得

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

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

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

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

• 入力ペイロード構造:

  • 検索範囲句 (必須)
  • 述語句 (オプション)
  • 制限条項(必須)

• 要求メッセージの例:

  {
    "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
  }
  

環境集計 API の取得

Get Environment Aggregates API は、オプションで他のプロパティの値を測定するため、指定されたプロパティでイベントをグループ化します。

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

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

• 入力ペイロード構造:

  • 検索範囲句 (必須)
  • 述語句 (オプション)
  • 集計句 (必須)

• 要求本文の例

  {
   "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": []
  }
  

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

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

環境集計の取得 Streamed API

Get Environment Aggregates Streamed API は、オプションで他のプロパティの値を測定するため、指定されたプロパティでイベントをグループ化します。

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

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

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

• 入力ペイロード構造:

  • 検索範囲句 (必須)
  • 述語句 (オプション)
  • 集計句 (必須)

• 要求メッセージの例:

  {
    "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
  }
  

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

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

制限

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

エラー処理と解決

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

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

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

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

未解決のプロパティを報告する

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

解決の成功によっては、次の警告またはエラーが出力される場合があります。

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

エラー応答

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

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

ここでは、 innerError はオプションです。 形式が正しくない要求などの基本的なエラーに加えて、次のエラーが返されます。

警告

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

各警告オブジェクトには、次のフィールドを含めることができます。

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

"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 リクエストとレスポンスのテストを支援するツールには、次のものがあります。

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

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