共用方式為

如何從計量 API 移轉至 getBatch API

  • 發行項

大量使用計量 API 可能會導致節流或效能問題。 移轉 metrics:getBatch API 可讓您在單一 REST 要求中查詢多個資源。 這兩個 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/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"
]
}

批次限制

在決定 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 呼叫轉換為 metrics:getBatch API 呼叫，請遵循這些步驟：

假設使用下列 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. 變更主機名稱。
    將 management.azure.com 取代為 Azure 監視器計量資料平面的區域端點，使用下列格式：<region>.metrics.monitor.azure.com，其中的 region 是您要求計量的資源區域。 例如，如果資源位於 westus2 中，主機名稱為 westus2.metrics.monitor.azure.com。

  2. 變更 API 名稱和路徑。
    metrics:getBatch API 是訂用帳戶層級 POST API。 要求計量的資源是在要求本文中指定，而不是在 URL 路徑中指定。
    變更 URL 路徑，如下所示：
    從 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/sample-test/providers/Microsoft.Storage/storageAccounts/testaccount/providers/microsoft.Insights/metrics
    到 /subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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=。

  7. metrics:getBatch API 是 POST 呼叫，其中的本文包含下列格式的以逗號分隔的 resourceId 清單：例如：

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

    例如：

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

每個呼叫中最多可指定 50 個唯一資源識別碼。 每個資源都必須屬於相同的訂用帳戶、區域，且屬於相同的資源類型。

重要

  • 本文中的 resourceids 物件屬性必須是小寫。
  • 確保陣列清單中的最後一個 resourceid 上沒有尾端逗號。

已轉換的批次要求

下列範例顯示已轉換的批次要求。

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

回應格式

metrics:getBatch API 的回應格式會以下列格式封裝個別計量呼叫回應的清單：

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

resourceid 屬性已新增至 metrics:getBatch API 回應中每個資源的計量清單。

以下顯示範例回應格式。

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

錯誤回應變更

在 metrics:getBatch 錯誤回應中，錯誤內容會包裝在回應的最上層 "error" 屬性內。 例如，

  • 計量 API 錯誤回應

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

  • 批次 API 錯誤回應：

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

疑難排解

  • 傳回的空時間序列 "timeseries": []

    • 當指定的時間範圍和篩選條件沒有可用資料時，會傳回空的時間序列。 最常見的原因是指定了不包含任何資料的時間範圍。 例如，如果時間範圍設定為未來的日期。
    • 另一個常見原因是指定的篩選條件不符合任何資源。 例如，如果篩選條件指定訂用帳戶和區域組合中任何資源上都不存在的維度值，則會傳回 "timeseries": []。

  • 萬用字元篩選
    使用萬用字元篩選，例如 Microsoft.ResourceId eq '*'，會導致 API 傳回訂用帳戶和區域中每個 resourceId 的時間序列。 如果訂用帳戶和區域組合不包含任何資源，則會傳回空的時間序列。 沒有萬用字元篩選的相同查詢會傳回單一時間序列，在要求的維度上 (例如訂用帳戶和區域) 彙總要求的計量。

  • 目前不支援自訂計量。
    metrics:getBatch API 不支援查詢自訂計量，或不支援其計量命名空間名稱不是資源類型的查詢。 這是使用命名空間 "azure.vm.windows.guestmetrics" 或 "azure.vm.linux.guestmetrics" 的 VM 客體 OS 計量的情況。

  • top 參數會根據每個指定的資源識別碼套用。
    在批次 API 的內容中，top 參數的運作方式可能會有點令人困惑。 不對整個呼叫所傳回的總時間序列強制執行限制，而是對每個資源識別碼每個計量傳回的總時間序列強制執行。 如果您的批次查詢指定許多 '*' 篩選條件、兩個計量，以及具有 top 5 的四個資源識別碼。 該查詢傳回的最大可能時間序列為 40，也就是 2x4x5 時間序列。

401 授權錯誤

個別計量 API 需要使用者具有要查詢的資源上的監視讀取者權限。 因為 metrics:getBatch API 是訂用帳戶層級 API，使用者必須具有查詢訂用帳戶的監視讀取者權限，才能使用批次 API。 即使使用者具有批次 API 中要查詢的所有資源的監視讀取者權限，如果使用者沒有訂用帳戶本身上的監視讀取者權限，則要求也會失敗。

529 節流錯誤

雖然資料平面批次 API 是設計來協助減輕節流問題，仍可能發生 529 錯誤碼，表示計量後端目前正在對某些客戶進行節流。 建議的動作是實作指數輪詢重試配置。

分頁

metrics:getBatch API 不支援分頁。 此 API 最常見的使用案例是針對最新的時間範圍，每隔幾分鐘針對相同的計量和資源呼叫一次。 低延遲是會盡可能平行處理其查詢的許多客戶的重要考量。 分頁會強制客戶進入會引入額外的查詢延遲的循序呼叫模式。 在分頁對要求傳回會有幫助的計量資料量的情況下，建議將查詢分割成多個平行查詢。

計費

是，所有計量資料平面和批次呼叫都會計費。 如需詳細資訊，請參閱基本記錄搜尋查詢中的 Azure 監視器原生計量一節。