Delen via

Migreren van de API voor metrische gegevens naar de getBatch-API

Intensief gebruik van de metrics API kan leiden tot throttling of prestatieproblemen. Door te migreren naar de metrics:getBatch API kunt u meerdere resources in één REST-aanvraag opvragen. De twee API's delen een gemeenschappelijke set queryparameter- en antwoordindelingen die de migratie eenvoudig maken.

Dit artikel bevat richtlijnen voor het converteren van een bestaande API-aanroep voor metrische gegevens naar een metrics:getBatch API-aanroep. Zie voor meer informatie over throttling Hoe Azure Resource Manager verzoeken vertraagt.

Aanvraagindeling

De metrics:getBatch API-aanvraag heeft de volgende indeling:

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

Voorbeeld:

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

Batchbeperkingen

Houd rekening met de volgende beperkingen voor het samenvoegen van resources bij het bepalen of de metrics:getBatch API de juiste keuze is voor uw scenario.

  • Alle resources in een batch moeten zich in hetzelfde abonnement bevinden.
  • Alle resources in een batch moeten zich in dezelfde Azure-regio bevinden.
  • Alle resources in een batch moeten hetzelfde resourcetype hebben.

Als u groepen resources wilt identificeren die aan deze criteria voldoen, voert u de volgende Azure Resource Graph-query uit met behulp van Azure Resource Graph Explorer of via de Azure Resource Manager-resourcesquery-API.

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

Stappen voor aanvraagconversie

Als u een bestaande API-aanroep voor metrische gegevens wilt converteren naar een metric:getBatch API-aanroep, voert u de volgende stappen uit:

Stel dat de volgende API-aanroep wordt gebruikt om metrische gegevens aan te vragen:

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. Wijzig de hostnaam.

    Vervang management.azure.com door een regionaal eindpunt voor het gegevensvlak met metrische gegevens van Azure Monitor met behulp van de volgende indeling: <region>.metrics.monitor.azure.com waar bevindt zich region de regio van de resources waarvoor u metrische gegevens aanvraagt. Als de resources zich bijvoorbeeld in westus2 bevinden, is westus2.metrics.monitor.azure.comde hostnaam .

  2. Wijzig de API-naam en het pad.

    De metrics:getBatch API is een POST-API op abonnementsniveau. De resources waarvoor de metrische gegevens worden aangevraagd, worden opgegeven in de aanvraagbody in plaats van in het URL-pad.

    Wijzig het URL-pad als volgt:

    van /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
    tot /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch

  3. De metricNamespace queryparameter is vereist voor metrics:getBatch. Voor metrische standaardgegevens van Azure is de naamruimtenaam meestal het resourcetype van de resources die u hebt opgegeven. Als u de waarde van de naamruimte wilt controleren die u wilt gebruiken, raadpleegt u de API voor metrische naamruimten.

  4. Schakel over van het gebruik van de timespan queryparameter naar het gebruik starttime en endtime. ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z wordt bijvoorbeeld ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Werk de queryparameter api-versie als volgt bij: &api-version=2023-10-01

  6. De filterqueryparameter wordt niet voorafgegaan door een $ in de metrics:getBatch API. Wijzig de queryparameter van $filter= in filter=.

  7. De metrics:getBatch API is een POST-aanroep met een hoofdtekst die een door komma's gescheiden lijst met resourceIds bevat in de volgende indeling:

    Voorbeeld:

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

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

    In elke aanroep kunnen maximaal 50 unieke resource-id's worden opgegeven. Elke resource moet deel uitmaken van hetzelfde abonnement, dezelfde regio en hetzelfde resourcetype hebben.

Belangrijk

  • De resourceids objecteigenschap in de tekst moet met een kleine letter geschreven zijn.
  • Zorg ervoor dat er geen volgkomma's zijn op uw laatste resource-id in de matrixlijst.

Geconverteerde batchaanvraag

In het volgende voorbeeld ziet u de geconverteerde batchaanvraag.

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

Antwoordindeling

De antwoordindeling van de metrics:getBatch API bevat een lijst met antwoorden op metrische API-aanroepen.

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

Er is een resourceid eigenschap toegevoegd aan de lijst met metrische gegevens van elke resource in het metrics:getBatch API-antwoord.

Hieronder ziet u voorbeeld van antwoordindelingen.

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

Wijzigingen in foutreacties

In het metrics:getBatch foutantwoord wordt de foutinhoud verpakt binnen een eigenschap 'fout' op het hoogste niveau van het antwoord. Bijvoorbeeld

  • Reactie op metrische API-fouten

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

  • Antwoord op batch-API-fouten:

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

Probleemoplossingsproces

  • Lege tijdreeks teruggegeven "timeseries": []

    • Er wordt een lege tijdreeks geretourneerd wanneer er geen gegevens beschikbaar zijn voor het opgegeven tijdsbereik en filter. De meest voorkomende oorzaak is het opgeven van een tijdsbereik dat geen gegevens bevat. Als het tijdsbereik bijvoorbeeld is ingesteld op een toekomstige datum.
    • Een andere veelvoorkomende oorzaak is het opgeven van een filter dat niet overeenkomt met resources. Als met het filter bijvoorbeeld een dimensiewaarde wordt opgegeven die niet bestaat op resources in de combinatie van het abonnement en de regio, "timeseries": [] wordt deze geretourneerd.

  • Jokertekenfilters

    Het gebruik van een jokertekenfilter, zoals Microsoft.ResourceId eq '*' ervoor zorgt dat de API een tijdreeks retourneert voor elke resourceId in het abonnement en de regio. Als de combinatie van het abonnement en de regio geen resources bevat, wordt er een lege tijdreeks geretourneerd. Dezelfde query zonder het jokertekenfilter retourneert één tijdreeks, waarbij de aangevraagde metrische waarde wordt samengevoegd ten opzichte van de aangevraagde dimensies, bijvoorbeeld abonnement en regio.

  • Aangepaste metrische gegevens worden momenteel niet ondersteund.

    De metrics:getBatch API biedt geen ondersteuning voor het uitvoeren van query's op aangepaste metrische gegevens of query's waarbij de naam van de metrische naamruimte geen resourcetype is. Dit is het geval voor de metrische gegevens van het gastbesturingssysteem van een VM, die gebruikmaken van de naamruimte 'azure.vm.windows.guestmetrics' of 'azure.vm.linux.guestmetrics'.

  • De bovenste parameter is van toepassing per opgegeven resource-id.

    Hoe de belangrijkste parameter werkt in de context van de batch-API kan een beetje verwarrend zijn. In plaats van een limiet op te leggen aan de totale tijdreeks die door de gehele oproep wordt geretourneerd, wordt er eerder een limiet opgelegd aan de totale tijdreeks die per meting per resource-ID wordt geretourneerd. Als u een batchquery hebt met veel '*'-filters opgegeven, twee metrische gegevens en vier resource-id's met een top van 5. De maximaal mogelijke tijdreeks die door die query wordt geretourneerd, is 40, dat is 2x4x5-tijdreeks.

401-autorisatiefouten

De afzonderlijke API voor metrische gegevens vereist dat een gebruiker de machtiging Monitoring Lezer heeft op de resource die bevraagd wordt. Omdat de metrics:getBatch API een API op abonnementsniveau is, moeten gebruikers de machtiging Bewakingslezer hebben voor het opgevraagde abonnement om de batch-API te kunnen gebruiken. Zelfs als gebruikers Monitoringlezer hebben voor alle resources die in de batch-API worden opgevraagd, mislukt de aanvraag als de gebruiker geen Monitoringlezer voor het abonnement zelf heeft.

403-autorisatiefouten

Dit geeft aan dat de vereiste resourceprovider niet is geregistreerd. Zie Microsoft.Insights resource provider is niet geregistreerd voor uw abonnement.

529 beperkingsfouten

Hoewel de batch-API van het gegevensvlak-API is ontworpen om throttling-problemen te verhelpen, kunnen er nog steeds 529-foutcodes optreden. Deze fout geeft aan dat de back-end voor metrische gegevens momenteel uw aanvragen beperkt. De aanbevolen actie is het implementeren van een exponentieel terugval-herhalingsschema. Zie voor meer informatie over throttling Hoe Azure Resource Manager verzoeken vertraagt.

Oproepen

Paging wordt niet ondersteund door de metrics:getBatch API. De meest voorkomende gebruikssituatie voor deze API is het regelmatig iedere paar minuten aanroepen voor dezelfde meetwaarden en resources voor het laatste tijdsbestek. Lage latentie is een belangrijke overweging waardoor veel klanten hun query's zo veel mogelijk parallel uitvoeren. Paginering dwingt klanten om een sequentieel belpatroon te volgen, wat extra vertraging in queryverwerking introduceert. In scenario's waarin aanvragen volumes met metrische gegevens retourneren waar paging nuttig zou zijn, is het raadzaam om de query te splitsen in meerdere parallelle query's.

Facturatie

Ja, alle metrische gegevenslaag en batchoproepen worden gefactureerd. Zie de sectie systeemeigen metrische gegevens van Azure Monitor in Basisquery's voor zoeken in logboeken voor meer informatie.