Azure 时序见解 Gen1 查询 API

2023-07-19

注意

这是一篇 Gen1 文章。

本文介绍各种 REST 查询 API。 REST API 是支持 HTTP 操作集 (方法) 的服务终结点，可用于查询 Azure 时序见解 Gen1 环境。

重要

Azure 时序见解 Gen1 对获取环境、获取环境可用性、获取元数据、获取环境事件和获取环境聚合 API 使用 HTTPS 协议。
Azure 时序见解 Gen1 使用 WebSocket Secure (WSS) 协议获取环境事件流式处理 API 和获取聚合流式处理 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

输入有效负载结构：
- 搜索范围子句 (强制)

示例请求正文：

{
   "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	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	“仅允许在路径”聚合“上发出 WebSocket 请求。”
400	InvalidUrl	“无法分析请求 URL'/a/b'。”
408	RequestTimeout	“请求在'30'秒后超时， () 。”
503	TooManyRequests	“环境'95880732-01b9-44ea-8d2d-4d764dfe1904'的并发请求计数已超出'10'。”	`EnvRequestLimitExceeded`

警告

查询 API 响应可能包含 HTTP 响应或 WebSocket 响应消息根下作为 "warnings" 条目的警告列表。如果找不到给定搜索范围的属性，但在全局时间跨度的环境中找到属性，则会生成警告。当标头x-ms-property-not-found-behavior设置为 UseNull 并且引用的属性即使在全局搜索范围中也不存在时，也会生成它。

每个警告对象可以包含以下字段：

字段名称	字段类型	说明
code	字符串	预定义警告代码之一
message	字符串	详细的警告消息
目标	字符串	导致警告的 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 请求和响应的工具包括：

菲德勒此免费的 Web 调试代理可以截获 REST 请求，因此你可以诊断 HTTP 请求和响应消息。
JWT.io。可以使用此工具在持有者令牌中快速转储声明，然后验证其内容。
Postman。这是一个免费的 HTTP 请求和响应测试工具，用于调试 REST API。

查看 Gen1 文档，详细了解 Azure 时序见解 Gen1。

通过

Azure 时序见解 Gen1 查询 API

获取环境 API

获取环境可用性 API

获取环境元数据 API

获取环境事件 API

获取流式处理的环境事件 API

获取环境聚合 API

获取流式处理的环境聚合 API

限制

错误处理和解决

“找不到属性”行为

报告未解析的属性

错误响应

警告

另请参阅

其他资源