共用方式為

Azure 時序見解 Gen1 查詢 API

謹慎

這是一篇關於 Gen1 的文章。

本文介紹各種 REST 查詢 API。 REST API 是支援一組 HTTP作（方法）的服務終結點，使你能夠查詢 Azure 時序見解 Gen1 環境。

這很重要

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

  • 輸入有效載荷結構：

    • 搜尋範圍子句（必填）

  • 要求本文範例：

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

  • 輸入有效載荷結構：

    • 搜尋範圍子句（必填）
    • 謂詞子句（選擇）
    • 限制條款（強制性）

  • 要求本文範例：

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

  • 輸入有效載荷結構：

    • 搜尋範圍子句（必填）
    • 謂詞子句（選擇）
    • 限制條款（強制性）

  • 要求訊息範例：

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

  • 輸入有效載荷結構：

    • 搜尋範圍子句（必填）
    • 謂詞子句（選擇）
    • 聚合子句（必填）

  • 要求本文範例：

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

  • 輸入有效載荷結構：

    • 搜尋範圍子句（必填）
    • 謂詞子句（選擇）
    • 聚合子句（必填）

  • 要求訊息範例：

    {
  "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 中一、中二
獲取環境可用性、獲取環境元數據、獲取環境事件、獲取流式環境聚合 每個環境的最大併發請求數 10 中一、中二
獲取環境事件，獲取流式處理環境聚合 最大回應大小 16 兆位元組 中一、中二
獲取環境事件，獲取流式處理環境聚合 謂詞中唯一屬性引用的最大數量，包括謂詞字串表達式 50 中一、中二
獲取環境事件，獲取流式處理環境聚合 謂詞字串中沒有屬性引用的最大全文搜索詞 2 中一、中二 範例：HAS 'abc'、'abc'
獲取環境事件 回應中的最大事件數 1萬 中一、中二
獲取環境聚合流式傳輸 最大維度數 5 中一、中二
獲取環境聚合流式傳輸 所有維度的最大總基數 150,000 中一、中二
獲取環境聚合流式傳輸 最大測量數 20 中一、中二

錯誤處理和解決

「未找到屬性」 行為

對於查詢中引用的屬性，無論是作為謂詞的一部分還是聚合（度量值）的一部分，默認情況下，查詢都會嘗試解析環境全域搜索範圍內的屬性。 如果找到該屬性，則查詢成功。 如果未找到該屬性，則查詢失敗。

但是，可以修改此行為，將屬性視為現有屬性，但如果環境中不存在屬性，則具有 null 值。 這個選項， 您可以選擇的請求標頭 x-ms-property-not-found-behavior 設定為值 UseNull。

請求標頭的可能值為 UseNull or ThrowError （預設值）。 當您設置為 UseNull 值時，即使屬性不存在，查詢也會成功，並且回應將包含顯示未找到的屬性的警告。

報告未解析的屬性

您可以為謂詞、維度和度量運算式指定屬性引用。 如果具有特定名稱和類型的屬性對於指定的搜索跨度不存在，則會嘗試在全域時間跨度內解析屬性。

根據解決的成功，可能會發出以下警告或錯誤：

  • 如果某個屬性在全域時間跨度記憶體在環境中，則會適當地解析該屬性，併發出警告以通知您此屬性的值適用於 null 給定的搜索範圍。
  • 如果環境中不存在屬性，則會發出錯誤，並且查詢執行失敗。

錯誤回應

如果查詢執行失敗，JSON 回應有效負載將包含具有以下結構的錯誤回應：

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

這裡是選擇的。 innerError 除了基本錯誤（例如格式錯誤的請求）外，還會返回以下錯誤：

HTTP 狀態代碼 錯誤碼 錯誤訊息的範例 可能的內部錯誤代碼
400 無效的Api版本 “不支援 API 版本'2016'。 支援的版本是『2016-12-12』。
400 無效輸入 “無法解析謂詞字串。” PredicateStringParseError
400 無效輸入 “無法翻譯謂詞字串。” InvalidTypes、LimitExceeded、MissingOperand、InvalidPropertyType、InvalidLiteral、PropertyNotFound
400 無效輸入 “不支援多個聚合。”
400 無效輸入 “未找到謂詞屬性。” PropertyNotFound
400 無效輸入 “未找到度量屬性。” PropertyNotFound
400 無效輸入 “未找到維度屬性。” PropertyNotFound
400 無效輸入 “措施數量超過限制。” NumberOfMeasuresExceededLimit
400 無效輸入 “聚合深度超出限制。” AggregateDepthExceededLimit
400 無效輸入 “總基數超出限制。” TotalCardinalityExceededLimit
400 無效輸入 “財產'來自'不見了。” BreaksPropertyMissing
400 無效輸入 “財產'to'不見了。” BreaksPropertyMissing
400 無效輸入 “請求大小超出限制。” RequestSizeExceededLimit
400 無效輸入 “回應大小超出限制。” ResponseSizeExceededLimit
400 無效輸入 “事件計數超出限制。” EventCountExceededLimit
400 無效輸入 “屬性參考數量超出限制。” PropertyReferenceCountExceededLimit
400 無效方法 “路徑'聚合'上只允許 WebSocket 請求。”
400 InvalidUrl “無法解析請求 URL '/a/b'。”
408 RequestTimeout “請求在'30'秒後超時。”
503 請求過多 “環境'95880732-01b9-44ea-8d2d-4d764dfe1904'的併發請求計數超過了'10'。” EnvRequestLimitExceeded

警告

查詢 API 回應可能包含警告清單，作為 "warnings" HTTP 回應或 WebSocket 回應訊息根目錄下的條目。 目前，如果未找到給定搜索跨度的屬性，但在全域時間跨度的環境中找到屬性，則會生成警告。 當標頭 x-ms-property-not-found-behavior 設置為 並且 UseNull 引用的屬性即使在全域搜索範圍中也不存在時，也會生成它。

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

欄位名稱 欄位類型 註釋
程式碼 String 預定義的警告代碼之一
訊息 String 詳細的警告消息
目標 String 導致警告的 JSON 輸入有效負載條目的點分隔 JSON 路徑
警告細節 字典 自選;其他警告詳細資訊（例如，謂詞字串中的位置）

以下代碼提供了謂詞、謂詞、維度和度量值中的謂詞字串的警告示例：

"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。 可以使用此工具快速轉儲持有令牌中的聲明，然後驗證其內容。
  • 郵遞員。 這是一個免費的 HTTP 請求和響應測試工具，用於調試 REST API。

通過查看 Gen1 文件，詳細瞭解 Azure 時序見解 Gen1。

  • Last updated on