Dela via

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

  • Artikel

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.

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

Ett 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

Om du vill konvertera ett befintligt API-anrop för mått till ett metric:getBatch API-anrop följer du dessa steg:

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: Till exempel:

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

    Till exempel:

    {
  "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 resourceid i matrislistan.

Konverterad 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 returnerade "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ågra resurser i kombinationen "timeseries": [] prenumeration och region returneras.

  • Jokerteckenfilter
    Om du använder ett jokerteckenfilter som Microsoft.ResourceId eq '*' gör att API:et 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 framtvinga en gräns för den totala tidsserie som returneras av hela anropet framtvingar den i stället den totala tidsserie 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.

529 begränsningsfel

Batch-API:et för dataplanet är utformat för att minimera begränsningsproblem, men 529 felkoder kan fortfarande inträffa, vilket indikerar att måttserverdelen för närvarande begränsar vissa kunder. Den rekommenderade åtgärden är att implementera ett exponentiellt återförsöksschema för backoff.

Sidnumrering

Växling stöds inte av API: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. Växling tvingar kunder till ett sekventiellt anropsmönster som introducerar ytterligare frågesvarstid. I scenarier där begäranden returnerar volymer av måttdata där växling skulle vara fördelaktigt rekommenderar vi att du delar upp frågan i flera parallella frågor.

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.