Partilhar 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. A migração para a metrics:getBatch API 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 do pedido

A metrics:getBatch solicitação de API 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 lotes

Considere as seguintes restrições sobre quais recursos podem ser agrupados em lote ao decidir se a metrics:getBatch API é a escolha correta 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 do Azure Resource Graph usando o Azure Resource Graph Explorer ou por meio da API de consulta Recursos do Azure Resource Manager.

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

Solicitar etapas de conversão

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

Suponha que a seguinte chamada de 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 do Azure Monitor Metrics usando o seguinte formato: <region>.metrics.monitor.azure.com onde 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 metrics:getBatch API é uma API POST de 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 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 metricNamespace parâmetro de consulta é necessário para metrics:getBatch. Para métricas padrão do Azure, o nome do namespace geralmente é o tipo de recurso dos recursos especificados. Para verificar o valor do namespace a ser usado, consulte a API de namespaces de métricas

  4. Alterne de usar o timespan parâmetro de consulta para usar starttime e endtime. Por exemplo, ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z passa a ?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 metrics:getBatch API. Altere a parada de consulta de $filter= para filter=.

  7. A metrics:getBatch API é 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 recursos exclusivos podem ser especificados em cada chamada. Cada recurso deve pertencer à mesma assinatura, região e ser do mesmo tipo de recurso.

Importante

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

Solicitação de lote convertida

O exemplo a seguir mostra a solicitação de 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 metrics:getBatch API encapsula uma lista de respostas de chamada de métricas individuais no seguinte formato:

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

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

A seguir mostram formatos de resposta de exemplo.

{
  "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 na resposta a erros

Na resposta de metrics:getBatch erro, o conteúdo do erro é encapsulado dentro de uma propriedade "error" de nível superior 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 em 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}"
  }
}

Resoluçã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 filtro especificados. A causa mais comum é especificar um intervalo de tempo que não contém dados. Por exemplo, se o intervalo de tempo estiver definido para uma data futura.
    • Outra causa comum é especificar um filtro que não corresponde a nenhum recurso. Por exemplo, se o filtro especificar um valor de dimensão que não existe em nenhum recurso na combinação de assinatura e região, "timeseries": [] será retornado.

  • Filtros curinga
    O uso de um filtro 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 de assinatura e região não contiver recursos, uma série temporal vazia será retornada. A mesma consulta sem o filtro curinga retornaria uma única série temporal, agregando a métrica solicitada sobre as dimensões solicitadas, por exemplo, assinatura e região.

  • Atualmente, não há suporte para métricas personalizadas.
    A metrics:getBatch API não oferece suporte à consulta de métricas personalizadas ou consultas em que o nome do namespace da métrica não é um tipo de recurso. Este é o caso das métricas do SO convidado da VM que usam o namespace "azure.vm.windows.guestmetrics" ou "azure.vm.linux.guestmetrics".

  • O parâmetro superior aplica-se por ID de recurso especificado.
    Como o parâmetro superior funciona no contexto da API em lote pode ser um pouco confuso. Em vez de impor um limite para a série temporal total retornada pela chamada inteira, ele 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 recursos com um topo de 5. A série temporal máxima possível retornada por essa consulta é 40, ou seja, uma série temporal 2x4x5.

401 erros de autorização

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

529 erros de limitação

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

Paginação

A paginação não é suportada pela API metrics:getBatch. O caso de uso mais comum para essa API é chamar frequentemente a cada poucos minutos para as mesmas métricas e recursos para o período de tempo mais recente. A baixa latência é uma consideração importante, então muitos clientes paralelizam suas consultas tanto quanto 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 métricos em que a paginação seria benéfica, é recomendável dividir a consulta em várias consultas paralelas.

Faturação

Sim, todas as métricas, plano de dados e chamadas em lote 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.