Condividi tramite

Come eseguire la migrazione dall'API delle metriche all'API getBatch

  • Articolo

L'uso elevato dell'API delle metriche può causare problemi di limitazione o prestazioni. La migrazione all'API metrics:getBatch consente di eseguire query su più risorse in una singola richiesta REST. Le due API condividono un set comune di formati di parametri di query e risposta che semplificano la migrazione.

Formato della richiesta

La richiesta API metrics:getBatch ha il formato seguente:

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

ad esempio:

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

Restrizioni di invio in batch

Quando si decide se l'API metrics:getBatch è la scelta corretta per lo scenario, prendere in considerazione le restrizioni seguenti per cui è possibile raggruppare le risorse.

  • Tutte le risorse in un batch devono trovarsi nella stessa sottoscrizione.
  • Tutte le risorse in un batch devono trovarsi nella stessa area di Azure.
  • Tutte le risorse in un batch devono essere dello stesso tipo di risorsa.

Per identificare i gruppi di risorse che soddisfano questi criteri, eseguire la query di Azure Resource Graph seguente usando Azure Resource Graph Explorer o tramite API di query delle risorse di Azure Resource Manager.

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

Passaggi di conversione della richiesta

Per convertire una chiamata API delle metriche esistente a una chiamata API metric:getBatch, seguire questa procedura:

Si supponga che venga usata la chiamata API seguente per richiedere le metriche:

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. Modificare il nome host.
    Sostituire management.azure.com con un endpoint a livello di area per il piano dati delle metriche di Monitoraggio di Azure usando il formato seguente: <region>.metrics.monitor.azure.com in cui region è l'area delle risorse per cui si richiedono le metriche. Ad esempio, se le risorse si trovano in westus2, il nome host è westus2.metrics.monitor.azure.com.

  2. Modificare il nome e il percorso dell'API.
    L'API metrics:getBatch è un'API POST a livello di sottoscrizione. Le risorse per le quali vengono richieste le metriche vengono specificate nel corpo della richiesta anziché nel percorso URL.
    Modificare il percorso url come indicato di seguito:
    da /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. Il parametro della query metricNamespace è necessario per metrics:getBatch. Per le metriche standard di Azure, il nome dello spazio dei nomi è in genere il tipo di risorsa delle risorse specificate. Per controllare il valore dello spazio dei nomi da usare, vedere API degli spazi dei nomi delle metriche

  4. Passare dall'uso del parametro di query timespan all'uso di starttime e endtime. Ad esempio, ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z diventa ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Aggiornare il parametro di query api-version come indicato di seguito: &api-version=2023-10-01

  6. Il parametro della query di filtro non è preceduto da un $ nell'API metrics:getBatch. Modificare il parametro della query da $filter= a filter=.

  7. L'API metrics:getBatch è una chiamata POST con un corpo che contiene un elenco delimitato da virgole di resourceId nel formato seguente: ad esempio:

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

    Ad esempio:

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

In ogni chiamata possono essere specificati fino a 50 ID risorsa univoci. Ogni risorsa deve appartenere alla stessa sottoscrizione, alla stessa area e allo stesso tipo di risorsa.

Importante

  • La proprietà dell'oggetto resourceids nel corpo deve essere in lettere minuscole.
  • Assicurarsi che nell'elenco di matrici non siano presenti virgole finali sull'ultimo resourceid.

Richiesta batch convertita

Nell'esempio seguente viene illustrata la richiesta batch convertita.

    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 della risposta

Il formato di risposta dell'API metrics:getBatch incapsula un elenco di singole risposte di chiamata delle metriche nel formato seguente:

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

È stata aggiunta una proprietà resourceid all'elenco delle metriche di ogni risorsa nella risposta API metrics:getBatch.

Di seguito vengono illustrati i formati di risposta di esempio.

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

Modifiche alla risposta di errore

Nella risposta di errore metrics:getBatch, il contenuto dell'errore viene sottoposto a wrapping all'interno di una proprietà di primo livello "error" nella risposta. ad esempio:

  • Risposta di errore dell'API metriche

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

  • Risposta di errore dell'API batch:

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

Risoluzione dei problemi

  • Serie temporale vuota restituita "timeseries": []

    • Viene restituita una serie temporale vuota quando non sono disponibili dati per l'intervallo di tempo e il filtro specificati. La causa più comune è specificare un intervallo di tempo che non contiene dati. Ad esempio, se l'intervallo di tempo è impostato su una data futura.
    • Un'altra causa comune consiste nello specificare un filtro che non corrisponde ad alcuna risorsa. Ad esempio, se il filtro specifica un valore di dimensione che non esiste in alcuna risorsa nella combinazione di sottoscrizione e area, "timeseries": [] viene restituito.

  • Filtri con caratteri jolly
    L'uso di un filtro con caratteri jolly, ad esempio Microsoft.ResourceId eq '*', fa sì che l'API restituisca una serie temporale per ogni resourceId nella sottoscrizione e nell'area. Se la combinazione di sottoscrizioni e aree non contiene risorse, viene restituita una serie temporale vuota. La stessa query senza il filtro con caratteri jolly restituirà una singola serie temporale, aggregando la metrica richiesta sulle dimensioni richieste, ad esempio la sottoscrizione e l'area.

  • Le metriche personalizzate non sono attualmente supportate.
    L'API metrics:getBatch non supporta l'esecuzione di query su metriche personalizzate o query in cui il nome dello spazio dei nomi della metrica non è un tipo di risorsa. Questo è il caso per le metriche del sistema operativo guest della macchina virtuale che usano lo spazio dei nomi "azure.vm.windows.guestmetrics" o "azure.vm.linux.guestmetrics".

  • Il parametro principale si applica all’ID risorsa specificato.
    Il funzionamento del parametro principale nel contesto dell'API batch può generare confusione. Anziché applicare un limite alla serie temporale totale restituita dall'intera chiamata, applica invece la serie temporale totale restituita per metrica per ID risorsa. Se si dispone di una query batch con molti filtri "*" specificati, due metriche e quattro ID risorsa con un massimo di 5. La serie temporale massima possibile restituita da tale query è 40, ovvero una serie temporale 2x4x5.

Errori di autorizzazione 401

L’API delle singole metriche richiede che un utente disponga dell'autorizzazione lettore di monitoraggio per la risorsa sottoposta a query. Poiché l'API metrics:getBatch è un'API a livello di sottoscrizione, gli utenti devono disporre dell'autorizzazione di lettura per il monitoraggio per la sottoscrizione su cui viene eseguita la query per usare l'API batch. Anche se gli utenti dispongono del lettore di monitoraggio su tutte le risorse sottoposte a query nell'API batch, la richiesta ha esito negativo se l'utente non dispone del lettore di monitoraggio nella sottoscrizione stessa.

Errori di limitazione 529

Anche se l'API batch del piano dati è progettata per ridurre i problemi di limitazione, possono verificarsi ancora codici di errore 529 che indicano che il back-end delle metriche sta attualmente limitando alcuni clienti. L'azione consigliata consiste nell'implementare uno schema di ripetizione dei tentativi di backoff esponenziale.

Paging

Il paging non è supportato dall'API metrics:getBatch. Il caso d'uso più comune per questa API viene spesso chiamato ogni pochi minuti per le stesse metriche e risorse per l'intervallo di tempo più recente. La bassa latenza è una considerazione importante quindi molti clienti parallelizzano le query il più possibile. Il paging forza i clienti in un modello di chiamata sequenziale che introduce una latenza di query aggiuntiva. Negli scenari in cui le richieste restituiscono volumi di dati delle metriche in cui il paging sarebbe utile, è consigliabile suddividere la query in più query parallele.

Fatturazione

Sì, vengono fatturati tutti i piani dati delle metriche e le chiamate in batch. Per altre informazioni, vedere la sezione metriche native di Monitoraggio di Azure in Query di ricerca log Basic.