Прием пользовательских метрик для ресурса Azure с помощью REST API

2025-04-18

В этой статье показано, как отправлять пользовательские метрики для ресурсов Azure в хранилище метрик Azure Monitor через REST API. Когда метрики находятся в Azure Monitor, вы можете выполнять все действия с ними, которые вы делаете со стандартными метриками. Например, можно создавать диаграммы и оповещения, а также направлять метрики другим внешним средствам.

Замечание

REST API позволяет отправлять пользовательские метрики только для ресурсов Azure. Чтобы отправить метрики для ресурсов в других средах или локальной среде, используйте Application Insights.

Отправка запросов REST для приема пользовательских метрик

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

Маркер проверки подлинности
Тема
Регион
Метка времени
Пространство имен
Имя
Ключи измерения
Значения измерения
Значения метрик

Аутентификация

Чтобы отправить пользовательские метрики в Azure Monitor, сущность, которая отправляет метрики, требует допустимого маркера Microsoft Entra в заголовке носителя запроса. Поддерживаемые способы получить действительный маркер носителя включают следующие:

Управляемые удостоверения для ресурсов Azure. Управляемое удостоверение можно использовать для предоставления ресурсам разрешений на выполнение определенных операций. Примером может служить позволение ресурсу публиковать свои собственные метрики. Ресурсу, или его управляемому удостоверению, можно дать разрешение Издатель метрик мониторинга на другой ресурс. С этим разрешением управляемое удостоверение может также выдавать метрики для других ресурсов.
Представитель службы Microsoft Entra. В этом сценарии приложение Microsoft Entra или служба могут быть назначены разрешения на выдачу метрик о ресурсе Azure. Для проверки подлинности запроса Azure Monitor проверяет маркер приложения с помощью открытых ключей Microsoft Entra. Существующая роль Издатель метрик мониторинга уже имеет это разрешение. Доступно на портале Azure.

Основной службе, в зависимости от ресурсов, для которых она отправляет пользовательские метрики, можно предоставить роль Издатель метрик мониторинга на требуемом охвате. Примеры включают подписку, группу ресурсов или конкретный ресурс.

Подсказка

При запросе токена Microsoft Entra для отправки пользовательских метрик убедитесь, что аудитория или ресурс, для которых запрашивается токен, — это https://monitoring.azure.com/. Убедитесь, что URL содержит завершающую косую черту.

Получите токен авторизации

После того как вы создали управляемое удостоверение или принципал службы и назначили разрешения издателя метрик мониторинга, вы можете получить токен авторизации. При запросе указать resource: https://monitoring.azure.comтокен.

Получите токен аутентификации, используя один из следующих методов:

интерфейс командной строки (CLI)
REST API
Пакет SDK

При запросе токена необходимо предоставить параметр resource. Параметр resource является URL-адресом ресурса, к которому вы хотите получить доступ.

Ресурсы включают:

https://management.azure.com
https://api.loganalytics.io
https://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 CLI

** Чтобы получить токен с помощью CLI, вы можете использовать следующую команду.

az account get-access-token

Для получения дополнительной информации см. az account get-access-token

Получите токен с помощью SDK

Примеры кода ниже показывают, как получить токен, используя:

C#
NodeJS
Питон

C#

Следующий код показывает, как получить токен с помощью Azure. Библиотека идентификации требует ID клиента и секрет клиента для аутентификации запроса.

var context = new AuthenticationContext("https://login.microsoftonline.com/<tennant ID>");
var clientCredential = new ClientCredential("<your apps client ID>", "<your apps client secret>");
var result = context.AcquireTokenAsync("https://monitoring.azure.com", clientCredential).Result;

В качестве альтернативы вы можете использовать класс DefaultAzureCredential для получения токена. Этот метод использует учетные данные Azure по умолчанию для аутентификации запроса и не требует идентификатора клиента или секретного ключа клиента.

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Вы также можете указать вашу управляемую идентичность или учетные данные служебного принципала следующим образом:

string userAssignedClientId = "<your managed identity client ID>";
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = userAssignedClientId
    });

var token = credential.GetToken(new TokenRequestContext(new[] { "https://management.azure.com/.default" }));

Для получения дополнительной информации см. DefaultAzureCredential Class

Node.js

Для получения информации об аутентификации с использованием JavaScript и NodeJS см. Как аутентифицировать приложения JavaScript для служб Azure с помощью Azure SDK для JavaScript

В следующем коде показано, как получить токен, используя класс DefaultAzureCredential. Этот метод использует учетные данные Azure по умолчанию для аутентификации запроса и не требует клиента ID или клиентского секрета.

const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const accessToken = await credential.getToken("https://management.azure.com/.default");

Вы также можете использовать класс InteractiveBrowserCredential для получения учетных данных. Этот метод предоставляет пользователям возможность аутентификации через браузер для взаимодействия с сервисами Azure.

Для получения дополнительной информации см. DefaultAzureCredential Class и InteractiveBrowserCredential Class

В качестве альтернативы вы можете использовать класс ClientSecretCredential для получения токена. Данный метод требует идентификатор клиента и секрет клиента для аутентификации запроса.

const { ClientSecretCredential } = require("@azure/identity");
credential = ClientSecretCredential(
    client_id="<client_id>",
    username="<username>",
    password="<password>"
   )
const accessToken = await credential.getToken("https://management.azure.com/.default");

Для получения дополнительной информации см. Класс ClientSecretCredential

Питон

Следующий код показывает, как получить токен с помощью класса DefaultAzureCredential. Этот метод использует учетные данные Azure по умолчанию для аутентификации запроса и не требует идентификатора клиента или клиентского секрета.

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token('https://management.azure.com/.default')
print(token.token)

Вы также можете использовать класс InteractiveBrowserCredential, чтобы получить учетные данные. Этот метод обеспечивает пользователям возможность аутентификации через браузер для работы с сервисами Azure.

Для получения дополнительной информации см. DefaultAzureCredential Class и InteractiveBrowserCredential Class

Как вариант, вы можете использовать класс ClientSecretCredential, чтобы получить токен. Этот метод требует идентификатор клиента и секретный ключ клиента для аутентификации запроса.

from azure.identity import ClientSecretCredential

credential = ClientSecretCredential (
     tenant_id="<tenant id>",
     client_id="<Client id>",
     client_secret="client secret"
    )
token = credential.get_token("https://management.azure.com/.default")
print(token.token)

Для получения дополнительной информации см. ClientSecretCredential Class.

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

Тема

Это свойство объекта содержит ИД ресурса Azure, для которого сообщается пользовательская метрика. Эти сведения кодируются в URL-адресе вызова API. Каждый API может отправлять значения метрик только для одного ресурса Azure.

Замечание

Невозможно задавать пользовательские метрики с использованием идентификатора группы ресурсов или подписки.

Регион

В этом свойстве указывается регион Azure, где развертывается ресурс, для которого отправляются метрики. Метрики должны отправляться в конечную точку Azure Monitor того же региона, в котором развертывается ресурс. Например, пользовательские метрики для виртуальной машины, развернутой в регионе "Западная часть США", должны отправляться в конечную точку Azure Monitor региона "Западная часть США". Сведения о регионе также кодируются в URL-адресе вызова API.

Отметка времени

Каждая точка данных, отправляемая в Azure Monitor, должна быть отмечена временной меткой. Эта метка времени содержит дату и время измерения или получения метрики. Azure Monitor принимает данные метрик с метками времени до 20 минут назад и до 5 минут вперед. Метка времени должна быть указана в формате ISO 8601.

Пространство имен

Пространства имен — это способ классифицировать или группировать аналогичные метрики вместе. С помощью пространств имен можно добиться изоляции между группами метрик, которые могут собирать различные аналитические сведения или показатели производительности. Например, у вас есть пространство имен с именем contosomemorymetrics, отслеживающее метрики использования памяти, которые профилируют приложения. Другое пространство имен, которое называется contosoapptransaction, может отслеживать все метрики о пользовательских транзакциях в приложении.

Имя

Свойство "Имя" — это имя отправляемой метрики. Как правило, оно является достаточно описательным, чтобы указать измеряемый показатель. Пример представляет собой показатель, который измеряет количество байтов памяти, используемых на виртуальной машине. Например, имя метрики Используемые байты памяти.

Ключи измерений

Измерение — это пара "ключ-значение", помогающая описывать другие характеристики собираемой метрики. С помощью других характеристик можно собирать больше данных о метрике, которые предоставляют больше аналитических сведений.

Например, у метрики Используемые байты памяти может быть ключ измерения под названием Процесс, в котором указано, сколько байтов памяти использует каждый процесс на виртуальной машине. Использование этого ключа позволяет фильтровать метрику, чтобы узнать, сколько памяти используют определенные процессы, или получить список 5 процессов, использующих больше всего памяти.

Размеры являются необязательными, и не все метрики их имеют. Пользовательская метрика может содержать до 10 измерений.

Значения измерений

Когда вы сообщаете показатель метрики, каждому ключу измерения в этой метрике соответствует значение измерения. Например, вам нужно сообщить, сколько памяти использует ContosoApp на вашей виртуальной машине:

имя метрики — Используемые байты памяти;
ключ измерения — Процесс;
значение параметра будет ContosoApp.exe.

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

Хотя параметры измерений являются необязательными, если в записи метрики указаны ключи измерений, соответствующие значения этих ключей становятся обязательными.

Значения метрик

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

Чтобы ограничить количество необработанных значений, которые необходимо выдавать и платить за них в Azure Monitor, локально преагрегировать и выдавать агрегированные значения:

Минимум — минимальное наблюдаемое значение из всех образцов или измерений за минуту.
Максимум — максимальное наблюдаемое значение из всех образцов или измерений за минуту.
Сумма — сумма всех наблюдаемых значений из всех образцов или измерений за минуту.
Количество — число образцов или измерений за минуту.

Замечание

Azure Monitor не поддерживает определение единиц для пользовательской метрики.

Допустим, за минуту в вашем приложении произошло четыре транзакции входов, в результате которых были измерены следующие задержки:

Проводка 1	Транзакция 2	Транзакция 3	Транзакция 4
7 мс	4 мс	13 мс	16 мс

Результаты публикации метрики в Azure Monitor будут следующими:

Минимум: 4;
"Максимум": 16;
Сумма: 40
Количество: 4

Если приложение не может локально выполнять предварительную сборку и должно выдавать каждый дискретный пример или событие сразу после сбора, вы можете вывести необработанные значения мер. Например, каждый раз, когда в вашем приложении происходит транзакция входа, вы публикуете метрику в Azure Monitor только с одним измерением. Таким образом, для транзакции входа, выполнение которой заняло 12 миллисекунд, будут опубликованы следующие метрики:

Минимум: 12
"Максимум": 12;
Сумма: 12
Количество: 1.

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

Пример публикации пользовательской метрики

В следующем примере создайте настраиваемую метрику с именем Используемые байты памяти в пространстве имен метрик Профиль памяти для виртуальной машины. У этой метрики есть одно измерение с именем Процесс. Значения метрики для метки времени выводятся для двух процессов.

Сохраните следующий код JSON в файле с именем custommetric.json на локальном компьютере. Обновите параметр времени, чтобы он был в течение последних 20 минут. Вы не можете поместить метрику в магазин, если ей больше 20 минут.

{
    "time": "2024-01-07T11:25:20-7:00",
    "data": {

      "baseData": {

        "metric": "Memory Bytes in Use",
        "namespace": "Memory Profile",
        "dimNames": [
          "Process"
        ],
        "series": [
          {
            "dimValues": [
              "ContosoApp.exe"
            ],
            "min": 10,
            "max": 89,
            "sum": 190,
            "count": 4
          },
          {
            "dimValues": [
              "SalesApp.exe"
            ],
            "min": 10,
            "max": 23,
            "sum": 86,
            "count": 4
          }
        ]
      }
    }
  }

Отправьте следующий HTTP-запрос POST с помощью следующих переменных:

location: регион развертывания ресурса, для который вы генерируете метрики.
resourceId: идентификатор ресурса Azure, за которым вы отслеживаете метрику.

accessToken: токен авторизации, полученный на этапе получения токена авторизации.

curl -X POST 'https://<location>.monitoring.azure.com/<resourceId>/metrics' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <accessToken>' \
-d @custommetric.json

Просмотр метрик

Войдите на портал Azure.
В меню слева выберите Монитор.
На странице Монитор щелкните Метрики.
Измените период агрегирования на Последний час.
В раскрывающемся списке "Область" выберите ресурс, для который вы отправляете метрику.
В раскрывающемся списке пространства имен метрик выберите профиль памяти.
В раскрывающемся списке метрик выберите используемое количество байтов памяти.

Устранение неполадок

Если на любом этапе процесса появится сообщение об ошибке, изучите следующие сведения об устранении неполадок:

Если вы не можете выдавать метрики для подписки, группы ресурсов или конкретного ресурса, убедитесь, что вашему приложению или служебному участнику назначена роль издателя метрик мониторинга в управлении доступом (IAM).
Убедитесь, что число имен измерений соответствует количеству значений.
Убедитесь, что вы отправляете метрики в правильный региональный конечный пункт Azure Monitor. Например, если ресурс развернут в западной части США, необходимо отправить метрики в конечную точку региона Западной части США.
Убедитесь, что метка времени сделана в течение последних 20 минут.
Убедитесь, что метка времени находится в формате ISO 8601.
Проверьте, что имя метрики допустимо. Например, он не может содержать пробелы.

Дальнейшие действия

Дополнительные сведения о настраиваемых метриках см. в этой статье.

Поделиться через

Прием пользовательских метрик для ресурса Azure с помощью REST API

Отправка запросов REST для приема пользовательских метрик

Аутентификация

Получите токен авторизации

Получить токен с помощью REST-запроса

Тема

Регион

Отметка времени

Пространство имен

Имя

Ключи измерений

Значения измерений

Значения метрик

Пример публикации пользовательской метрики

Просмотр метрик

Устранение неполадок

Дальнейшие действия

Обратная связь

Дополнительные ресурсы