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

Миграция из API метрик в API getBatch

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

В этой статье приводятся рекомендации по преобразованию существующего metrics:getBatch вызова API метрик в вызов API. Дополнительные сведения о регулировании см. в статье о том, как Azure Resource Manager регулирует запросы.

Формат запроса

Запрос metrics:getBatch API имеет следующий формат:

POST /subscriptions/<subscriptionId>/metrics:getBatch?metricNamespace=<resource type namespace>&api-version=2023-10-01
Host: <region>.metrics.monitor.azure.com
Content-Type: application/json
Authorization: Bearer <token>

{
   "resourceids":[<comma separated list of resource IDs>]
}

Пример:

POST /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch?metricNamespace=microsoft.compute/virtualMachines&api-version=2023-10-01
Host: eastus.metrics.monitor.azure.com
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhb...TaXzf6tmC4jhog

{
    "resourceids":["/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-vms-01/providers/Microsoft.Compute/virtualMachines/vmss-001_41df4bb9",
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/rg-vms-02/providers/Microsoft.Compute/virtualMachines/vmss-001_c1187e2f"]
}

Ограничения пакетной обработки

Рассмотрим следующие ограничения, в которых ресурсы можно пакетировать вместе при выборе metrics:getBatch правильности api для вашего сценария.

  • Все ресурсы в пакете должны находиться в одной подписке.
  • Все ресурсы в пакете должны находиться в одном регионе Azure.
  • Все ресурсы в пакете должны быть одинаковыми типами ресурсов.

Чтобы определить группы ресурсов, которые соответствуют этим критериям, выполните следующий запрос Azure Resource Graph с помощью Обозреватель Azure Resource Graph или API запросов ресурсов Azure Resource Manager.

resources
| project id, subscriptionId, ['type'], location
| order by subscriptionId, ['type'], location

Шаги преобразования запросов

Чтобы преобразовать вызов API существующих метрик в metric:getBatch вызов API, выполните следующие действия.

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

GET https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z&interval=PT6H&metricNamespace=microsoft.storage%2Fstorageaccounts&metricnames=Ingress,Egress&aggregation=total,average,minimum,maximum&top=10&orderby=total desc&$filter=ApiName eq '*'&api-version=2019-07-01

  1. Измените имя узла.

    Замените management.azure.com на региональную конечную точку для плоскости данных метрик Azure Monitor, используя следующий формат: <region>.metrics.monitor.azure.com где region находится регион ресурсов, для которых запрашивается метрика. Например, если ресурсы находятся в westus2, имя узла равно westus2.metrics.monitor.azure.com.

  2. Измените имя и путь API.

    metrics:getBatch API — это API уровня подписки POST. Ресурсы, для которых запрашиваются метрики, указываются в тексте запроса, а не в пути URL-адреса.

    Измените путь URL-адреса следующим образом:

    от /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
    на /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch

  3. Для metricNamespace требуется параметр запроса metrics:getBatch. Для стандартных метрик Azure имя пространства имен обычно является типом ресурса указанных ресурсов. Чтобы проверить используемое значение пространства имен, см. API пространств имен для метрик.

  4. Переключение с использования timespan параметра запроса на использование starttime и endtime. Например, ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z преобразуется в ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Обновите параметр запроса версии API следующим образом: &api-version=2023-10-01

  6. Параметр запроса фильтра в API не имеет префикса $. Измените параметр запроса на $filter=filter=.

  7. metrics:getBatch API — это вызов POST с текстом, который содержит разделенный запятыми список идентификаторов ресурсов в следующем формате:

    Пример:

        {
      "resourceids": [
        // <comma separated list of resource ids>
      ]
    }

    {
  "resourceids": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount"
  ]
}

    В каждом вызове можно указать до 50 уникальных идентификаторов ресурсов. Каждый ресурс должен принадлежать к одной подписке, региону и иметь один и тот же тип ресурса.

Это важно

  • Свойство resourceids объекта в основной части должно быть в нижнем регистре.
  • Убедитесь, что в списке массивов отсутствуют конечные запятые.

Преобразованный пакетный запрос

В следующем примере показан преобразованный пакетный запрос.

POST https://westus2.metrics.monitor.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch?starttime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z&interval=PT6H&metricNamespace=microsoft.storage%2Fstorageaccounts&metricnames=Ingress,Egress&aggregation=total,average,minimum,maximum&top=10&orderby=total desc&filter=ApiName eq '*'&api-version=2023-10-01

{
  "resourceids": [
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount",
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample2-test-rg/providers/Microsoft.Storage/storageAccounts/eax252qtemplate",
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3diag",
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3prefile",
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3tipstorage",
    "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample3backups/providers/Microsoft.Storage/storageAccounts/pod01account1"
  ]
}

Формат ответа

Формат metrics:getBatch ответа API инкапсулирует список ответов на вызовы отдельных метрик в следующем формате:

{
  "values": [
      // <One individual metrics response per requested resourceId>
  ]
}

Свойство resourceid было добавлено в список метрик каждого ресурса в ответе metrics:getBatch API.

Ниже показаны примеры форматов ответов.

{
  "cost": 11516,
  "startime": "2023-04-20T12:00:00Z",
  "endtime": "2023-04-22T12:00:00Z",
  "interval": "P1D",
  "value": [
    {
      "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/Microsoft.Insights/metrics/Ingress",
      "type": "Microsoft.Insights/metrics",
      "name": {
        "value": "Ingress",
        "localizedValue": "Ingress"
      },
      "displayDescription": "The amount of ingress data, in bytes. This number includes ingress from an external client into Azure Storage as well as ingress within Azure.",
      "unit": "Bytes",
      "timeseries": [
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "EntityGroupTransaction"
            }
          ],
          "data": [
            {
              "timeStamp": "2023-04-20T12:00:00Z",
              "total": 1737897,
              "average": 5891.17627118644,
              "minimum": 1674,
              "maximum": 10976
            },
            {
              "timeStamp": "2023-04-21T12:00:00Z",
              "total": 1712543,
              "average": 5946.329861111111,
              "minimum": 1674,
              "maximum": 10980
            }
          ]
        },
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "GetBlobServiceProperties"
            }
          ],
          "data": [
            {
              "timeStamp": "2023-04-20T12:00:00Z",
              "total": 1284,
              "average": 321,
              "minimum": 321,
              "maximum": 321
            },
            {
              "timeStamp": "2023-04-21T12:00:00Z",
              "total": 1926,
              "average": 321,
              "minimum": 321,
              "maximum": 321
            }
          ]
        }
      ],
      "errorCode": "Success"
    },
    {
      "id": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/Microsoft.Insights/metrics/Egress",
      "type": "Microsoft.Insights/metrics",
      "name": {
        "value": "Egress",
        "localizedValue": "Egress"
      },
      "displayDescription": "The amount of egress data. This number includes egress to external client from Azure Storage as well as egress within Azure. As a result, this number does not reflect billable egress.",
      "unit": "Bytes",
      "timeseries": [
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "EntityGroupTransaction"
            }
          ],
          "data": [
            {
              "timeStamp": "2023-04-20T12:00:00Z",
              "total": 249603,
              "average": 846.1118644067797,
              "minimum": 839,
              "maximum": 1150
            },
            {
              "timeStamp": "2023-04-21T12:00:00Z",
              "total": 244652,
              "average": 849.4861111111111,
              "minimum": 839,
              "maximum": 1150
            }
          ]
        },
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "GetBlobServiceProperties"
            }
          ],
          "data": [
            {
              "timeStamp": "2023-04-20T12:00:00Z",
              "total": 3772,
              "average": 943,
              "minimum": 943,
              "maximum": 943
            },
            {
              "timeStamp": "2023-04-21T12:00:00Z",
              "total": 5658,
              "average": 943,
              "minimum": 943,
              "maximum": 943
            }
          ]
        }
      ],
      "errorCode": "Success"
    }
  ],
  "namespace": "microsoft.storage/storageaccounts",
  "resourceregion": "westus2"
}

Изменения ответа на ошибку

В ответе на ошибку содержимое metrics:getBatch ошибки упаковывается в свойство "error" верхнего уровня в ответе. Например

  • Ответ об ошибках API метрик

    {
  "code": "BadRequest",
  "message": "Metric: Ingress does not support requested dimension combination: apiname2, supported ones are: GeoType,ApiName,Authentication, TraceId: {6666aaaa-77bb-cccc-dd88-eeeeee999999}"
}

  • Ответ об ошибке пакетного API:

    {
  "error": {
    "code": "BadRequest",
    "message": "Metric: Egress does not support requested dimension combination: apiname2, supported ones are: GeoType,ApiName,Authentication, TraceId: {6666aaaa-77bb-cccc-dd88-eeeeee999999}"
  }
}

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

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

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

  • Фильтры подстановочных знаков

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

  • Пользовательские метрики в настоящее время не поддерживаются.

    metrics:getBatch API не поддерживает запросы пользовательских метрик или запросов, в которых имя пространства имен метрик не является типом ресурса. Это касается метрик гостевой ОС виртуальной машины, использующих пространство имен "azure.vm.windows.guestmetrics" или "azure.vm.linux.guestmetrics".

  • Верхний параметр применяется к указанному идентификатору ресурса.

    Как параметр top работает в контексте пакетного API может быть немного запутанным. Вместо того чтобы налагать ограничение на суммарный временной ряд, возвращаемый всем вызовом, он применяет ограничение на суммарный временной ряд, возвращаемый на каждую метрику для каждого идентификатора ресурса. Если у вас есть пакетный запрос со многими фильтрами "*", двумя метриками и четырьмя идентификаторами ресурсов с верхней частью 5. Максимально возможное число временных рядов, возвращаемых этим запросом, равно 40, то есть 2x4x5 временных рядов.

Ошибки авторизации 401

Для API отдельных метрик требуется, чтобы у пользователя было разрешение 'Чтение мониторинга' для запрашиваемого ресурса. metrics:getBatch Поскольку API относится к уровню подписки, пользователи должны иметь разрешение на просмотр данных мониторинга для запрашиваемой подписки, чтобы использовать пакетный API. Даже если у пользователей есть средство чтения мониторинга для всех ресурсов, запрашиваемых в пакетном API, запрос завершается ошибкой, если пользователь не имеет средства чтения мониторинга в самой подписке.

Сбои авторизации 403

Это означает, что обязательный поставщик ресурсов не зарегистрирован. См. поставщик ресурсов Microsoft.Insights не зарегистрирован для вашей подписки.

Ошибки ограничения частоты 529

Хотя пакетный API плоскости данных предназначен для устранения проблем дросселирования, коды ошибок 529 всё ещё могут возникать. Эта ошибка означает, что серверная часть метрик в настоящее время ограничивает ваши запросы. Рекомендуемое действие — внедрить механизм повторных попыток с экспоненциальной задержкой. Дополнительные сведения о регулировании см. в статье о том, как Azure Resource Manager регулирует запросы.

Пейджинг

Разбиение по страницам не поддерживается API metrics:getBatch. Наиболее распространённый случай использования этого API — это постоянные вызовы каждые несколько минут для тех же метрик и ресурсов за последний период времени. Низкая задержка является важным фактором, так что многие клиенты параллелизируют свои запросы как можно больше. Разбиение по страницам заставляет клиентов в последовательный шаблон вызова, который приводит к дополнительной задержке запроса. В сценариях, когда запросы возвращают тома данных метрик, где разбиение по страницам будет полезным, рекомендуется разделить запрос на несколько параллельных запросов.

Выставление счетов

Да, все данные метрик и пакетные вызовы в плоскости данных подлежат оплате. Дополнительные сведения см. в разделе "Собственные метрики Azure Monitor" в "Базовые запросы поиска по журналам".

  • Last updated on