Azure 時間序列深入解析 Gen1 查詢 API

發行項
08/05/2023

警告

這是 Gen1 文章。

本文說明各種 REST 查詢 API。 REST API 是支援一組 HTTP 作業的服務端點， (方法) ，可讓您查詢 Azure 時間序列深入解析 Gen1 環境。

重要

Azure 時間序列深入解析 Gen1 會針對取得環境、取得環境可用性、取得中繼資料、取得環境事件和取得環境匯總API 使用 HTTPS 通訊協定。
Azure 時間序列深入解析 Gen1 使用 WebSocket Secure (WSS) 通訊協定，取得串流處理的環境事件和取得匯總串流API。

取得環境 API

取得環境 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

取得環境可用性 API 會傳回 事件時間戳記$ts的事件計數分佈。系統會快取環境可用性，而回應時間不取決於環境中的事件數目。

提示

取得環境可用性 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

取得環境中繼資料 API 會傳回指定搜尋範圍的環境中繼資料。中繼資料會以一組屬性參考的形式傳回。 Azure 時間序列深入解析 Gen1 內部快取和近似中繼資料，而且可能會傳回更多出現在搜尋範圍中確切事件的屬性。

端點和作業：

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

輸入承載結構：
- 搜尋 span 子句 (強制)

要求本文範例：

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

取得環境事件 API 會傳回符合搜尋範圍和述詞的原始事件清單。

端點和作業：

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

輸入承載結構：
- 搜尋 span 子句 (強制)
- 述詞子句 (選擇性)
- 限制子句 (強制)

要求本文範例：

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

注意

巢狀排序 (，也就是目前不支援依兩個或多個屬性排序) 。
事件可以排序並限制在頂端。
所有屬性類型都支援排序。排序依賴針對 布林運算式定義的比較運算子。

回應本文範例：

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

取得環境事件串流 API 會傳回符合搜尋範圍和述詞的原始事件清單。

此 API 會使用 WebSocket 安全通訊協定來執行串流並傳回部分結果。它一律會傳回其他事件。也就是說，新訊息會加到前一個訊息。新訊息包含未在上一個訊息中的新事件。新增新訊息時，應該保留先前的訊息。

端點和作業：

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

輸入承載結構：
- 搜尋 span 子句 (強制)
- 述詞子句 (選擇性)
- 限制子句 (強制)

範例要求訊息：

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

注意

巢狀排序 (，也就是目前不支援依兩個或多個屬性排序) 。
事件可以排序並限制在頂端。
所有屬性類型都支援排序。排序依賴針對 布林運算式定義的比較運算子。

範例回應訊息：

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

取得環境會依指定的屬性匯總 API 群組事件，因為它會選擇性地測量其他屬性的值。

注意

貯體界限支援 10ⁿ、 2×10ⁿ或 5×10ⁿ 值，以配合數值長條圖，並提供更好的支援。

端點和作業：

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

輸入承載結構：
- 搜尋 span 子句 (強制)
- 述詞子句 (選擇性)
- 匯總子句 (強制)

要求本文範例：

{
 "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 其他類型的量值。

取得串流的環境彙總值 API

取得環境會依指定的屬性匯總串流 API 群組事件，因為它選擇性地測量其他屬性的值：

此 API 會使用 WebSocket 安全通訊協定進行串流，並傳回部分結果。
它一律會傳回所有值的取代 (快照集) 。
用戶端可以捨棄先前的封包。

注意

貯體界限支援 10ⁿ、 2×10ⁿ或 5×10ⁿ 值，以配合數值長條圖，並提供更好的支援。

端點和作業：

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

輸入承載結構：
- 搜尋 span 子句 (強制)
- 述詞子句 (選擇性)
- 匯總子句 (強制)

範例要求訊息：

{
  "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 其他類型的量值。

限制

在查詢執行期間會套用下列限制，以在多個環境和使用者之間公平地利用資源：

適用的 API	限制名稱	限制值	受影響的 SKU	備註
全部	要求大小上限	32 KB	S1, S2
取得環境可用性、取得環境中繼資料、取得環境事件、取得串流處理的環境匯總	每個環境的並行要求數目上限	10	S1, S2
取得環境事件、取得串流處理的環境匯總	最大回應大小	16 MB	S1, S2
取得環境事件、取得串流處理的環境匯總	述詞中唯一屬性參考的數目上限，包括述詞字串運算式	50	S1, S2
取得環境事件、取得串流處理的環境匯總	述詞字串中沒有屬性參考的全文檢索搜尋字詞上限	2	S1, S2	範例：`HAS 'abc'`、`'abc'`
取得環境事件	回應中的事件數目上限	10,000	S1, S2
取得串流處理的環境匯總	維度數目上限	5	S1, S2
取得串流處理的環境匯總	所有維度的總基數上限	150,000	S1, S2
取得串流處理的環境匯總	量值數目上限	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	「找不到述詞屬性」。	`PropertyNotFound`
400	InvalidInput	「找不到 Measure 屬性。」	`PropertyNotFound`
400	InvalidInput	「找不到維度屬性」。	`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' 秒後逾時 (s) 」。
503	TooManyRequests	「環境 '95880732-01b9-44ea-8d2d-4d764dfe1904' 已超過 '10' 的並行要求計數。」	`EnvRequestLimitExceeded`

警告

查詢 API 回應可能包含警告清單，做為 "warnings" HTTP 回應或 WebSocket 回應訊息根目錄底下的專案。如果找不到指定搜尋範圍的屬性，但在全域時間範圍的環境中找到，則會產生目前警告。當標頭 x-ms-property-not-found-behavior 設定 UseNull 為，而且參考的屬性甚至不存在於全域搜尋範圍時，也會產生它。

每個警告物件可能包含下欄欄位：

欄位名稱	欄位類型	備註
code	String	其中一個預先定義的警告代碼
message	String	詳細的警告訊息
目標	String	JSON 輸入承載專案的點分隔 JSON 路徑，導致警告
warningDetails	字典	選;例如，其他警告詳細資料 (述詞字串中的位置)

下列程式碼提供述詞、述詞字串、維度和量值內之述詞字串的警告範例：

"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 偵錯 Proxy 可以攔截您的 REST 要求，以便診斷 HTTP 要求和回應訊息。
JWT.io。您可以使用此工具，快速傾印持有人權杖中的宣告，然後驗證其內容。
Postman。這是免費的 HTTP 要求和回應測試控管來偵錯 REST API。

檢閱Gen1 檔，以深入瞭解 Azure 時間序列深入解析 Gen1。

Azure 時間序列深入解析 Gen1 查詢 API

取得環境 API

取得環境可用性 API

取得環境中繼資料 API

取得環境事件 API

取得串流的環境事件 API

取得環境彙總值 API

取得串流的環境彙總值 API

限制

錯誤處理和解決方式

找不到屬性行為

報表未解析的屬性

錯誤回應

警告

另請參閱

其他資源