Freigeben über

Migrieren von der Metrik-API zur getBatch-API

  • Artikel

Die intensive Verwendung der Metrik-API kann zu Drosselungs- oder Leistungsproblemen führen. Durch die Migration zur metrics:getBatch-API können Sie mehrere Ressourcen in einer einzelnen REST-Anforderung abfragen. Die beiden APIs verwenden einen gemeinsamen Satz von Abfrageparametern und Antwortformaten, die die Migration vereinfachen.

Anforderungsformat

Die Anforderung der metrics:getBatch-API weist das folgende Format auf:

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

Beispiel:

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

Einschränkungen bei der Batchverarbeitung

Berücksichtigen Sie bei der Entscheidung, ob die metrics:getBatch-API die richtige Wahl für Ihr Szenario ist, die folgenden Einschränkungen in Bezug darauf, welche Ressourcen in einem Batch verarbeitet werden können.

  • Alle Ressourcen in einem Batch müssen sich im selben Abonnement befinden.
  • Alle Ressourcen in einem Batch müssen sich in derselben Azure-Region befinden.
  • Alle Ressourcen in einem Batch müssen vom selben Ressourcentyp sein.

Um Ressourcengruppen zu identifizieren, die diese Kriterien erfüllen, führen Sie die folgende Azure Resource Graph-Abfrage mithilfe des Azure Resource Graph-Explorers oder über die Azure Resource Manager-API zum Abfragen von Ressourcen aus.

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

Schritte zur Anforderungskonvertierung

Führen Sie die folgenden Schritte aus, um einen vorhandenen Metrik-API-Aufruf in einen Aufruf der metric:getBatch-API zu konvertieren:

Angenommen, der folgende API-Aufruf wird zum Anfordern von Metriken verwendet:

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. Ändern Sie den Hostnamen.
    Ersetzen Sie management.azure.com durch einen regionalen Endpunkt für die Azure Monitor-Metrikdatenebene im folgenden Format: <region>.metrics.monitor.azure.com. Dabei ist region die Region der Ressourcen, für die Sie Metriken anfordern. Wenn sich die Ressourcen beispielsweise in der Region „westus2“ befinden, lautet der Hostname westus2.metrics.monitor.azure.com.

  2. Ändern Sie den API-Namen und -Pfad.
    Die metrics:getBatch-API ist eine POST-API auf Abonnementebene. Die Ressourcen, für die die Metriken angefordert werden, werden im Anforderungstext und nicht im URL-Pfad angegeben.
    Ändern Sie den URL-Pfad wie folgt:
    von /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
    in /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch

  3. Der Abfrageparameter metricNamespace ist für „metrics:getBatch“ erforderlich. Bei Azure-Standardmetriken entspricht der Namespacename in der Regel dem Ressourcentyp der von Ihnen angegebenen Ressourcen. Informationen zum Überprüfen des zu verwendenden Namespacewerts finden Sie im Artikel zur API für Metriknamespaces.

  4. Wechseln Sie von der Verwendung des timespan-Abfrageparameters zur Verwendung von starttime und endtime. Beispielsweise wird ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z zu ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Aktualisieren Sie den Abfrageparameter „api-version“ wie folgt: &api-version=2023-10-01.

  6. Dem Filterabfrageparameter wird in der metrics:getBatch-API nicht das Präfix $ vorangestellt. Ändern Sie den Abfrageparameter von $filter= in filter=.

  7. Die metrics:getBatch-API ist ein POST-Aufruf mit einem Text, der eine durch Trennzeichen getrennte Liste von Ressourcen-IDs (resourceIds) beispielsweise im folgenden Format enthält:

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

    Zum Beispiel:

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

In jedem Aufruf können bis zu 50 eindeutige Ressourcen-IDs angegeben werden. Jede Ressource muss zum gleichen Abonnement und zur selben Region gehören und denselben Ressourcentyp aufweisen.

Wichtig

  • Die Objekteigenschaft resourceids im Text muss in Kleinbuchstaben angegeben werden.
  • Stellen Sie sicher, dass in der Arrayliste der letzten Ressourcen-ID (resourceid) keine Kommas nachgestellt sind.

Konvertierte Batchanforderung

Das folgende Beispiel zeigt die konvertierte Batchanforderung:

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

Antwortformat

Das Antwortformat der metrics:getBatch-API kapselt eine Liste einzelner Antworten auf Metrikaufrufe im folgenden Format:

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

In der Antwort der metrics:getBatch-API wurde der Metrikliste der einzelnen Ressourcen eine resourceid-Eigenschaft hinzugefügt.

Im Folgenden sind Beispielantwortformate gezeigt.

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

Änderungen an Fehlerantworten

In der Fehlerantwort von metrics:getBatch wird der Fehlerinhalt in der error-Eigenschaft auf oberster Ebene für die Antwort eingeschlossen. Beispiel:

  • Fehlerantwort der Metrik-API

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

  • Fehlerantwort der Batch-API

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

Problembehandlung

  • Zurückgegebene leere Zeitreihe "timeseries": []

    • Eine leere Zeitreihe wird zurückgegeben, wenn keine Daten für den angegebenen Zeitraum und Filter verfügbar sind. Die häufigste Ursache ist die Angabe eines Zeitbereichs, der keine Daten enthält. Dies trifft z. B. zu, wenn der Zeitbereich auf ein Datum in der Zukunft festgelegt wird.
    • Eine weitere häufige Ursache kann die Angabe eines Filters sein, der zu keinen übereinstimmenden Ressourcen führt. Wenn der Filter beispielsweise einen Dimensionswert angibt, der auf keine Ressourcen mit dieser Kombination aus Abonnement und Region zutrifft, wird "timeseries": [] zurückgegeben.

  • Platzhalterfilter
    Die Verwendung eines Platzhalterfilters wie Microsoft.ResourceId eq '*' bewirkt, dass die API eine Zeitreihe für jede Ressourcen-ID im Abonnement und in der Region zurückgibt. Wenn die Kombination aus Abonnement und Region keine Ressourcen liefert, wird eine leere Zeitreihe zurückgegeben. Dieselbe Abfrage ohne den Platzhalterfilter würde eine einzelne Zeitreihe zurückgeben und die angeforderte Metrik über die angeforderten Dimensionen aggregieren, z. B. Abonnement und Region.

  • Benutzerdefinierte Metriken werden derzeit nicht unterstützt.
    Die metrics:getBatch-API unterstützt keine Abfragen benutzerdefinierter Metriken und keine Abfragen, bei denen der Name des Metriknamespace kein Ressourcentyp ist. Dies gilt für VM-Gastbetriebssystemmetriken, die den Namespace „azure.vm.windows.guestmetrics“ oder „azure.vm.linux.guestmetrics“ verwenden.

  • Der top-Parameter gilt für jede angegebene Ressourcen-ID.
    Die Funktionsweise des top-Parameters im Kontext der Batch-API kann etwas verwirrend sein. Anstatt einen Grenzwert für die vom gesamten Aufruf zurückgegebene Gesamtzeitreihe zu erzwingen, wird die Gesamtzeitreihe erzwungen, die pro Metrik pro Ressourcen-ID zurückgegeben wird. Beispiel: Sie verfügen über eine Batchabfrage mit zahlreichen angegebenen Filtern vom Typ „*“, zwei Metriken und vier Ressourcen-IDs mit einem Grenzwert von 5. Von dieser Abfrage können maximal 40 Zeitreihen zurückgegeben werden, d. h. 2 · 4 · 5 Zeitreihen.

Autorisierungsfehler vom Typ „401“

Die API für einzelne Metriken erfordert, dass Benutzer*innen über die Berechtigung Benutzer mit Leseberechtigung für Überwachungsdaten für die abgefragte Ressource verfügen. Da die metrics:getBatch-API eine API auf Abonnementebene gilt, müssen Benutzer/Benutzerinnen über die Berechtigung „Überwachungsleser“ für das abgefragte Abonnement verfügen, um die Batch-API verwenden zu können. Selbst wenn Benutzer*innen über die Berechtigung „Benutzer mit Leseberechtigung für Überwachungsdaten“ für alle Ressourcen verfügen, die in der Batch-API abgefragt werden, schlägt die Anforderung fehl, wenn die Benutzer*innen nicht über die Berechtigung „Benutzer mit Leseberechtigung für Überwachungsdaten“ für das Abonnement selbst verfügen.

Drosselungsfehler vom Typ „529“

Die Batch-API auf Datenebene wurde zwar entwickelt, um Drosselungsprobleme zu minimieren, es können aber weiterhin 529-Fehlercodes auftreten. Dies weist darauf hin, dass das Metrik-Back-End derzeit eine Drosselung für einige Kund*innen anwendet. Es wird empfohlen, ein Wiederholungsschema für ein exponentielles Backoff zu implementieren.

Paging

Paging wird von der metrics:getBatch-API nicht unterstützt. Der häufigste Anwendungsfall für diese API besteht darin, alle paar Minuten dieselben Metriken und Ressourcen für den aktuellen Zeitraum abzurufen. Geringe Wartezeit ist ein wichtiger Aspekt, sodass viele Kund*innen ihre Abfragen möglichst stark parallelisieren. Paging zwingt Kund*innen zu einem sequenziellen Aufrufmuster, das zusätzliche Wartezeit einführt. In Szenarien, in denen Anforderungen große Mengen von Metrikdaten zurückgeben und in denen Paging von Vorteil wäre, wird empfohlen, die Abfrage in mehrere parallele Abfragen aufzuteilen.

Abrechnung

Ja, alle Aufrufe auf Metrikdatenebene und Batchverarbeitungsaufrufe werden in Rechnung gestellt. Weitere Informationen finden Sie unter Grundlegende Protokollsuchabfragen im Abschnitt Native Azure Monitor-Metriken.