Delen via

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

  • Artikel

Intensief gebruik van de API voor metrische gegevens kan leiden tot beperking 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.

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

Bijvoorbeeld:

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 metrische gegevens: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 metrische gegevens: getBatch. Voor metrische standaardgegevens van Azure is de naamruimtenaam meestal het resourcetype van de resources die u hebt opgegeven. Als u de te gebruiken naamruimtewaarde wilt controleren, raadpleegt u de API voor metrische naamruimten

  4. Schakel over van het gebruik van de timespan queryparameter naar het gebruik starttime en endtime. Zo wordt ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z gewijzigd in ?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: bijvoorbeeld:

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

    Voorbeeld:

    {
  "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 hoofdtekst moet een kleine letter zijn.
  • Zorg ervoor dat er geen volgkomma's op uw laatste resourceid in de matrixlijst staan.

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 aanroepen van afzonderlijke metrische gegevens in de volgende indeling:

{
  "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 foutbericht wordt de inhoud van de fout verpakt in een eigenschap 'fout' op het hoogste niveau in 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}"
  }
}

Probleemoplossing

  • Lege tijdreeks geretourneerd "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 metrische gegevens van het gastbesturingssystem van de 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 af te dwingen voor de totale tijdreeks die door de hele aanroep wordt geretourneerd, wordt de totale tijdreeks die per metrische waarde per resource-id wordt geretourneerd, afgedwongen. 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 Lezer voor bewaking heeft voor de resource waarop een query wordt uitgevoerd. 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 Controlelezer hebben voor alle resources die in de batch-API worden opgevraagd, mislukt de aanvraag als de gebruiker geen bewakingslezer voor het abonnement zelf heeft.

529 beperkingsfouten

Hoewel de batch-API van het gegevensvlak is ontworpen om beperkingsproblemen te verhelpen, kunnen er nog steeds 529-foutcodes optreden die aangeven dat de back-end met metrische gegevens momenteel bepaalde klanten beperkt. De aanbevolen actie is het implementeren van een exponentieel uitstelschema.

Paginering

Paging wordt niet ondersteund door de metrische gegevens: getBatch-API. De meest voorkomende use-case voor deze API roept regelmatig om de paar minuten aan voor dezelfde metrische gegevens en resources voor het laatste tijdsbestek. Lage latentie is een belangrijke overweging, zoveel mogelijk klanten die hun query's parallelliseren. Paginering dwingt klanten af in een sequentiële aanroeppatroon dat extra querylatentie 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.

Billing

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.