Sdílet prostřednictvím

Migrace z rozhraní API metrik na rozhraní getBatch API

  • Článek

Vysoké využití rozhraní API metrik může vést k omezování nebo problémům s výkonem. Migrace na metrics:getBatch rozhraní API umožňuje dotazovat se na více prostředků v jednom požadavku REST. Tato dvě rozhraní API sdílejí společnou sadu parametrů dotazu a formátů odpovědí, které usnadňují migraci.

Formát požadavku

Požadavek metrics:getBatch rozhraní API má následující formát:

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

Příklad:

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

Omezení dávkování

Při rozhodování o tom, jestli metrics:getBatch je rozhraní API správnou volbou pro váš scénář, zvažte následující omezení, ke kterým prostředkům je možné seskupit dohromady.

  • Všechny prostředky v dávce musí být ve stejném předplatném.
  • Všechny prostředky v dávce musí být ve stejné oblasti Azure.
  • Všechny prostředky v dávce musí být stejného typu prostředku.

Pokud chcete pomoct identifikovat skupiny prostředků, které splňují tato kritéria, spusťte následující dotaz Azure Resource Graphu pomocí Azure Resource Graph Exploreru nebo prostřednictvím rozhraní API pro dotazy prostředků Azure Resource Manageru.

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

Kroky převodu požadavků

Pokud chcete převést existující volání rozhraní API metrik na volání rozhraní API metrik:getBatch, postupujte takto:

Předpokládejme, že se k vyžádání metrik používá následující volání rozhraní API:

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. Změňte název hostitele.
    Nahraďte management.azure.com regionálním koncovým bodem roviny dat metrik Služby Azure Monitor pomocí následujícího formátu: <region>.metrics.monitor.azure.com kde region je oblast prostředků, pro které požadujete metriky. Například pokud jsou prostředky v westus2, název hostitele je westus2.metrics.monitor.azure.com.

  2. Změňte název a cestu rozhraní API.
    Rozhraní metrics:getBatch API je rozhraní POST API na úrovni předplatného. Prostředky, pro které se metriky požadují, se zadají v textu požadavku, nikoli v cestě URL.
    Cestu url změňte následujícím způsobem:
    z /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
    na /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/metrics:getBatch

  3. Parametr metricNamespace dotazu se vyžaduje pro metriky:getBatch. Pro standardní metriky Azure je název oboru názvů obvykle typem prostředku zadaných prostředků. Pokud chcete zkontrolovat hodnotu oboru názvů, kterou chcete použít, podívejte se na rozhraní API pro obory názvů metrik.

  4. Přepněte z použití parametru timespan dotazu na použití starttime a endtime. Například z ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z se stane ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Následujícím způsobem aktualizujte parametr dotazu api-version: &api-version=2023-10-01

  6. Parametr dotazu filtru není předponou $ v metrics:getBatch rozhraní API. Změňte parametr dotazu z $filter= na filter=.

  7. Rozhraní metrics:getBatch API je volání POST s tělem, které obsahuje seznam id prostředků oddělený čárkami v následujícím formátu: Například:

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

    Příklad:

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

V každém volání může být zadáno až 50 jedinečných ID prostředků. Každý prostředek musí patřit do stejného předplatného, oblasti a musí mít stejný typ prostředku.

Důležité

  • Vlastnost resourceids objektu v těle musí být malá písmena.
  • Ujistěte se, že v seznamu polí nejsou žádné koncové čárky.

Převedený dávkový požadavek

Následující příklad ukazuje převedenou dávkovou žádost.

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

Formát odpovědi

Formát metrics:getBatch odpovědi rozhraní API zapouzdřuje seznam odpovědí volání jednotlivých metrik v následujícím formátu:

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

resourceid V odpovědi rozhraní API byla do seznamu metrics:getBatch metrik jednotlivých prostředků přidána vlastnost.

Následující příklad ukazuje ukázkové formáty odpovědí.

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

Změny odpovědi na chybu

metrics:getBatch V odpovědi na chybu je obsah chyby zabalen uvnitř vlastnosti "error" nejvyšší úrovně v odpovědi. Příklad:

  • Odpověď na chybu rozhraní API metrik

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

  • Odpověď na chybu rozhraní API služby Batch:

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

Řešení problému

  • Vrácená prázdná časová řada "timeseries": []

    • Prázdná časová řada se vrátí, když pro zadaný časový rozsah a filtr nejsou k dispozici žádná data. Nejběžnější příčinou je určení časového rozsahu, který neobsahuje žádná data. Pokud je například časový rozsah nastavený na budoucí datum.
    • Další běžnou příčinou je zadání filtru, který neodpovídá žádným prostředkům. Pokud například filtr určuje hodnotu dimenze, která neexistuje u žádného prostředku v kombinaci předplatného a oblasti, "timeseries": [] vrátí se.

  • Filtry zástupných znaků
    Použití filtru zástupných znaků, například Microsoft.ResourceId eq '*' způsobí, že rozhraní API vrátí časovou řadu pro každé ID prostředku v předplatném a oblasti. Pokud kombinace předplatného a oblasti neobsahuje žádné prostředky, vrátí se prázdná časová řada. Stejný dotaz bez filtru se zástupnými znamény vrátí jednu časovou řadu a agreguje požadovanou metriku přes požadované dimenze, například předplatné a oblast.

  • Vlastní metriky se v současné době nepodporují.
    Rozhraní metrics:getBatch API nepodporuje dotazování vlastních metrik ani dotazy, kde název oboru názvů metrik není typem prostředku. Jedná se o případ metrik hostovaného operačního systému virtuálního počítače, které používají obor názvů azure.vm.windows.guestmetrics nebo azure.vm.linux.guestmetrics.

  • Horní parametr se vztahuje na zadané ID prostředku.
    Způsob fungování horního parametru v kontextu dávkového rozhraní API může být trochu matoucí. Místo vynucení limitu pro celkovou časovou řadu vrácenou celým voláním vynucuje spíše celkovou časovou řadu vrácenou podle metriky na ID prostředku. Pokud máte dávkový dotaz se zadanými mnoha filtry *, dvě metriky a čtyři ID prostředků s vrcholem 5. Maximální možná časová řada vrácená tímto dotazem je 40, tedy 2x4x5 časových řad.

Chyby autorizace 401

Rozhraní API pro jednotlivé metriky vyžaduje, aby měl uživatel oprávnění Čtenář monitorování k dotazovanému prostředku. metrics:getBatch Vzhledem k tomu, že rozhraní API je rozhraní API na úrovni předplatného, musí mít uživatelé oprávnění Čtenář monitorování pro dotazované předplatné, aby mohli používat rozhraní API služby Batch. I když mají uživatelé čtenáře monitorování na všechny prostředky dotazované v dávkovém rozhraní API, požadavek selže, pokud uživatel nemá v samotném předplatném čtenáře monitorování.

Chyby omezování 529

I když je rozhraní API pro dávku roviny dat navržené tak, aby pomohlo zmírnit problémy s omezováním, může dojít k 529 kódům chyb, které značí, že back-end metrik v současné době omezuje některé zákazníky. Doporučená akce je implementace exponenciálního schématu opakování opakování.

Stránkování

Stránkování nepodporuje rozhraní API metrics:getBatch. Nejběžnější případ použití tohoto rozhraní API se často volá každých několik minut pro stejné metriky a prostředky za poslední časový rámec. Nízká latence je důležitým aspektem, takže mnoho zákazníků paralelizuje dotazy co nejvíce. Stránkování vynutí zákazníky do sekvenčního volajícího modelu, který zavádí další latenci dotazů. V situacích, kdy požadavky vrací objemy dat metrik, kde by stránkování bylo výhodné, doporučujeme dotaz rozdělit na několik paralelních dotazů.

Fakturace

Ano, fakturují se všechna rovina dat metrik a dávková volání. Další informace najdete v části Nativní metriky služby Azure Monitor v základních dotazech prohledávání protokolů.