Partager via

Migrer de l’API de métriques vers l’API getBatch

  • Article

L’utilisation intensive de l’API de métriques peut entraîner des problèmes de limitation ou de performances. La migration vers l’API metrics:getBatch vous permet d’interroger plusieurs ressources dans une seule requête REST. Les deux API partagent un ensemble commun de paramètres de requête et de formats de réponse qui facilitent la migration.

Format de la demande

L’API de requête metrics:getBatch dispose du format suivant :

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

Par exemple,

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

Restrictions liées au traitement par lot

Tenez compte des restrictions suivantes concernant les ressources à regrouper lorsque vous décidez si le choix de l’API metrics:getBatch est adapté à votre scénario.

  • Toutes les ressources d’un lot doivent se trouver dans le même abonnement.
  • Toutes les ressources d’un lot doivent se trouver dans la même région Azure.
  • Toutes les ressources d’un lot doivent être du même type.

Pour identifier les groupes de ressources qui répondent à ces critères, exécutez la requête Azure Resource Graph suivante à l’aide d’Azure Resource Graph Explorer ou via l’API des requêtes de ressources Azure Resource Manager.

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

Étapes de conversion des requêtes

Pour convertir un appel d’API de métriques existant en appel d’API metric:getBatch, procédez comme suit :

Supposons que l’appel d’API suivant est utilisé pour effectuer une requête de métriques :

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. Modifiez le nom d’hôte.
    Remplacez management.azure.com par un point de terminaison régional pour le plan de données des métriques Azure Monitor au format <region>.metrics.monitor.azure.com, où region correspond à la région des ressources pour lesquelles vous effectuez une requête de métriques. Pour l’exemple, si les ressources sont situées dans la région westus2, le nom d’hôte est westus2.metrics.monitor.azure.com.

  2. Modifiez le nom et le chemin d’accès de l’API.
    L’API metrics:getBatch est une API POST au niveau de l’abonnement. Les ressources pour lesquelles les métriques sont demandées sont spécifiées dans le corps de la requête plutôt que dans le chemin d’URL.
    Modifiez le chemin d’URL comme suit :
    de /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. Le paramètre de requête metricNamespace est requis pour metrics:getBatch. Pour les métriques standard Azure, le nom de l’espace de noms correspond généralement au type des ressources que vous avez spécifiées. Pour vérifier la valeur à utiliser pour l’espace de noms, consultez l’API des espaces de noms des métriques.

  4. Passez de l’utilisation de l’analyseur timespan de requête à l’utilisation starttime et endtime. Par exemple, ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z devient ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Mettez à jour le paramètre de requête api-version comme suit : &api-version=2023-10-01

  6. Le paramètre de requête de filtre n’est pas précédé d’un $ dans l’API metrics:getBatch. Remplacez le paramètre de requête $filter= par filter=.

  7. L’API metrics:getBatch est un appel POST avec un corps qui contient une liste de resourceId séparées par des virgules au format suivant. Par exemple :

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

    Par exemple :

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

Jusqu’à 50 ID de ressource uniques peuvent être spécifiés dans chaque appel. Chaque ressource doit appartenir au même abonnement et à la même région, et être du même type.

Important

  • La propriété d’objet resourceids dans le corps doit être saisie en minuscules.
  • Assurez-vous que le dernier resourceId de la liste de votre tableau n’est suivi d’aucune virgule de fin.

Requête de traitement par lot convertie

L’exemple suivant illustre la requête de traitement par lots convertie.

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

Format de la réponse

Le format de réponse de l’API metrics:getBatch englobe une liste de réponses d’appel de métriques individuelles au format suivant :

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

Une propriété resourceid a été ajoutée à la liste des métriques de chaque ressource dans la réponse de l’API metrics:getBatch.

Voici des exemples de formats de réponse.

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

Évolutions de la réponse d’erreur

Dans la réponse d’erreur metrics:getBatch, le contenu de l’erreur est enveloppé par une propriété « error » de niveau supérieur dans la réponse. Par exemple,

  • Réponse d’erreur de l’API de métriques

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

  • Réponse d’erreur de l’API de traitement par lot :

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

Dépannage

  • Une série chronologique vide retourne "timeseries": []

    • Une série chronologique vide est retournée quand aucune donnée n’est disponible pour l’intervalle de temps et le filtre spécifiés. La cause la plus courante est la spécification d’un intervalle de temps qui ne contient aucune donnée. Par exemple, si l’intervalle de temps a la valeur d’une date future.
    • Une autre cause courante est la spécification d’un filtre qui ne correspond à aucune ressource. Par exemple, si le filtre spécifie une valeur de dimension qui n’existe dans aucune ressource de la combinaison abonnement et région, "timeseries": [] est retourné.

  • Filtres de caractères génériques
    L’utilisation d’un filtre de caractères génériques tel que Microsoft.ResourceId eq '*' permet à l’API de retourner une série chronologique pour chaque resourceId de l’abonnement et de la région. Si la combinaison abonnement et région ne contient aucune ressource, une série chronologique vide est retournée. La même requête sans filtre de caractères génériques retourne une seule série chronologique, en agrégeant la métrique demandée sur les dimensions demandées, par exemple l’abonnement et la région.

  • Les métriques personnalisées ne sont actuellement pas prises en charge.
    L’API metrics:getBatch ne prend pas en charge les requêtes de métriques personnalisées ou les requêtes pour lesquelles le nom de l’espace de noms de métrique ne correspond pas à un type de ressource. C’est le cas pour les métriques de système d’exploitation invité de machine virtuelle qui utilisent l’espace de noms « azure.vm.windows.guestmetrics » ou « azure.vm.linux.guestmetrics ».

  • Le paramètre supérieur s’applique par ID de ressource spécifié.
    Le fonctionnement du paramètre supérieur dans le contexte de l’API de traitement par lot peut s’avérer quelque peu déroutant. Au lieu d’appliquer une limite sur le nombre total de séries chronologiques retournées par l’ensemble de l’appel, il applique le nombre total de séries chronologiques retournées par métrique et par ID de ressource. Prenons l’exemple d’une requête par lot avec de nombreux filtres « * » spécifiés, deux métriques et quatre ID de ressource avec le paramètre supérieur 5. Le nombre maximal de séries chronologiques possibles retournées par cette requête s’élève à 40, soit l’équivalent de 2 x 4 x 5 séries chronologiques.

Erreurs d’autorisation 401

L’API de métriques individuelles nécessite qu’un utilisateur dispose de l’autorisation Lecteur de surveillance sur la ressource interrogée. Étant donné que l’API metrics:getBatch est une API au niveau de l’abonnement, les utilisateurs doivent disposer de l’autorisation Lecteur d’analyse pour l’abonnement interrogé afin d’utiliser l’API de lot. Même si les utilisateurs disposent de l’autorisation de lecture de surveillance sur toutes les ressources interrogées dans l’API de traitement par lot, la requête échoue lorsque l’utilisateur ne dispose pas de cette autorisation sur l’abonnement lui-même.

Erreurs de limitation 529

Bien que l’API de traitement par lot de plans de données soit conçue pour résoudre les problèmes de limitation, des codes d’erreur 529 peuvent toujours se produire, ce qui indique que le backend des métriques limite actuellement certains clients. L’action recommandée consiste à implémenter un schéma de nouvelle tentative de backoff exponentiel.

Pagination

La pagination n’est pas prise en charge par l’API metrics:getBatch.. Pour cette API, le cas d’utilisation le plus courant consiste à effectuer des appels fréquents (toutes les quelques minutes) pour les mêmes métriques et ressources et pour la période la plus récente. La faible latence est une considération importante pour que de nombreux clients parallélisent autant que possible leurs requêtes. La pagination force les clients à passer à un modèle d’appel séquentiel qui introduit une latence de requête supplémentaire. Dans les scénarios où les requêtes retournent des volumes de données de métriques où la pagination est utile, il est recommandé de fractionner la requête en plusieurs requêtes parallèles.

Facturation

Oui, tous les plans de données de métriques et les appels de traitement par lot sont facturés. Pour en savoir plus, consultez la section Métriques natives Azure Monitor dans Requêtes basiques de recherche dans les journaux.