Azure 監視 REST API 逐步解說
本文示範如何使用 Azure 監視器 REST API 參考。
使用 Azure 監視器 API 擷取計量定義、維度值和計量值，並在應用程式中使用資料，或儲存在資料庫中進行分析。 您也可以使用 Azure 監視器 API 列出警示規則並檢視活動記錄。
驗證 Azure 監視器要求
使用 Azure 監視器 API 提交的要求會使用 Azure Resource Manager 驗證模型。 所有要求都使用 Microsoft Entra ID 進行驗證。 驗證用戶端應用程式的其中一個方法是建立 Microsoft Entra 服務主體，並擷取驗證權杖。 您可以使用 Azure 入口網站、CLI 或 PowerShell 來建立 Microsoft Entra 服務主體。 如需詳細資訊，請參閱註冊應用程式以要求授權權杖並使用 API。
擷取權杖
建立服務主體之後，呼叫擷取存取權杖。 在權杖要求中指定 resource=https://management.azure.com。
使用下列任何方法來取得驗證權杖：
- CLI
- REST API
- SDK
要求權杖時，您必須提供 resource 參數。 resource 參數是您想要存取的資源的 URL。
這些資源包括：
https://management.azure.comhttps://api.loganalytics.iohttps://monitoring.azure.com
使用 REST 要求取得權杖
使用下列 REST API 呼叫來取得權杖。 此要求會使用用戶端識別碼和用戶端密碼來驗證要求。 當您向 Microsoft Entra ID 註冊應用程式時，會取得用戶端識別碼和用戶端密碼。 如需詳細資訊，請參閱註冊應用程式以要求授權權杖並使用 API
curl -X POST 'https://login.microsoftonline.com/<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.com'
回應本文會以下列格式出現：
{
"token_type": "Bearer",
"expires_in": "86399",
"ext_expires_in": "86399",
"expires_on": "1672826207",
"not_before": "1672739507",
"resource": "https://monitoring.azure.com",
"access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}
驗證和擷取權杖之後，在 Azure 監視器 API 要求中使用存取權杖，方法是包含標頭 'Authorization: Bearer <access token>'
注意
如需使用 Azure REST API 的詳細資訊，請參閱 Azure REST API 參考。
取出資源識別碼
使用 REST API 需要目標 Azure 資源的資源識別碼。 資源識別碼遵循下列模式：
/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 Database (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 來尋找資源識別碼。
若要在入口網站中尋找 resourceID，請從資源的概觀頁面選取 JSON 檢視
[資源 JSON] 頁面隨即顯示。 可以使用識別碼右邊的圖示來複製資源識別碼。
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 監視器計量定義 REST API 來存取可供服務使用的計量清單。 使用以下要求格式來擷取計量定義。
GET /subscriptions/<subscription id>/resourcegroups/<resourceGroupName>/providers/<resourceProviderNamespace>/<resourceType>/<resourceName>/providers/microsoft.insights/metricDefinitions?api-version=<apiVersion>
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer <access token>
例如，下列要求擷取 Azure 儲存體帳戶的計量定義。
curl --location --request GET 'https://management.azure.com/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 監視器計量 REST API 來查找指定計量維度的所有值。
在篩選條件定義中使用計量的 name.value 元素。 如果未指定篩選器，則會傳回預設度量。 此 API 僅允許一個維度具有萬用字元篩選條件。
使用 "resultType=metadata" 查詢參數指定維度值要求。 對於計量值要求，省略 resultType。
注意
若要使用 Azure 監視器 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.azure.com
Content-Type: application/json
Authorization: Bearer <access token>
下列範例擷取 Transactions 計量的 API Name 維度發出的維度值清單，其中指定時間範圍內 GeoType 維度的值為 Primary。
curl --location --request GET 'https://management.azure.com/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": "eastus"
}
取出計量值
擷取計量定義和維度值之後，擷取計量值。 使用 Azure 監視器計量 REST API 來擷取計量值。
在篩選條件定義中使用計量的 name.value 元素。 如果未指定維度篩選條件，則會傳回積存的彙總計量。
多個時間序列
時間序列是一組依時間排序的資料點，並針對特定維度組合進行排序。 維度是一個可描述資料點的計量層面，例如數列資料點、區域或 ApiName。
- 如果要擷取具有特定維度值的多個時間序列，請指定篩選查詢參數以指定兩個維度值，例如
"&$filter=ApiName eq 'ListContainers' or ApiName eq 'GetBlobServiceProperties'"。 在此範例中，您會取得一個時間序列，其中ApiName是ListContainers，第二個時間序列中的ApiName是GetBlobServiceProperties。 - 若要為指定維度每個值傳回時間序列，請使用
*篩選條件，例如"&$filter=ApiName eq '*'"。 使用Top和OrderBy查詢參數來限制和排序傳回的時間序列數目。 在此範例中，您會取得結果中每個ApiName值的時間序列。 如果未傳回任何資料，API 會傳回空的時間序列"timeseries": []。
注意
若要使用 Azure 監視器 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.azure.com
Content-Type: application/json
Authorization: Bearer <access token>
下列範例在 5 分鐘範圍內的 Transactions 值 (遞減順序) 會擷取前三個 API，其中 GeoType 維度的值為 Primary。
curl --location --request GET 'https://management.azure.com/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": "eastus"
}
一次性查詢多個資源的計量。
除了查詢個別資源的計量之外，某些資源類型也支援在單一要求中查詢多個資源。 這些 API 為 Azure 計量總管中的多資源體驗提供支援。 您可以透過內容刀鋒視窗上範圍選取器中的資源類型下拉式清單，在 Azure 監視器的 [計量] 刀鋒視窗上查看支持查詢多個計量的資源類型集。 如需詳細資訊，請參閱多資源 UX 文件。
查詢多個和個別資源的計量之間存在一些重要差異。
- 計量多資源 API 會在訂用帳戶層級運作，而不是資源識別碼層級。 這項限制表示查詢這些 API 的使用者必須擁有訂用帳戶本身的監視讀取器權限。
- 計量多資源 API 僅支援每個查詢的單一 resourceType，該資源類型必須以計量命名空間查詢參數的形式指定。
- 計量多資源 API 僅支援每個查詢的單一 Azure 區域，該區域必須以區域查詢參數的形式指定。
查詢多個資源的計量範例
下列範例顯示了個別計量定義要求：
GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/resourceGroups/EASTUS-TESTING/providers/Microsoft.Compute/virtualMachines/TestVM1/providers/microsoft.insights/metricdefinitions?api-version=2021-05-01
下列要求顯示了多個資源的對等用法計量定義要求。
唯一的變更是訂用帳戶路徑，而不是資源識別碼路徑，以及新增 region 和 metricNamespace 查詢參數。
GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/metricdefinitions?api-version=2021-05-01®ion=eastus&metricNamespace=microsoft.compute/virtualmachines
下列範例顯示了個別計量要求。
GET https://management.azure.com/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.azure.com/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=eastus&metricNamespace=microsoft.compute/virtualmachines&$filter=Microsoft.ResourceId eq '*'
注意
範例中已新增針對多資源計量要求的 Microsoft.ResourceId eq '*' 篩選條件。 * 篩選條件會告訴 API 在訂用帳戶和區域中為每個擁有資料的虛擬機資源傳回個別時間序列。 如果沒有篩選條件，API 會傳回匯總所有 VM 的平均 CPU 的單一時間序列。 每個資源的時間序列會依每個時間序列項目上的 Microsoft.ResourceId 中繼資料值來區分，如下列範例傳回值所示。 如果此查詢沒有擷取到 resourceIds，則會傳回空的時間序列 "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": "eastus"
}
針對查詢多個資源的計量進行疑難排解
傳回的空時間序列
"timeseries": []- 當指定的時間範圍和篩選條件沒有可用資料時，會傳回空的時間序列。 最常見的原因是指定了不包含任何資料的時間範圍。 例如，如果時間範圍設定為未來的日期。
- 另一個常見原因是指定的篩選條件不符合任何資源。 例如，如果篩選條件指定訂用帳戶和區域組合中任何資源上都不存在的維度值，則會傳回
"timeseries": []。
萬用字元篩選
使用萬用字元篩選，例如Microsoft.ResourceId eq '*'，會導致 API 傳回訂用帳戶和區域中每個 resourceId 的時間序列。 如果訂用帳戶和區域組合不包含任何資源，則會傳回空的時間序列。 沒有萬用字元篩選的相同查詢會傳回單一時間序列，在要求的維度上 (例如訂用帳戶和區域) 彙總要求的計量。401 授權錯誤：
個別資源計量 API 要求使用者要查詢的資源具有監視讀取器權限。 由於多資源計量 API 是訂用帳戶層級 API，因此使用者必須對查詢的訂用帳戶具有監視讀取器權限，才能使用多資源計量 API。 即使使用者在訂用帳戶中的所有資源具有監視讀取器權限，如果使用者對訂用帳戶本身沒有該權限，則要求也會失敗。
下一步
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應