Compartilhar via

Como migrar da API de métricas para a API getBatch

  • Artigo

O uso intenso da API de métricas pode resultar em problemas de limitação ou desempenho. Migrar para a API metrics:getBatch permite que você consulte vários recursos em uma única solicitação REST. As duas APIs compartilham um conjunto comum de parâmetros de consulta e formatos de resposta que facilitam a migração.

Formato de solicitação

A solicitação da API metrics:getBatch tem o seguinte formato:

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>]
}

Por exemplo,

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"
]
}

Restrições de envio em lote

Pense nas seguintes restrições sobre quais recursos podem ser agrupados em lote ao decidir se a API metrics:getBatch é a melhor escolha para seu cenário.

  • Todos os recursos em um lote devem estar na mesma assinatura.
  • Todos os recursos em um lote devem estar na mesma região do Azure.
  • Todos os recursos em um lote devem ser do mesmo tipo de recurso.

Para ajudar a identificar grupos de recursos que atendem a esses critérios, execute a seguinte consulta de Resource Graph do Azure usando o Resource Graph Explorer do Azure ou por meio da API de consulta do Azure Resource Manager Resources.

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

Etapas de conversão de solicitação

Para converter uma chamada à API de métricas existente em uma chamada à API metric:getBatch, siga estas etapas:

Suponha que a seguinte chamada à API esteja sendo usada para solicitar métricas:

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. Altere o nome do host.
    Substitua management.azure.com por um ponto de extremidade regional para o plano de dados Métricas do Azure Monitor usando o seguinte formato: <region>.metrics.monitor.azure.com em que region é a região dos recursos para os quais você está solicitando métricas. Por exemplo, se os recursos estiverem em westus2, o nome do host será westus2.metrics.monitor.azure.com.

  2. Altere o nome e o caminho da API.
    A API metrics:getBatch é uma API POST em nível de assinatura. Os recursos para os quais as métricas são solicitadas são especificados no corpo da solicitação e não no caminho da URL.
    Altere o caminho da URL da seguinte maneira:
    de /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
    para /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch

  3. O parâmetro de consulta metricNamespace é necessário para metrics:getBatch. Para as métricas padrão do Azure, o nome do namespace costuma ser o tipo de recurso dos recursos que você especificou. Para marcar o valor do namespace a ser usado, consulte a API de namespaces de métricas

  4. Alterne o uso do parâmetro de consulta timespan para starttime e endtime. Por exemplo, ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z se tornará ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Atualize o parâmetro de consulta api-version da seguinte maneira: &api-version=2023-10-01

  6. O parâmetro de consulta de filtro não é prefixado com um $ na API metrics:getBatch. Altere o parâmetro de consulta de $filter= para filter=.

  7. A API metrics:getBatch é uma chamada POST com um corpo que contém uma lista separada por vírgulas de resourceIds no seguinte formato: Por exemplo:

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

    Por exemplo:

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

Até 50 IDs de recurso exclusivas podem ser especificadas em cada chamada. Cada recurso deve pertencer à mesma assinatura, região e ser do mesmo tipo de recurso.

Importante

  • A propriedade resourceids do objeto no corpo deve ser minúscula.
  • Verifique se não há vírgulas à direita em seu último resourceid na lista de matrizes.

Solicitação em lote convertida

O exemplo a seguir mostra a solicitação em lote convertida.

    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"
      ]
    }

Formato da resposta

O formato de resposta da API metrics:getBatch encapsula uma lista de respostas de chamadas de métricas individuais no seguinte formato:

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

Uma propriedade resourceid foi adicionada à lista de métricas de cada recurso na resposta da API metrics:getBatch.

Os seguintes exemplos de formatos de resposta são mostrados.

{
  "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"
}

Alterações de resposta de erro

Na resposta de erro de metrics:getBatch, o conteúdo do erro é encapsulado dentro de uma propriedade "erro" de alto nível na resposta. Por exemplo,

  • Resposta de erro da API de métricas

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

  • Resposta de erro da API do Lote:

    {
  "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}"
  }
}

Solução de problemas

  • Série temporal vazia retornada "timeseries": []

    • Uma série temporal vazia é retornada quando nenhum dado está disponível para o intervalo de tempo e o filtro especificados. A causa mais comum é a especificação de um intervalo de tempo que não contém nenhum dado. Por exemplo, se o intervalo de tempo estiver definido para uma data futura.
    • Outra causa comum é a especificação de um filtro que não corresponda a nenhum recurso. Por exemplo, se o filtro especificar um valor de dimensão que não existe em nenhum recurso na combinação entre assinatura e região, "timeseries": [] será retornado.

  • Filtros de caracteres curinga
    Usar um filtro de caracteres curinga, como Microsoft.ResourceId eq '*', faz com que a API retorne uma série temporal para cada resourceId na assinatura e região. Se a combinação entre assinatura e região não contiver nenhum recurso, uma série temporal vazia será retornada. A mesma consulta sem o filtro de caracteres curinga retornaria uma única série temporal, agregando a métrica solicitada nas dimensões solicitadas, como, por exemplo, assinatura e região.

  • Métricas personalizadas não são compatíveis atualmente.
    A API metrics:getBatch não dá suporte à consulta de métricas personalizadas ou consultas em que o nome do namespace da métrica não seja um tipo de recurso. Esse é o caso das métricas do sistema operacional convidado da VM que usam o namespace "azure.vm.windows.guestmetrics" ou "azure.vm.linux.guestmetrics".

  • O parâmetro superior se aplica por ID de recurso especificada.
    Como o parâmetro superior funciona no contexto da API de lote pode ser um pouco confuso. Em vez de impor um limite na série temporal total retornada por toda a chamada, ela impõe a série temporal total retornada por métrica por ID de recurso. Se você tiver uma consulta em lote com muitos filtros '*' especificados, duas métricas e quatro IDs de recurso com uma parte superior de 5. A série temporal máxima possível retornada por essa consulta é 40, ou seja, série temporal 2x4x5.

401 erros de autorização

A API de métricas individuais requer que um usuário tenha a permissão Leitor de Monitoramento no recurso que está sendo consultado. Como a API metrics:getBatch é uma API no nível da assinatura, os usuários precisam ter a permissão de Leitor de Monitoramento para que a assinatura consultada use a API de lote. Mesmo que os usuários tenham o Leitor de Monitoramento em todos os recursos que estão sendo consultados na API do lote, a solicitação falhará se o usuário não tiver o Leitor de Monitoramento na própria assinatura.

529 erros de limitação

Embora a API de lote do plano de dados seja projetada para ajudar a atenuar problemas de limitação, 529 códigos de erro ainda podem ocorrer, o que indica que o back-end de métricas está limitando alguns clientes no momento. A ação recomendada é implementar um esquema de repetição de retirada exponencial.

Paginamento

A paginação não é compatível com a API metrics:getBatch. O caso de uso mais comum para essa API é chamar com frequência a cada poucos minutos as mesmas métricas e recursos para o período mais recente. A baixa latência é uma consideração importante para que muitos clientes paralelizem suas consultas o máximo possível. A paginação força os clientes a um padrão de chamada sequencial que introduz latência de consulta adicional. Em cenários em que as solicitações retornam volumes de dados de métrica em que a paginação seria benéfica, é recomendável dividir a consulta em várias consultas paralelas.

Cobrança

Sim, todas as chamadas de plano de dados e envio em lote de métricas são cobradas. Para obter mais informações, consulte a seção Métricas nativas do Azure Monitor em Consultas Básicas de Pesquisa de Log.