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

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

  • Статья

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

В этой статье приводятся рекомендации по преобразованию существующего вызова API метрик в вызов API metrics:getBatch 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 существующих метрик в вызов API metric:getBatch, выполните следующие действия.

Предположим, что для запроса метрик используется следующий вызов 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 метрик: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. Параметр запроса фильтра не префиксируется с помощью $ metrics:getBatch 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".

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

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

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

Ошибки регулирования 529

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

Разбиение на страницы

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

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

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