你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure 时序见解 Gen1 查询 API

2025-08-12

谨慎

这是一篇 Gen1 文章。

本文介绍各种 REST 查询 API。 REST API 是支持一组 HTTP作（方法）的服务终结点，使你能够查询 Azure 时序见解 Gen1 环境。

重要

Azure 时序见解 Gen1 将 HTTPS 协议用于获取环境、获取环境可用性、获取元数据、获取环境事件和获取环境聚合 API。
Azure 时序见解 Gen1 将 WebSocket 安全（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

输入有效载荷结构：
- 搜索范围子句（必填）

示例请求正文：

{
   "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	TooManyRequests	“环境'95880732-01b9-44ea-8d2d-4d764dfe1904'的并发请求计数超过了'10'。”	`EnvRequestLimitExceeded`

警告

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

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

字段名称	Field 类型	注释
代码	字符串	预定义的警告代码之一
邮件	字符串	详细的警告消息
目标	字符串	导致警告的 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。

通过

Azure 时序见解 Gen1 查询 API

获取环境 API

获取环境可用性 API

获取环境元数据 API

获取环境事件 API

获取环境事件流式处理 API

获取环境聚合 API

获取环境聚合流式处理 API

限制

错误处理和解决

“未找到属性”行为

报告未解析的属性

错误响应

警告

另请参阅

其他资源