Dela via

Migrera från mått-API:et till getBatch-API:et

Tung användning av mått-API:et kan leda till begränsnings- eller prestandaproblem. Om du migrerar till API:et metrics:getBatch kan du köra frågor mot flera resurser i en enda REST-begäran. De två API:erna delar en gemensam uppsättning frågeparameter- och svarsformat som gör migreringen enkel.

Den här artikeln innehåller vägledning om hur du konverterar ett befintligt API-anrop för mått till ett metrics:getBatch API-anrop. Mer information om begränsning finns i Förstå hur Azure Resource Manager begränsar begäranden.

Begärandeformat

metrics:getBatch API-begäran har följande format:

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

Exempel:

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

Batchbegränsningar

Tänk på följande begränsningar för vilka resurser som kan batchas tillsammans när du bestämmer om API:et metrics:getBatch är rätt val för ditt scenario.

  • Alla resurser i en batch måste finnas i samma prenumeration.
  • Alla resurser i en batch måste finnas i samma Azure-region.
  • Alla resurser i en batch måste vara av samma resurstyp.

För att identifiera grupper av resurser som uppfyller dessa villkor kör du följande Azure Resource Graph-fråga med Azure Resource Graph Explorer eller via fråge-API:et för Azure Resource Manager-resurser.

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

Begärandekonverteringssteg

Följ dessa steg för att konvertera ett befintligt API-anrop för mått till ett metric:getBatch API-anrop:

Anta att följande API-anrop används för att begära mått:

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. Ändra värdnamnet.

    Ersätt management.azure.com med en regional slutpunkt för Azure Monitor Metrics-dataplanet med följande format: <region>.metrics.monitor.azure.com var region är regionen för de resurser som du begär mått för. Om resurserna till exempel finns i westus2 är westus2.metrics.monitor.azure.comvärdnamnet .

  2. Ändra API-namnet och sökvägen.

    API:et metrics:getBatch är ett POST-API på prenumerationsnivå. De resurser som måtten begärs för anges i begärandetexten i stället för i URL-sökvägen.

    Ändra url-sökvägen enligt följande:

    från /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
    till /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch

  3. Frågeparam metricNamespace krävs för metrics:getBatch. För Azures standardmått är namnområdesnamnet vanligtvis resurstypen för de resurser som du har angett. Information om hur du kontrollerar det namnområdesvärde som ska användas finns i API:et för måttnamnområden.

  4. Växla från att använda timespan frågeparam till att använda starttime och endtime. Till exempel kommer ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z att bli ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Uppdatera frågeparametern api-version enligt följande: &api-version=2023-10-01

  6. Filterfrågeparamen är inte prefix med en $ i API:et metrics:getBatch . Ändra frågeparam från $filter= till filter=.

  7. API:et metrics:getBatch är ett POST-anrop med en brödtext som innehåller en kommaavgränsad lista över resourceIds i följande format:

    Exempel:

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

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

    Upp till 50 unika resurs-ID:t kan anges i varje anrop. Varje resurs måste tillhöra samma prenumeration, region och vara av samma resurstyp.

Viktigt!

  • Objektegenskapen resourceids i brödtexten måste vara gemener.
  • Kontrollera att det inte finns några avslutande kommatecken på ditt senaste resurs-ID i matrislistan.

Omvandlad batchbegäran

I följande exempel visas den konverterade batchbegäran.

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

Svarsformat

Svarsformatet för API:et metrics:getBatch kapslar in en lista över enskilda måttanropssvar i följande format:

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

En resourceid egenskap lades till i varje resurs måttlista i API-svaret metrics:getBatch .

Följande visar exempel på svarsformat.

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

Felsvarsändringar

I felsvaret metrics:getBatch omsluts felinnehållet i en "felegenskap" på toppnivå i svaret. Ett exempel:

  • API-felsvar för mått

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

  • Batch API-felsvar:

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

Felsökning

  • Tomma tidsserier returnerades "timeseries": []

    • En tom tidsserie returneras när inga data är tillgängliga för det angivna tidsintervallet och filtret. Den vanligaste orsaken är att ange ett tidsintervall som inte innehåller några data. Till exempel om tidsintervallet är inställt på ett framtida datum.
    • En annan vanlig orsak är att ange ett filter som inte matchar några resurser. Om filtret till exempel anger ett dimensionsvärde som inte finns på någon resurs i kombinationen av prenumeration och region, "timeseries": [] returneras.

  • Jokerteckenfilter

    Om du använder ett jokerteckenfilter som Microsoft.ResourceId eq '*' gör det att API returnerar en tidsserie för varje ResourceId i prenumerationen och regionen. Om kombinationen prenumeration och region inte innehåller några resurser returneras en tom tidsserie. Samma fråga utan jokerteckenfiltret returnerar en enda tidsserie och aggregerar det begärda måttet över de begärda dimensionerna, till exempel prenumeration och region.

  • Anpassade mått stöds inte för närvarande.

    API:et metrics:getBatch stöder inte frågor mot anpassade mått eller frågor där namnet på måttnamnområdet inte är en resurstyp. Detta gäller för VM-mått för gästoperativsystem som använder namnområdet "azure.vm.windows.guestmetrics" eller "azure.vm.linux.guestmetrics".

  • Den översta parametern gäller per angivet resurs-ID.

    Hur den översta parametern fungerar i kontexten för batch-API:et kan vara lite förvirrande. I stället för att begränsa antalet tidsserier som returneras av hela anropet, begränsar den i stället antalet tidsserier som returneras per mått per resurs-ID. Om du har en batchfråga med många *-filter angivna, två mått och fyra resurs-ID:er med en topp på 5. Den maximala möjliga tidsserie som returneras av den frågan är 40, dvs. 2x4x5-tidsserier.

401-auktoriseringsfel

Api:et för enskilda mått kräver att en användare har behörigheten Övervakningsläsare för resursen som efterfrågas. Eftersom API:et metrics:getBatch är ett API på prenumerationsnivå måste användarna ha behörigheten Övervakningsläsare för den efterfrågade prenumerationen för att kunna använda batch-API:et. Även om användarna har övervakningsläsare för alla resurser som efterfrågas i batch-API:et misslyckas begäran om användaren inte har övervakningsläsare för själva prenumerationen.

403 behörighetsmisslyckanden

Detta anger att den nödvändiga resursprovidern inte är registrerad. Se Microsoft.Insights-resursprovidern är inte registrerad för din prenumeration.

529 begränsningsfel

Batch-API:et för dataplanet är utformat för att minimera begränsningsproblem, men 529 felkoder kan fortfarande inträffa. Det här felet anger att metrikbackend för närvarande begränsar dina begäranden. Den rekommenderade åtgärden är att implementera ett återförsöksschema med exponentiell backoff. Mer information om begränsning finns i Förstå hur Azure Resource Manager begränsar begäranden.

Bläddring

Paginering stöds inte av API:et metrics:getBatch. Det vanligaste användningsfallet för det här API:et är att anropa med några minuters mellanrum för samma mått och resurser för den senaste tidsramen. Låg svarstid är ett viktigt övervägande så många kunder parallelliserar sina frågor så mycket som möjligt. Paginering tvingar kunder till ett sekventiellt anropsmönster som introducerar ytterligare fördröjning i förfrågningar. I scenarier där begäranden returnerar volymer av måttdata där sidindelning skulle vara fördelaktigt rekommenderar vi att du delar upp frågan i flera parallella sökningar.

Fakturering

Ja, alla måttdataplan och batchanrop faktureras. Mer information finns i avsnittet inbyggda mått i Azure Monitor i Grundläggande loggsökningsfrågor.