メトリック API から getBatch API に移行する方法

  • [アーティクル]

メトリック API を大量に使用すると、調整やパフォーマンスの問題が発生する可能性があります。 metrics:getBatch API に移行すると、1 つの REST 要求で複数のリソースに対してクエリを実行できます。 2 つの API は、クエリ パラメーターと応答の形式の一般的なセットを共有しており、移行が容易になります。

要求の形式

metrics:getBatch API 要求の形式は次のとおりです。

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

たとえば、 にします。

POST /subscriptions/12345678-1234-1234-1234-123456789abc/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/12345678-1234-1234-1234-123456789abc/resourceGroups/rg-vms-01/providers/Microsoft.Compute/virtualMachines/vmss-001_41df4bb9",
    "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/rg-vms-02/providers/Microsoft.Compute/virtualMachines/vmss-001_c1187e2f"
]
}

バッチ処理の制限

metrics:getBatch API がシナリオに適した選択肢であるかどうかを判断するときは、一緒にバッチ処理できるリソースに関する次の制限事項を考慮してください。

  • バッチ内のすべてのリソースは、同じサブスクリプションに存在する必要があります。
  • バッチ内のすべてのリソースは、同じ Azure リージョンに存在する必要があります。
  • バッチ内のすべてのリソースは、同じリソースの種類である必要があります。

これらの条件を満たすリソースのグループを特定するには、Azure Resource Graph エクスプローラーを使用するか、Azure Resource Manager リソース クエリ API を使用して、次の Azure Resource Graph クエリを実行します。

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

要求の変換手順

既存のメトリック API 呼び出しを metric:getBatch API 呼び出しに変換するには、次の手順に従います。

メトリックを要求するために次の API 呼び出しが使用されているとします。

GET https://management.azure.com/subscriptions/12345678-1234-1234-1234-123456789abc/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. ホスト名を変更します。
    次の形式: <region>.metrics.monitor.azure.com を使用して、management.azure.com を Azure Monitor メトリック データ プレーンのリージョン エンドポイントに置き換えます。ここで region は、メトリックが要求されるリソースのリージョンです。 この例では、リソースが westus2 にある場合、ホスト名は westus2.metrics.monitor.azure.com です。

  2. API の名前とパスを変更します。
    metrics:getBatch API は、サブスクリプション レベルの POST API です。 メトリックが要求されるリソースは、URL パスではなく要求本文で指定されます。
    URL パスを次のように変更します。
    /subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics から
    /subscriptions/12345678-1234-1234-1234-123456789abc/metrics:getBatch へ

  3. metrics:getBatch には metricNamespace クエリ パラメーターが必要です。 Azure 標準メトリックの場合、名前空間名は通常、指定したリソースの種類です。 使用する名前空間の値を確認するには、メトリック名前空間 API に関するページを参照してください

  4. クエリ パラメーター timespan の使用から starttime および endtime の使用へと切り替えを行います。 たとえば、?timespan=2023-04-20T12:00:00.000Z/2023-04-22T12:00:00.000Z は ?startime=2023-04-20T12:00:00.000Z&endtime=2023-04-22T12:00:00.000Z になります。

  5. api-version クエリ パラメーターを次のように更新します: &api-version=2023-10-01。

  6. metrics:getBatch API で、filter クエリ パラメーターにはプレフィックス $ が付きません。 クエリ パラメーターを $filter= から filter= に変更します。

  7. metrics:getBatch API は、次の形式の resourceId のコンマ区切りリストを含む本文を持つ POST 呼び出しです。次に例を示します。

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

    次に例を示します。

    {
  "resourceids": [
    "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount"
  ]
}

各呼び出しでは、最大 50 個の一意のリソース ID を指定できます。 各リソースは、同じサブスクリプション、リージョンに属し、同じリソースの種類である必要があります。

重要

  • 本文の resourceids オブジェクト プロパティは小文字にする必要があります。
  • 配列リスト内の最後の resourceid に末尾のコンマがないことを確認します。

変換されたバッチ要求

次の例は、変換されたバッチ要求を示しています。

    POST https://westus2.metrics.monitor.azure.com/subscriptions/12345678-1234-1234-1234-123456789abc/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/12345678-1234-1234-1234-123456789abc/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample2-test-rg/providers/Microsoft.Storage/storageAccounts/eax252qtemplate",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3diag",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3prefile",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3/providers/Microsoft.Storage/storageAccounts/sample3tipstorage",
        "/subscriptions/12345678-1234-1234-1234-123456789abc/resourceGroups/sample3backups/providers/Microsoft.Storage/storageAccounts/pod01account1"
      ]
    }

応答の形式

metrics:getBatch API の応答の形式では、個々のメトリック呼び出し応答のリストが次の形式でカプセル化されます。

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

metrics:getBatch API 応答の各リソースのメトリック リストに、resourceid プロパティが追加されました。

応答の形式の例を次に示します。

{
  "cost": 11516,
  "startime": "2023-04-20T12:00:00Z",
  "endtime": "2023-04-22T12:00:00Z",
  "interval": "P1D",
  "value": [
    {
      "id": "/subscriptions/12345678-1234-1234-1234-123456789abc/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/12345678-1234-1234-1234-123456789abc/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"
}

エラー応答の変更

metrics:getBatch エラー応答で、エラー コンテンツは応答の最上位の "error" プロパティ内にラップされます。 たとえば、 にします。

  • メトリック API エラー応答

    {
  "code": "BadRequest",
  "message": "Metric: Ingress does not support requested dimension combination: apiname2, supported ones are: GeoType,ApiName,Authentication, TraceId: {ab11d9c2-b17e-4f75-8986-b314ecacbe11}"
}

  • Batch API エラー応答:

    {
  "error": {
    "code": "BadRequest",
    "message": "Metric: Egress does not support requested dimension combination: apiname2, supported ones are: GeoType,ApiName,Authentication, TraceId: {cd77617d-5f11-e50d-58c5-ba2f2cdc38ce}"
  }
}

トラブルシューティング

  • 空の時系列で "timeseries": [] が返されました

    • 指定した時間の範囲とフィルターで利用可能なデータがない場合、空の時系列が返されます。 最も一般的な原因は、データを含まない時間の範囲を指定することです。 たとえば、時間の範囲を将来の日付に設定した場合などです。
    • もう 1 つのよくある原因は、どのリソースにも一致しないフィルターを指定することです。 たとえば、サブスクリプションとリージョンの組み合わせのどのリソースにも存在しないディメンジョン値をフィルターで指定すると、"timeseries": [] が返されます。

  • ワイルドカード フィルター
    Microsoft.ResourceId eq '*' などのワイルドカード フィルターを使用すると、API はサブスクリプションとリージョン内のすべての resourceId の時系列を返します。 サブスクリプションとリージョンの組み合わせにリソースが含まれない場合、空の時系列が返されます。 ワイルドカード フィルターを使用しない同じクエリは、サブスクリプションやリージョンなど、要求されるディメンジョン経由で要求されたメトリックを集約した単一の時系列を返します。 サブスクリプションとリージョンの組み合わせにリソースがない場合、API は 0 の単一のデータ ポイントを持つ単一の時系列を返します。

  • カスタム メトリックは現時点ではサポートされていません。
    metrics:getBatch API では、カスタム メトリックのクエリや、メトリック名前空間名がリソースの種類ではないクエリはサポートされていません。 これは、名前空間 "azure.vm.windows.guestmetrics" または "azure.vm.linux.guestmetrics" を使用する VM ゲスト OS メトリックの場合です。

  • top パラメーターは、指定されたリソース ID ごとに適用されます。
    バッチ API のコンテキストで top パラメーターがどのように機能するかは、少しわかりにくい場合があります。 呼び出し全体によって返される合計時系列に制限を適用するのではなく、"リソース ID ごと、メトリックごと" に返される合計時系列を適用します。 多数の '*' フィルターが指定されたバッチ クエリ、2 つのメトリック、最上位が 5 の 4 つのリソース ID がある場合。 そのクエリによって返される可能性のある最大時系列は 40 (2x4x5 の時系列) です。

401 承認エラー

個々のメトリック API には、クエリ対象のリソースに対する 監視閲覧者 アクセス許可がユーザーに付与されている必要があります。 metrics:getBatch API はサブスクリプション レベルの API であるため、ユーザーは、バッチ API を使用するには、クエリされたサブスクリプションの監視閲覧者アクセス許可を持っている必要があります。 バッチ API でクエリが実行されるすべてのリソースに対してユーザーが監視閲覧者アクセス許可を場合でも、サブスクリプション自体に対して監視閲覧者アクセス許可を持っていない場合、要求は失敗します。

529 調整エラー

調整の問題を軽減するためにデータ プレーン バッチ API が設計されていますが、メトリック バックエンドによって一部の顧客が現在調整されていることを示す 529 エラー コードが引き続き発生する可能性があります。 推奨されるアクションは、指数バックオフ再試行スキームを実装することです。

Paging

metrics:getBatch API ではページングはサポートされていません。 この API の最も一般的なユース ケースは、最新の時間枠で同じメトリックとリソースに対して、数分ごとに頻繁に呼び出しを行うことです。 低待機時間は、多くの顧客が可能な限りクエリを並列化するための重要な考慮事項です。 ページングにより、顧客はシーケンシャルな呼び出しパターンを強制されるため、クエリの待機時間が増加します。 要求によって大量のメトリック データの量が返される、ページングが有益なシナリオでは、クエリを複数の並列クエリに分割することをお勧めします。

課金

すべてのメトリック データ プレーンおよびバッチ処理呼び出しに対して課金されます。 詳細については、「基本的なログ検索クエリ」の「Azure Monitor ネイティブ メトリック」セクションを参照してください。