다음을 통해 공유

Metrics API에서 getBatch API로 마이그레이션하는 방법

  • 아티클

metrics 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/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 Explorer를 사용하거나 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=로 변경합니다.

  7. metrics:getBatch API는 쉼표로 구분된 resourceIds 목록을 포함하는 본문이 포함된 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를 지정할 수 있습니다. 각 리소스는 동일한 구독, 지역에 속해야 하며 동일한 리소스 종류여야 합니다.

Important

  • 본문의 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: {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 메트릭의 경우입니다.

  • 최상위 매개 변수는 지정된 리소스 ID별로 적용됩니다.
    일괄 처리 API의 컨텍스트에서 최상위 매개 변수가 작동하는 방식은 약간 혼란스러울 수 있습니다. 전체 호출에서 반환된 총 시계열에 제한을 적용하는 대신 리소스 ID당 메트릭당 반환된 총 시계열을 적용합니다. 많은 '*' 필터가 지정된 일괄 처리 쿼리가 있는 경우 메트릭 2개와 상위 5개가 있는 4개의 리소스 ID가 있습니다. 해당 쿼리에서 반환할 수 있는 최대 시계열은 40, 즉 2x4x5 시계열입니다.

401 권한 부여 오류

개별 메트릭 API를 사용하려면 사용자에게 쿼리 중인 리소스에 대한 모니터링 읽기 권한자 권한이 있어야 합니다. metrics:getBatch API는 구독 수준 API이므로 사용자는 일괄 처리 API를 사용하려면 쿼리된 구독에 대한 모니터링 독자 권한이 있어야 합니다. 사용자가 일괄 처리 API에서 쿼리되는 모든 리소스에 대해 모니터링 읽기 권한자를 가지고 있더라도 사용자에게 구독 자체에 대한 모니터링 읽기 권한자가 없으면 요청이 실패합니다.

529 제한 오류

데이터 평면 일괄 처리 API는 제한 문제를 완화하는 데 도움이 되도록 설계되었지만 메트릭 백 엔드가 현재 일부 고객을 제한하고 있음을 나타내는 529 오류 코드가 여전히 발생할 수 있습니다. 권장되는 작업은 지수 백오프 재시도 체계를 구현하는 것입니다.

페이징

페이징은 metrics:getBatch에서 지원되지 않습니다. 이 API의 가장 일반적인 사용 사례는 최신 기간에 동일한 메트릭 및 리소스에 대해 몇 분마다 자주 호출하는 것입니다. 짧은 대기 시간이 중요한 고려 사항이므로 많은 고객이 가능한 한 쿼리를 병렬 처리합니다. 페이징으로 인해 고객은 추가 쿼리 대기 시간이 발생하는 순차적 호출 패턴을 사용하게 됩니다. 요청이 페이징이 도움이 되는 많은 양의 메트릭 데이터를 반환하는 시나리오에서는 쿼리를 여러 병렬 쿼리로 분할하는 것이 좋습니다.

결제

예, 모든 메트릭 데이터 평면 및 일괄 처리 호출에 대한 요금이 청구됩니다. 자세한 내용은 기본 로그 검색 쿼리의 Azure Monitor 네이티브 메트릭 섹션을 참조하세요.