Compartir a través de

Cómo migrar desde la API de métricas a la API getBatch

  • Artículo

El uso intensivo de la API de métricas puede dar lugar a problemas de limitación o rendimiento. Migrar a la API metrics:getBatch le permite consultar múltiples recursos en una única solicitud REST. Las dos API comparten un conjunto común de parámetros de consulta y formatos de respuesta que facilitan la migración.

Formato de solicitud

La solicitud a la API metrics:getBatch tiene el formato siguiente:

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 ejemplo,

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

Restricciones de procesamiento por lotes

Tenga en cuenta las siguientes restricciones sobre qué recursos se pueden agrupar por lotes al decidir si la API metrics:getBatch es la opción correcta para su escenario.

  • Todos los recursos de un lote deben estar en la misma suscripción.
  • Todos los recursos de un lote deben estar en la misma región de Azure.
  • Todos los recursos de un lote deben ser el mismo tipo de recurso.

Para ayudar a identificar grupos de recursos que cumplan estos criterios, ejecute la siguiente consulta de Azure Resource Graph mediante Azure Resource Graph Explorer o a través de la API de consulta de recursos de Azure Resource Manager.

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

Pasos de conversión de solicitud

Para convertir una llamada API de métricas existente a una llamada API metric:getBatch, siga estos pasos:

Supongamos que se usa la siguiente llamada API 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. Cambie el nombre de host.
    Reemplace management.azure.com por un punto de conexión regional para el plano de datos Métricas de Azure Monitor con el siguiente formato: <region>.metrics.monitor.azure.com donde region es la región de los recursos para los que está solicitando métricas. Por ejemplo, si los recursos están en westus2, el nombre de host es westus2.metrics.monitor.azure.com.

  2. Cambie el nombre y la ruta de acceso de la API.
    La API metrics:getBatch es una API POST de nivel de suscripción. Los recursos para los que se solicitan las métricas se especifican en el cuerpo de la solicitud en lugar de en la ruta de acceso de la URL.
    Cambie la ruta de acceso de la URL de la siguiente manera:
    de /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
    a /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch

  3. El parámetro metricNamespace de consulta es necesario para metrics:getBatch. En el caso de las métricas estándar de Azure, el nombre del espacio de nombres suele ser el tipo de recurso de los recursos especificados. Para comprobar el valor del espacio de nombres que se va a usar, consulte la API de espacio de nombres de métricas

  4. Cambio del uso del parámetro de consulta timespan por el uso de starttime y endtime. Por ejemplo, ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z se convierte en ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Actualice el parámetro de consulta api-version de la siguiente manera: &api-version=2023-10-01

  6. El parámetro de consulta de filtro no tiene el prefijo $ en la API metrics:getBatch. Cambie el parámetro de consulta de $filter= a filter=.

  7. La API metrics:getBatch es una llamada POST con un cuerpo que contiene una lista separada por comas de resourceIds en el siguiente formato, por ejemplo:

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

    Por ejemplo:

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

Se pueden especificar hasta 50 id. de recursos únicos en cada llamada. Cada recurso debe pertenecer a la misma suscripción, región y ser del mismo tipo de recurso.

Importante

  • La propiedad resourceids de objeto del cuerpo debe estar en minúsculas.
  • Asegúrese de que no haya comas finales en el último resourceid de la lista de matrices.

Solicitud por lotes convertida

En el ejemplo siguiente se muestra la solicitud por lotes 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 de respuesta

El formato de respuesta de la API metrics:getBatch encapsula una lista de respuestas de llamadas de métricas individuales en el siguiente formato:

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

Se agregó una propiedad resourceid a la lista de métricas de cada recurso en la respuesta de la API metrics:getBatch.

A continuación se muestran formatos de respuesta de ejemplo.

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

Cambios de respuesta de error

En la respuesta de error metrics:getBatch, el contenido del error se ajusta dentro de una propiedad de nivel superior "error" en la respuesta. Por ejemplo,

  • Respuesta de error de la 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}"
}

  • Respuesta de error de la API de 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}"
  }
}

Solución de problemas

  • Serie temporal vacía devuelta "timeseries": []

    • Se devuelve una serie temporal vacía cuando no hay datos disponibles para el intervalo de tiempo y el filtro especificados. La causa más común es especificar un intervalo de tiempo que no contiene datos. Por ejemplo, si el intervalo de tiempo se establece en una fecha futura.
    • Otra causa común es especificar un filtro que no coincide con ningún recurso. Por ejemplo, si el filtro especifica un valor de dimensión que no existe en ningún recurso de la combinación de suscripción y región, se devuelve "timeseries": [].

  • Filtros de carácter comodín
    El uso de un filtro de carácter comodín, como Microsoft.ResourceId eq '*', hace que la API devuelva una serie temporal para cada resourceId de la suscripción y la región. Si la combinación de suscripción y región no contiene recursos, se devuelve una serie temporal vacía. La misma consulta sin el filtro de carácter comodín devolvería una sola serie temporal, agregando la métrica solicitada sobre las dimensiones solicitadas, por ejemplo, suscripción y región.

  • Actualmente no se admiten métricas personalizadas.
    La API metrics:getBatch no admite la consulta de métricas personalizadas ni las consultas en las que el nombre del espacio de nombres de métrica no es un tipo de recurso. Este es el caso de las métricas del SO invitado de máquina virtual que usan el espacio de nombres "azure.vm.windows.guestmetrics" o "azure.vm.linux.guestmetrics".

  • El parámetro superior se aplica por id. de recurso especificado.
    El funcionamiento del parámetro superior en el contexto de la API de lote puede ser un poco confuso. En lugar de imponer un límite a la serie temporal total devuelta por toda la llamada, impone la serie temporal total devuelta por métrica y por id. de recurso. Si tiene una consulta por lotes con muchos filtros "*" especificados, dos métricas y cuatro id. de recurso con una parte superior de 5. La serie temporal máxima posible devuelta por esa consulta es 40, es decir, serie temporal 2 x 4 x 5.

Errores de autorización 401

La API de métricas individuales requiere que un usuario tenga el permiso Lector de supervisión en el recurso que se está consultando. Dado que la API metrics:getBatch es una API de nivel de suscripción, los usuarios deben tener el permiso Lector de supervisión para que la suscripción consultada use la API de lote. Incluso si los usuarios tienen el Lector de supervisión en todos los recursos que se están consultando en la API de lote, se produce un error en la solicitud si el usuario no tiene un Lector de supervisión en la propia suscripción.

529 errores de limitación

Aunque la API de lote del plano de datos está diseñada para ayudar a mitigar los problemas de limitación, aún pueden producirse códigos de error 529 que indican que el back-end de métricas está limitando actualmente a algunos clientes. La acción recomendada es implementar un esquema de reintentos de retroceso exponencial.

Paginación

La paginación no es compatible con la API metrics:getBatch. El caso de uso más común para esta API es llamar frecuentemente cada pocos minutos para obtener las mismas métricas y recursos para el período de tiempo más reciente. La baja latencia es una consideración importante, por lo que muchos clientes paralelizan sus consultas todo lo posible. La paginación fuerza a los clientes a un patrón de llamada secuencial que introduce una latencia de consulta adicional. En escenarios en los que las solicitudes devuelven volúmenes de datos de métricas en los que la paginación sería beneficiosa, se recomienda dividir la consulta en varias consultas paralelas.

Facturación

Sí, se facturan todas llamadas de plano de datos y procesamiento por lotes de métricas. Para obtener más información, consulte la sección Métricas nativas de Azure Monitor en Consultas básicas de búsqueda de registros.