Udostępnij za pośrednictwem

Jak przeprowadzić migrację z interfejsu API metryk do interfejsu API getBatch

  • Artykuł

Duże wykorzystanie interfejsu API metryk może powodować problemy z ograniczaniem przepustowości lub wydajnością. Migracja do interfejsu metrics:getBatch API umożliwia wykonywanie zapytań dotyczących wielu zasobów w jednym żądaniu REST. Dwa interfejsy API mają wspólny zestaw formatów parametrów zapytań i odpowiedzi, które ułatwiają migrację.

Format żądania

Żądanie interfejsu metrics:getBatch API ma następujący 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>]
}

Na przykład:

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

Ograniczenia przetwarzania wsadowego

Podczas podejmowania decyzji, czy metrics:getBatch interfejs API jest poprawnym wyborem dla danego scenariusza, należy wziąć pod uwagę następujące ograniczenia dotyczące tego, które zasoby mogą być wsadowe.

  • Wszystkie zasoby w partii muszą znajdować się w tej samej subskrypcji.
  • Wszystkie zasoby w partii muszą znajdować się w tym samym regionie świadczenia usługi Azure.
  • Wszystkie zasoby w partii muszą być tego samego typu zasobu.

Aby ułatwić identyfikowanie grup zasobów spełniających te kryteria, uruchom następujące zapytanie usługi Azure Resource Graph przy użyciu Eksploratora usługi Azure Resource Graph lub za pośrednictwem interfejsu API zapytań zasobów usługi Azure Resource Manager.

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

Kroki konwersji żądania

Aby przekonwertować istniejące wywołanie interfejsu API metryk na wywołanie interfejsu API metryki:getBatch API, wykonaj następujące kroki:

Załóżmy, że następujące wywołanie interfejsu API jest używane do żądania metryk:

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. Zmień nazwę hosta.
    Zastąp management.azure.com element regionalnym punktem końcowym płaszczyzny danych metryk usługi Azure Monitor przy użyciu następującego formatu: <region>.metrics.monitor.azure.com gdzie region to region zasobów, dla których żądasz metryk. Jeśli na przykład zasoby znajdują się w westus2, nazwa hosta to westus2.metrics.monitor.azure.com.

  2. Zmień nazwę interfejsu API i ścieżkę.
    Interfejs metrics:getBatch API jest interfejsem API POST na poziomie subskrypcji. Zasoby, dla których są żądane metryki, są określone w treści żądania, a nie w ścieżce adresu URL.
    Zmień ścieżkę adresu URL w następujący sposób:
    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 zapytania jest wymagany dla metryk:getBatch. W przypadku metryk standardowych platformy Azure nazwa przestrzeni nazw jest zwykle typem zasobu określonych zasobów. Aby sprawdzić wartość przestrzeni nazw do użycia, zobacz interfejs API przestrzeni nazw metryk

  4. Przełącz się z używania parametru zapytania na używanie parametrów timespan starttime i endtime. Na przykład, ?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z staje się ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z.

  5. Zaktualizuj parametr zapytania api-version w następujący sposób: &api-version=2023-10-01

  6. Parametr zapytania filtru nie jest poprzedzony prefiksem $ w interfejsie metrics:getBatch API. Zmień parametr zapytania z $filter= na filter=.

  7. Interfejs metrics:getBatch API jest wywołaniem POST z treścią zawierającą rozdzielaną przecinkami listę identyfikatorów resourceId w następującym formacie: Na przykład:

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

    Na przykład:

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

W każdym wywołaniu można określić maksymalnie 50 unikatowych identyfikatorów zasobów. Każdy zasób musi należeć do tej samej subskrypcji, regionu i mieć ten sam typ zasobu.

Ważne

  • Właściwość resourceids object w treści musi mieć małe litery.
  • Upewnij się, że na liście tablic nie ma żadnych przecinków końcowych.

Przekonwertowane żądanie wsadowe

W poniższym przykładzie pokazano przekonwertowane żądanie wsadowe.

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

Format odpowiedzi

Format odpowiedzi interfejsu metrics:getBatch API hermetyzuje listę poszczególnych odpowiedzi wywołań metryk w następującym formacie:

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

Właściwość resourceid została dodana do listy metryk poszczególnych zasobów w odpowiedzi interfejsu metrics:getBatch API.

Poniżej przedstawiono przykładowe formaty odpowiedzi.

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

Zmiany odpowiedzi na błędy

W odpowiedzi na błąd zawartość błędu metrics:getBatch jest owinięta wewnątrz właściwości "error" najwyższego poziomu w odpowiedzi. Na przykład:

  • Odpowiedź na błąd interfejsu API metryk

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

  • Odpowiedź na błąd interfejsu API usługi 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}"
  }
}

Rozwiązywanie problemów

  • Zwrócona pusta seria czasowa "timeseries": []

    • Pusty szereg czasowy jest zwracany, gdy żadne dane nie są dostępne dla określonego zakresu czasu i filtru. Najczęstszą przyczyną jest określenie zakresu czasu, który nie zawiera żadnych danych. Jeśli na przykład zakres czasu jest ustawiony na datę przyszłą.
    • Inną typową przyczyną jest określenie filtru, który nie jest zgodny z żadnymi zasobami. Jeśli na przykład filtr określa wartość wymiaru, która nie istnieje dla żadnych zasobów w ramach subskrypcji i kombinacji regionu, "timeseries": [] zostanie zwrócona.

  • Filtry z symbolami wieloznacznymi
    Użycie filtru wieloznacznych, takiego jak Microsoft.ResourceId eq '*' powoduje, że interfejs API zwraca szereg czasowy dla każdego identyfikatora zasobu w subskrypcji i regionie. Jeśli kombinacja subskrypcji i regionu nie zawiera żadnych zasobów, zwracany jest pusty szereg czasowy. To samo zapytanie bez filtru z symbolami wieloznacznymi zwróci pojedynczą serię czasową, agregując żądaną metrykę dla żądanych wymiarów, na przykład subskrypcję i region.

  • Metryki niestandardowe nie są obecnie obsługiwane.
    Interfejs metrics:getBatch API nie obsługuje wykonywania zapytań dotyczących metryk niestandardowych ani zapytań, w których nazwa przestrzeni nazw metryki nie jest typem zasobu. Dotyczy to metryk systemu operacyjnego gościa maszyny wirtualnej, które używają przestrzeni nazw "azure.vm.windows.guestmetrics" lub "azure.vm.linux.guestmetrics".

  • Górny parametr ma zastosowanie do określonego identyfikatora zasobu.
    Sposób działania najwyższego parametru w kontekście interfejsu API wsadowego może być nieco mylący. Zamiast wymuszać limit całkowitej serii czasowej zwracanej przez całe wywołanie, wymusza łączną liczbę zwracanych szeregów czasowych na metrykę na identyfikator zasobu. Jeśli masz zapytanie wsadowe z wieloma określonymi filtrami "*", dwie metryki i cztery identyfikatory zasobów z maksymalnie 5. Maksymalna możliwa liczba szeregów czasowych zwracanych przez to zapytanie wynosi 40, czyli 2x4x5 szeregów czasowych.

Błędy autoryzacji 401

Interfejs API poszczególnych metryk wymaga od użytkownika uprawnienia Czytelnik monitorowania dla zasobu, którego dotyczy zapytanie. metrics:getBatch Ponieważ interfejs API jest interfejsem API na poziomie subskrypcji, użytkownicy muszą mieć uprawnienie Czytelnik monitorowania dla subskrypcji, do którego ma być używany interfejs API wsadowy. Nawet jeśli użytkownicy mają czytelnik monitorowania dla wszystkich zasobów, które są wykonywane w interfejsie API wsadowego, żądanie kończy się niepowodzeniem, jeśli użytkownik nie ma czytelnika monitorowania w samej subskrypcji.

Błędy ograniczania przepustowości 529

Chociaż interfejs API wsadowy płaszczyzny danych został zaprojektowany w celu ułatwienia rozwiązywania problemów z ograniczaniem przepustowości, kody błędów 529 mogą nadal występować, co wskazuje, że zaplecze metryk obecnie ogranicza niektórych klientów. Zalecaną akcją jest zaimplementowanie schematu ponawiania prób wykładniczego.

Stronicowanie

Stronicowanie nie jest obsługiwane przez interfejs API metrics:getBatch. Najczęstszy przypadek użycia tego interfejsu API jest często wywoływany co kilka minut dla tych samych metryk i zasobów w ostatnim przedziale czasu. Małe opóźnienia to ważna kwestia, aby wielu klientów zrównało zapytania tak bardzo, jak to możliwe. Stronicowanie wymusza na klientach sekwencyjny wzorzec wywołania, który wprowadza dodatkowe opóźnienie zapytań. W scenariuszach, w których żądania zwracają woluminy danych metryk, w których stronicowanie byłoby korzystne, zaleca się podzielenie zapytania na wiele zapytań równoległych.

Rozliczenia

Tak wszystkie metryki płaszczyzny danych i wywołania wsadowe są rozliczane. Aby uzyskać więcej informacji, zobacz sekcję Metryk natywnych usługi Azure Monitor w temacie Podstawowe zapytania przeszukiwania dzienników.