Пошаговое руководство по REST API Azure Monitor

  • Статья

В этой статье показано, как использовать справочник по REST API Azure Monitor.

Получение определений метрик, значений измерений и значений метрик с помощью API Azure Monitor и использование данных в приложениях или хранение в базе данных для анализа. Вы также можете перечислять правила генерации оповещений и просматривать журналы действий с помощью API Azure Monitor.

Аутентификация запросов Azure Monitor

Запрос, отправленный с помощью API Azure Monitor, использует модель проверки подлинности Azure Resource Manager. Все запросы проходят проверку подлинности с помощью идентификатора Microsoft Entra. Одним из способов проверки подлинности клиентского приложения является создание субъекта-службы Microsoft Entra и получение маркера проверки подлинности. Субъект-службу Microsoft Entra можно создать с помощью портал Azure, CLI или PowerShell. Дополнительные сведения см. в разделе "Регистрация приложения" для запроса маркеров авторизации и работы с API.

Получение маркера

После создания субъекта-службы получите маркер доступа с помощью вызова REST. Отправьте следующий запрос с помощью appIdpassword субъекта-службы или приложения:


    POST /<tenant-id>/oauth2/token
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=client_credentials
    &client_id=<app-client-id>
    &resource=https://management.azure.com
    &client_secret=<password>

Например.

curl --location --request POST 'https://login.microsoftonline.com/abcd1234-5849-4a5d-a2eb-5267eae1bbc7/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=0123b56a-c987-1234-abcd-1a2b3c4d5e6f' \
--data-urlencode 'client_secret=123456.ABCDE.~XYZ876123ABceDb0000' \
--data-urlencode 'resource=https://management.azure.com'

Успешный запрос получает маркер доступа в ответе:

{
   token_type": "Bearer",
   "expires_in": "86399",
   "ext_expires_in": "86399",
   "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax"
}

После проверки подлинности и получения маркера используйте маркер доступа в запросах API Azure Monitor, включив заголовок. 'Authorization: Bearer <access token>'

Примечание.

Дополнительные сведения о работе с REST API Azure см. в справочнике по REST API Azure.

Получение идентификатора ресурса

Для использования REST API требуется идентификатор ресурса целевого ресурса Azure. Идентификаторы ресурсов соответствуют следующему шаблону:

/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/<provider>/<resource name>/

Например.

  • Центр Интернета вещей Azure: /subscriptions/<subscription-id>/resourceGroups/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>
  • База данных SQL Azure (версия 12): /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.Sql/servers</server-name>/database/database-name<>
  • Служебная шина Azure: /subscriptions/<subscription-id>/resourceGroups/<resourceGroups/resource-group-name>/providers/Microsoft.ServiceBus/<namespace>/<servicebus-name>
  • Azure Масштабируемые наборы виртуальных машин: /subscriptions/<subscription-id>/resourceGroups/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/resourceGroups/<resource-group-name>/providers/Microsoft.EventHub/namespaces/<eventhub-namespace>

Используйте портал Azure, PowerShell или Azure CLI для поиска идентификатора ресурса.

Чтобы найти идентификатор ресурса на портале, на странице обзора ресурса выберите представление JSONA screenshot showing the overview page for a resource with the JSON view link highlighted.

Отображается страница JSON ресурса. Идентификатор ресурса можно скопировать с помощью значка справа от идентификатора.

A screenshot showing the Resource JSON page for a resource.

Конечные точки API

Конечные точки API используют следующий шаблон:
/<resource URI>/providers/microsoft.insights/<metrics|metricDefinitions>?api-version=<apiVersion>
Состоит resource URI из следующих компонентов:
/subscriptions/<subscription id>/resourcegroups/<resourceGroupName>/providers/<resourceProviderNamespace>/<resourceType>/<resourceName>/

Внимание

Не забудьте включить /providers/microsoft.insights/ после URI ресурса при вызове API для получения метрик или определений метрик.

Получение определений метрик

Используйте REST API определений метрик Azure Monitor для доступа к списку метрик, которые доступны для службы. Используйте следующий формат запроса для получения определений метрик.

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 определений метрик не поддерживают измерения.

Получение значений измерений

После получения доступных определений метрик получите диапазон значений измерений метрик. Используйте значения измерений для фильтрации или сегментирования метрик в запросах. Используйте REST API метрик Azure Monitor, чтобы найти все значения для заданного измерения метрик.

Используйте элемент метрики name.value в определениях фильтров. Если не указано ни одного фильтра, возвращается метрика по умолчанию. API позволяет только одному измерению иметь дикий фильтр карта. Укажите запрос значений "resultType=metadata" измерений с помощью параметра запроса. Опущен resultType для запроса значений метрик.

Примечание.

Чтобы получить значения измерений с помощью REST API Azure Monitor, используйте в качестве версии 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>  
&timespan=<starttime/endtime>  
&$filter=<filter>  
&resultType=metadata  
&api-version=<apiVersion>   HTTP/1.1
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer <access token>

В следующем примере извлекается список значений измерений, которые были созданы для API Name измерения Transactions метрики, где 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 \
&timespan=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"
}

Получение значений метрик

После получения определений метрик и значений измерений получите значения метрик. Для получения значений метрик и используйте REST API метрик Azure Monitor.

Используйте элемент метрики name.value в определениях фильтров. Если фильтры измерений не указаны, свернутый, возвращается агрегированная метрика.

Чтобы получить несколько временных рядов с определенными значениями измерений, укажите параметр фильтра запроса, который задает значения обоих измерений, например "&$filter=ApiName eq 'ListContainers' or ApiName eq 'GetBlobServiceProperties'".

Чтобы вернуть временные ряды для каждого значения определенного измерения, используйте фильтр *, например "&$filter=ApiName eq '*'". Параметры запроса Top и OrderBy можно использовать для ограничения числа и упорядочения возвращаемых временных рядов.

Примечание.

Чтобы получить значения многомерных метрик с помощью REST API Azure Monitor, используйте в качестве версии 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>&timespan=<starttime/endtime>&$filter=<filter>&interval=<timeGrain>&aggregation=<aggreation>&api-version=<apiVersion>
Host: management.azure.com
Content-Type: application/json
Authorization: Bearer <access token>

В следующем примере извлекаются три верхних API по количеству Transactions в порядке убывания значений в течение 5-минутного диапазона, где 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 \
&timespan=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 Monitor с помощью раскрывающегося списка типов ресурсов в селекторе область в колонке контекста. Дополнительные сведения см. в документации по UX с несколькими ресурсами.

Существуют некоторые важные различия между метриками запроса для нескольких и отдельных ресурсов.

  • API-интерфейсы многоресурсных метрик работают на уровне подписки, а не на уровне идентификатора ресурса. Это ограничение означает, что пользователи, запрашивающие эти 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

В следующем запросе показан эквивалентный запрос определений метрик для нескольких ресурсов. Единственными изменениями являются путь подписки вместо пути идентификатора ресурса и добавление regionmetricNamespace параметров запроса.

GET https://management.azure.com/subscriptions/12345678-abcd-98765432-abcdef012345/providers/microsoft.insights/metricdefinitions?api-version=2021-05-01&region=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&region=eastus&metricNamespace=microsoft.compute/virtualmachines&$filter=Microsoft.ResourceId eq '*'

Примечание.

Фильтр Microsoft.ResourceId eq '*' добавляется в пример для запросов многометрических метрик ресурсов. Фильтр сообщает API возвращать отдельные временные ряды для каждого ресурса виртуальной машины в подписке и регионе. Без фильтра API возвращает один временный ряд, агрегирующий средний ЦП для всех виртуальных машин. Временные ряды для каждого ресурса различаются по Microsoft.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": "eastus"
}

Устранение неполадок с запросами метрик для нескольких ресурсов

  • Возвращен пустой временный ряд "timeseries": []

    • Пустой временный ряд возвращается, если данные не доступны для указанного диапазона времени и фильтра. Наиболее распространенная причина заключается в указании диапазона времени, который не содержит никаких данных. Например, если для диапазона времени задана дата будущего.
    • Еще одна распространенная причина заключается в указании фильтра, не соответствующего ресурсам. Например, если фильтр задает значение измерения, которое не существует для ресурсов в сочетании подписок и регионов, "timeseries": [] возвращается.

  • Дикие фильтры карта
    Использование дикого фильтра карта например, приводит к тому, что Microsoft.ResourceId eq '*' API возвращает временные ряды для каждого идентификатора ресурса в подписке и регионе. Если сочетание подписки и региона не содержит ресурсов, возвращается пустой временный ряд. Тот же запрос без дикого фильтра карта вернет один временный ряд, агрегируя запрошенную метрику по запрошенным измерениям, например подписку и регион. Если в сочетании подписок и регионов нет ресурсов, API возвращает один временный ряд с одной точкой 0данных.

  • Ошибки авторизации 401:
    Для API отдельных метрик ресурсов требуется, чтобы у пользователя было разрешение средства чтения мониторинга для запрашиваемого ресурса. Так как API метрики с несколькими ресурсами являются API уровня подписки, пользователи должны иметь разрешение средства чтения мониторинга для запрашиваемой подписки, чтобы использовать API метрик с несколькими ресурсами. Даже если у пользователей есть средство чтения мониторинга для всех ресурсов в подписке, запрос завершается ошибкой, если пользователь не имеет средства чтения мониторинга в самой подписке.

Следующие шаги