本文介绍如何使用 Azure Monitor REST API 参考。
使用 Azure Monitor API 检索指标定义、维度值和指标值,并使用应用程序中的数据,或存储在数据库中进行分析。 还可以使用 Azure Monitor API 列出警报规则并查看活动日志。
对 Azure Monitor 请求进行身份验证
使用 Azure Monitor API 提交的请求使用 Azure 资源管理器身份验证模型。 所有请求都使用 Microsoft Entra ID 进行身份验证。 对客户端应用程序进行身份验证的一种方法是创建Microsoft Entra 服务主体并检索身份验证令牌。 可以使用 Azure 门户、CLI 或 PowerShell 创建Microsoft Entra 服务主体。 有关详细信息,请参阅 注册应用以请求授权令牌并使用 API。
检索令牌
创建服务主体后,检索访问令牌。 在令牌请求中指定 resource=https://management.chinacloudapi.cn
。
使用以下任一方法获取身份验证令牌:
- CLI
- REST API
- SDK
请求令牌时,必须提供参数 resource
。 参数 resource
是要访问的资源的 URL。
资源包括:
https://management.chinacloudapi.cn
https://api.loganalytics.io
https://monitoring.azure.cn
使用 REST 请求获取令牌
使用以下 REST API 调用获取令牌。 此请求使用客户端 ID 和客户端密码对请求进行身份验证。 向 Microsoft Entra ID 注册应用程序时,会获取客户端 ID 和客户端密码。 有关详细信息,请参阅 注册应用以请求授权令牌并使用 API。
curl -X POST 'https://login.partner.microsoftonline.cn/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource=https://monitoring.azure.cn'
响应正文采用以下格式显示:
{
"token_type": "Bearer",
"expires_in": "86399",
"ext_expires_in": "86399",
"expires_on": "1672826207",
"not_before": "1672739507",
"resource": "https://monitoring.azure.cn",
"access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}
验证和检索令牌后,通过包括标头在 Azure Monitor API 请求中使用访问令牌 'Authorization: Bearer <access token>'
注释
有关使用 Azure REST API 的详细信息,请参阅 Azure REST API 参考。
检索资源 ID
使用 REST API 需要目标 Azure 资源的资源 ID。 资源 ID 遵循以下模式:
/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/<provider>/<resource name>/
例如
- Azure IoT 中心:/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Devices/IotHubs/<iot-hub-name>
- 弹性 SQL 池:/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Sql/servers/<pool-db>/elasticpools/<sql-pool-name>
- Azure SQL 数据库(v12):/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Sql/servers/<server-name/databases/<database-name>>
- Azure 服务总线:/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.ServiceBus/<namespace>/<servicebus-name>
- Azure 虚拟机规模集:/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Compute/virtualMachineScaleSets/<vm-name>
- Azure 虚拟机:/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Compute/virtualMachines/<vm-name>
- Azure 事件中心:/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.EventHub/namespaces/<eventhub-namespace>
使用 Azure 门户、PowerShell 或 Azure CLI 查找资源 ID。
- Azure 门户
- PowerShell
- Azure CLI
若要在门户中查找 resourceID,请在资源的概述页中选择 JSON 视图。
将显示“资源 JSON”页。 可以使用 ID 右侧的图标复制资源 ID。
API 端点
API 终结点使用以下模式:
/<resource URI>/providers/microsoft.insights/<metrics|metricDefinitions>?api-version=<apiVersion>
它 resource URI
由以下组件组成:
/subscriptions/<subscription id>/resourcegroups/<resourceGroupName>/providers/<resourceProviderNamespace>/<resourceType>/<resourceName>/
重要
进行 API 调用以检索指标或指标定义时,请务必在资源 URI 后面包含 /providers/microsoft.insights/
。
检索指标定义
使用 Azure Monitor 指标定义 REST API 访问可用于服务的指标列表。 使用以下请求格式检索指标定义。
GET /subscriptions/<subscription id>/resourcegroups/<resourceGroupName>/providers/<resourceProviderNamespace>/<resourceType>/<resourceName>/providers/microsoft.insights/metricDefinitions?api-version=<apiVersion>
Host: management.chinacloudapi.cn
Content-Type: application/json
Authorization: Bearer <access token>
例如,以下请求检索 Azure 存储帐户的指标定义:
curl --location --request GET 'https://management.chinacloudapi.cn/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricDefinitions?api-version=2018-01-01'
--header 'Authorization: Bearer eyJ0eXAiOi...xYz
以下 JSON 显示了一个示例响应正文。 在此示例中,只有第二个指标具有维度:
{
"value": [
{
"id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricdefinitions/UsedCapacity",
"resourceId": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage",
"namespace": "Microsoft.Storage/storageAccounts",
"category": "Capacity",
"name": {
"value": "UsedCapacity",
"localizedValue": "Used capacity"
},
"isDimensionRequired": false,
"unit": "Bytes",
"primaryAggregationType": "Average",
"supportedAggregationTypes": [
"Total",
"Average",
"Minimum",
"Maximum"
],
"metricAvailabilities": [
{
"timeGrain": "PT1H",
"retention": "P93D"
},
...
{
"timeGrain": "PT12H",
"retention": "P93D"
},
{
"timeGrain": "P1D",
"retention": "P93D"
}
]
},
{
"id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricdefinitions/Transactions",
"resourceId": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage",
"namespace": "Microsoft.Storage/storageAccounts",
"category": "Transaction",
"name": {
"value": "Transactions",
"localizedValue": "Transactions"
},
"isDimensionRequired": false,
"unit": "Count",
"primaryAggregationType": "Total",
"supportedAggregationTypes": [
"Total"
],
"metricAvailabilities": [
{
"timeGrain": "PT1M",
"retention": "P93D"
},
{
"timeGrain": "PT5M",
"retention": "P93D"
},
...
{
"timeGrain": "PT30M",
"retention": "P93D"
},
{
"timeGrain": "PT1H",
"retention": "P93D"
},
...
{
"timeGrain": "P1D",
"retention": "P93D"
}
],
"dimensions": [
{
"value": "ResponseType",
"localizedValue": "Response type"
},
{
"value": "GeoType",
"localizedValue": "Geo type"
},
{
"value": "ApiName",
"localizedValue": "API name"
}
]
},
...
]
}
注释
建议使用 API 版本“2018-01-01”或更高版本。 旧版本的指标定义 API 不支持维度。
检索维度值
检索可用指标定义后,检索指标维度的值范围。 使用维度值筛选或分段查询中的指标。 使用 Azure Monitor 指标 REST API 查找给定指标维度的所有值。
在筛选器定义中使用指标的 name.value
元素。 如果未指定筛选器,则返回默认指标。 API 仅允许一个维度具有通配符筛选器。
使用 "resultType=metadata"
查询参数指定维度值的请求。 对于 resultType
指标值请求,省略该参数。
注释
若要使用 Azure Monitor REST API 检索维度值,请使用 API 版本“2019-07-01”或更高版本。
使用以下请求格式检索维度值:
GET /subscriptions/<subscription-id>/resourceGroups/
<resource-group-name>/providers/<resource-provider-namespace>/
<resource-type>/<resource-name>/providers/microsoft.insights/
metrics?metricnames=<metric>
×pan=<starttime/endtime>
&$filter=<filter>
&resultType=metadata
&api-version=<apiVersion> HTTP/1.1
Host: management.chinacloudapi.cn
Content-Type: application/json
Authorization: Bearer <access token>
以下示例检索为 API Name
指标维度发出的维度 Transactions
值列表,其中 GeoType
维度具有指定时间范围的值 Primary
。
curl --location --request GET 'https://management.chinacloudapi.cn/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metrics \
?metricnames=Transactions \
×pan=2023-03-01T00:00:00Z/2023-03-02T00:00:00Z \
&resultType=metadata \
&$filter=GeoType eq \'Primary\' and ApiName eq \'*\' \
&api-version=2019-07-01'
-header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0e..meG1lWm9Y'
以下 JSON 显示了一个示例响应正文:
{
"timespan": "2023-03-01T00:00:00Z/2023-03-02T00:00:00Z",
"value": [
{
"id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/Microsoft.Insights/metrics/Transactions",
"type": "Microsoft.Insights/metrics",
"name": {
"value": "Transactions",
"localizedValue": "Transactions"
},
"unit": "Count",
"timeseries": [
{
"metadatavalues": [
{
"name": {
"value": "apiname",
"localizedValue": "apiname"
},
"value": "DeleteBlob"
}
]
},
{
"metadatavalues": [
{
"name": {
"value": "apiname",
"localizedValue": "apiname"
},
"value": "SetBlobProperties"
}
]
},
...
]
}
],
"namespace": "Microsoft.Storage/storageAccounts",
"resourceregion": "chinanorth"
}
检索指标值
检索指标定义和维度值后,检索指标值。 使用 Azure Monitor 指标 REST API 检索指标值。
在筛选器定义中使用指标的 name.value
元素。 如果未指定维度筛选器,则返回汇总的聚合指标。
多个时序
时序是一组按时间排序的给定维度组合的数据点。 维度是指标的一个方面,用于描述数据点,例如资源 ID、区域或 ApiName。
若要提取具有特定维度值的多个时序,请指定一个筛选器查询参数,该参数指定两个维度值,例如
"&$filter=ApiName eq 'ListContainers' or ApiName eq 'GetBlobServiceProperties'"
。 在此示例中,你将获得一个时序,其中ApiName
是第二个时序ApiName
GetBlobServiceProperties
ListContainers
。若要返回给定维度的每个值的时序,请使用
*
筛选器,例如"&$filter=ApiName eq '*'"
。Top
使用和OrderBy
查询参数来限制和排序返回的时序数。 在此示例中,你将获取结果集中每个值的ApiName
时序。 如果未返回任何数据,API 将返回空时序"timeseries": []
。
注释
若要使用 Azure Monitor REST API 检索多维指标值,请使用 API 版本“2019-07-01”或更高版本。
使用以下请求格式检索指标值:
GET /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/<resource-provider-namespace>/<resource-type>/<resource-name>/providers/microsoft.insights/metrics?metricnames=<metric>×pan=<starttime/endtime>&$filter=<filter>&interval=<timeGrain>&aggregation=<aggreation>&api-version=<apiVersion>
Host: management.chinacloudapi.cn
Content-Type: application/json
Authorization: Bearer <access token>
以下示例按 Transactions
降值顺序检索前三个 API,在 5 分钟范围内,维度 GeoType
的值为 Primary
:
curl --location --request GET 'https://management.chinacloudapi.cn/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metrics \
?metricnames=Transactions \
×pan=2023-03-01T02:00:00Z/2023-03-01T02:05:00Z \
& $filter=apiname eq '\''GetBlobProperties'\'
&interval=PT1M \
&aggregation=Total \
&top=3 \
&orderby=Total desc \
&api-version=2019-07-01"' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer yJ0eXAiOi...g1dCI6Ii1LS'
以下 JSON 显示了一个示例响应正文:
{
"cost": 0,
"timespan": "2023-03-01T02:00:00Z/2023-03-01T02:05:00Z",
"interval": "PT1M",
"value": [
{
"id": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/Microsoft.Insights/metrics/Transactions",
"type": "Microsoft.Insights/metrics",
"name": {
"value": "Transactions",
"localizedValue": "Transactions"
},
"unit": "Count",
"timeseries": [
{
"metadatavalues": [
{
"name": {
"value": "apiname",
"localizedValue": "apiname"
},
"value": "GetBlobProperties"
}
],
"data": [
{
"timeStamp": "2023-09-19T02:00:00Z",
"total": 2
},
{
"timeStamp": "2023-09-19T02:01:00Z",
"total": 1
},
{
"timeStamp": "2023-09-19T02:02:00Z",
"total": 3
},
{
"timeStamp": "2023-09-19T02:03:00Z",
"total": 7
},
{
"timeStamp": "2023-09-19T02:04:00Z",
"total": 2
}
]
},
...
]
}
],
"namespace": "Microsoft.Storage/storageAccounts",
"resourceregion": "chinanorth"
}
一次查询多个资源的指标。
除了查询单个资源的指标之外,某些资源类型还支持在单个请求中查询多个资源。 这些 API 是 Azure 指标资源管理器中多资源体验的强大功能。 可以通过上下文边栏选项卡上范围选择器中的资源类型下拉列表,在 Azure Monitor 的“指标”边栏选项卡上 查看支持查询多个指标的资源类型集。 有关详细信息,请参阅 多资源 UX 文档。
查询多个资源和单个资源的指标之间存在一些重要差异。
- 指标多资源 API 在订阅级别运行,而不是资源 ID 级别。 此限制意味着查询这些 API 的用户必须对订阅本身具有 监视读取者 权限。
- 指标多资源 API 仅支持每个查询的单个 resourceType,该类型必须以指标命名空间查询参数的形式指定。
- 指标多资源 API 仅支持每个查询的单个 Azure 区域,必须以区域查询参数的形式指定。
查询多个资源的指标示例
以下示例显示了单个指标定义请求:
GET https://management.chinacloudapi.cn/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM1/providers/microsoft.insights/metricdefinitions?api-version=2021-05-01
以下请求显示了多个资源的等效指标定义请求。 唯一的更改是订阅路径,而不是资源 ID 路径,以及添加 region
和 metricNamespace
查询参数。
GET https://management.chinacloudapi.cn/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/metricdefinitions?api-version=2021-05-01®ion=chinanorth&metricNamespace=microsoft.compute/virtualmachines
以下示例显示了单个指标请求:
GET https://management.chinacloudapi.cn/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM1/providers/microsoft.Insights/metrics?timespan=2023-06-25T22:20:00.000Z/2023-06-26T22:25:00.000Z&interval=PT5M&metricnames=Percentage CPU&aggregation=average&api-version=2021-05-01
下面是多个资源的等效指标请求:
GET https://management.chinacloudapi.cn/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.Insights/metrics?timespan=2023-06-25T22:20:00.000Z/2023-06-26T22:25:00.000Z&interval=PT5M&metricnames=Percentage CPU&aggregation=average&api-version=2021-05-01®ion=chinanorth&metricNamespace=microsoft.compute/virtualmachines&$filter=Microsoft.ResourceId eq '*'
注释
Microsoft.ResourceId eq '*'
在多资源指标请求示例中添加了筛选器。 该 *
筛选器告知 API 为订阅和区域中具有数据的每个虚拟机资源返回单独的时序。 如果没有筛选器,API 将返回单个时序,聚合所有 VM 的平均 CPU。 每个资源的时序按 Microsoft.ResourceId
每个时序条目的元数据值进行区分,如以下示例返回值所示。 如果此查询未检索 resourceId,则返回空时序"timeseries": []
。
{
"timespan": "2023-06-25T22:35:00Z/2023-06-26T22:40:00Z",
"interval": "PT6H",
"value": [
{
"id": "subscriptions/12345678-abcd-98765432-abcdef012345/providers/Microsoft.Insights/metrics/Percentage CPU",
"type": "Microsoft.Insights/metrics",
"name": {
"value": "Percentage CPU",
"localizedValue": "Percentage CPU"
},
"displayDescription": "The percentage of allocated compute units that are currently in use by the Virtual Machine(s)",
"unit": "Percent",
"timeseries": [
{
"metadatavalues": [
{
"name": {
"value": "Microsoft.ResourceId",
"localizedValue": "Microsoft.ResourceId"
},
"value": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM1"
}
],
"data": [
{
"timeStamp": "2023-06-25T22:35:00Z",
"average": 3.2618888888888886
},
{
"timeStamp": "2023-06-26T04:35:00Z",
"average": 4.696944444444445
},
{
"timeStamp": "2023-06-26T10:35:00Z",
"average": 6.19701388888889
},
{
"timeStamp": "2023-06-26T16:35:00Z",
"average": 2.630347222222222
},
{
"timeStamp": "2023-06-26T22:35:00Z",
"average": 21.288999999999998
}
]
},
{
"metadatavalues": [
{
"name": {
"value": "Microsoft.ResourceId",
"localizedValue": "Microsoft.ResourceId"
},
"value": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM2"
}
],
"data": [
{
"timeStamp": "2023-06-25T22:35:00Z",
"average": 7.567069444444444
},
{
"timeStamp": "2023-06-26T04:35:00Z",
"average": 5.111835883171071
},
{
"timeStamp": "2023-06-26T10:35:00Z",
"average": 10.078277777777778
},
{
"timeStamp": "2023-06-26T16:35:00Z",
"average": 8.399097222222222
},
{
"timeStamp": "2023-06-26T22:35:00Z",
"average": 2.647
}
]
},
{
"metadatavalues": [
{
"name": {
"value": "Microsoft.ResourceId",
"localizedValue": "Microsoft.ResourceId"
},
"value": "/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/Common-TESTING/providers/Microsoft.Compute/virtualMachines/CommonVM1"
}
],
"data": [
{
"timeStamp": "2023-06-25T22:35:00Z",
"average": 6.892319444444444
},
{
"timeStamp": "2023-06-26T04:35:00Z",
"average": 3.5054305555555554
},
{
"timeStamp": "2023-06-26T10:35:00Z",
"average": 8.398817802503476
},
{
"timeStamp": "2023-06-26T16:35:00Z",
"average": 6.841666666666667
},
{
"timeStamp": "2023-06-26T22:35:00Z",
"average": 3.3850000000000002
}
]
}
],
"errorCode": "Success"
}
],
"namespace": "microsoft.compute/virtualmachines",
"resourceregion": "chinanorth"
}
排查查询多个资源的指标问题
返回的空时序
"timeseries": []
- 当没有数据可用于指定的时间范围和筛选器时,将返回空时序。 最常见的原因是指定不包含任何数据的时间范围。 例如,如果时间范围设置为将来的日期。
- 另一个常见原因是指定与任何资源不匹配的筛选器。 例如,如果筛选器指定订阅和区域组合中的任何资源上不存在的维度值,
"timeseries": []
则返回该维度值。
通配符筛选器
使用通配符筛选器(例如
Microsoft.ResourceId eq '*'
,使 API 返回订阅和区域中每个 resourceId 的时序)。 如果订阅和区域组合不包含任何资源,则返回空时序。 没有通配符筛选器的同一查询将返回单个时序,将请求的指标聚合到请求的维度上,例如订阅和区域。401 授权错误
单个资源指标 API 要求用户对要查询的资源具有 监视读取者 权限。 由于多资源指标 API 是订阅级别 API,因此用户必须具有查询订阅的 监视读取者 权限才能使用多资源指标 API。 即使用户对订阅中的所有资源具有监视读取者,如果用户没有订阅本身的监视读取器,请求也会失败。
529 限制错误
529 错误代码指示指标后端当前正在限制请求。 建议的作是实现指数退避重试方案。 有关限制的详细信息,请参阅 Azure 资源管理器如何限制请求。