보고서 정보

App Optimize API로 비용 및 사용률 데이터를 가져오려면 먼저 보고서를 만듭니다. 이 리소스는 분석할 데이터의 영구 정의 역할을 하며 범위, 측정기준, 기간, 필터와 같은 매개변수를 지정합니다.

보고서를 만들면 API가 요청된 데이터를 비동기식으로 생성합니다. 그런 다음 보고서의 리소스 이름을 사용하여 결과 데이터 세트를 가져옵니다.

따라서 워크플로는 다음과 같습니다.

기준을 지정하는 보고서를 만듭니다.
시스템은 이 요청을 비동기식으로 처리합니다.
작업이 완료되면 결과 데이터를 읽습니다.

이 문서에서는 사용 가능한 측정기준, 측정항목, 필터링 옵션을 비롯한 앱 최적화 API 보고서의 구조와 구성 가능한 매개변수를 자세히 설명하고 반환되는 데이터의 형식을 설명합니다.

비용 및 사용량 제한에 대한 자세한 내용은 데이터 이해하기를 참고하세요.

보고서 정의

보고서를 만들려면 다음 하위 섹션에 설명된 다음 구성 매개변수를 사용하여 Report 리소스를 정의합니다.

매개변수	유형	설명
`scopes`	배열	분석할 프로젝트 또는 App Hub 애플리케이션입니다. 범위 요소를 정확히 하나 제공해야 합니다.
`dimensions`	배열	시간 기반 그룹화를 포함하여 데이터를 가져오고 그룹화할 속성입니다.
`metrics`	배열	반환할 특정 측정항목입니다.
`filter`	문자열	시간 범위를 비롯해 데이터를 좁히는 Common Expression Language (CEL) 표현식입니다.

범위

scopes 필드는 App Optimize API가 분석할 리소스 집합을 정의합니다. 필드는 배열이지만 프로젝트 또는 App Hub 애플리케이션 중 하나인 요소를 정확히 하나 지정해야 합니다.

project: Google Cloud 프로젝트를 나타내는 문자열입니다. 다음과 같이 형식을 지정해야 합니다.
```
projects/PROJECT_ID
```
PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다. 예를 들면 projects/my-project-1입니다.
application: App Hub 애플리케이션의 전체 리소스 이름을 나타내는 문자열입니다. 다음과 같이 형식을 지정해야 합니다.
```
projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID
```
다음을 바꿉니다.
- PROJECT_ID: 앱 허브 호스트 프로젝트의 ID입니다.
- LOCATION: App Hub 애플리케이션의 리전입니다(예: us-central1).
- APPLICATION_ID: App Hub 애플리케이션의 ID입니다.
예를 들면 projects/my-host-proj/locations/us-central1/applications/my-app입니다.

다음은 보고서 생성 요청을 위한 JSON의 scopes 배열의 예시로, 단일 범위 요소를 보여줍니다.

프로젝트별 범위 지정:

"scopes": [
  {
    "project": "projects/my-project-1"
  }
]

애플리케이션별 범위 지정:

"scopes": [
  {
    "application": "projects/my-host-proj/locations/us-central1/applications/my-app"
  }
]

측정기준

측정기준은 반환되는 데이터와 데이터가 그룹화되는 방식을 결정합니다. 예를 들어 project 및 product_display_name을 선택하면 데이터에 있는 프로젝트 및 제품 이름 값의 고유한 조합마다 하나의 행이 출력에 포함됩니다.

지원되는 측정기준 표는 다음과 같습니다.

측정기준	유형	설명	예시 값
`project`	문자열	Google Cloud 프로젝트 ID입니다.	`projects/my-project`
`application`	문자열	App Hub 애플리케이션입니다.	`projects/my-project/locations/us-central1/applications/my-app`
`service_or_workload`	문자열	App Hub 서비스 또는 워크로드입니다.	`projects/my-project/locations/us-central1/applications/my-app/services/my-service`
`resource`	문자열	전체 리소스 이름입니다.	`//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1`
`resource_type`	문자열	API 리소스 유형입니다.	`compute.googleapis.com/Instance`
`location`	문자열	Google Cloud 리전 또는 멀티 리전입니다.	`us-east1`
`sku`	문자열	결제 SKU ID입니다.	`4496-8C0D-228F`
`product_display_name`	문자열	Google Cloud 제품 이름입니다.	`Compute Engine`
`month`	문자열	연도와 월입니다.	`2024-01`
`day`	문자열	연도, 월, 일입니다.	`2024-01-10`
`hour`	문자열	연도, 월, 일, 시간입니다.	`2024-01-10T00`

location 측정기준은 비용과 사용량이 귀속되는 Google Cloud 리전 또는 멀티 리전을 나타냅니다. 이 위치가 보고되는 방식은 보고서 범위에 있는 리소스의 위치 설정에 따라 다릅니다.

us-central1-a와 같은 특정 영역에 배포된 리소스의 경우 비용과 사용량이 집계되어 상위 리전에 기여한 것으로 간주됩니다. 이 예에서 location 측정기준에는 us-central1이 표시됩니다.
us-central1와 같은 리전에 배포된 리소스의 경우 location 측정기준은 해당 특정 리전을 반영합니다.
us과 같은 멀티 리전에 배포되거나 구성된 리소스의 경우 location 측정기준은 해당 멀티 리전을 반영합니다.

시간 측정기준

시간별로 결과를 집계하려면 dimensions 목록에 month, day, hour과 같은 시간 측정기준을 하나 이상 포함하세요. 다음 사항에 유의하세요.

모든 시간 측정기준은 태평양 표준시를 사용하며 일광 절약 시간 (DST)을 준수합니다.
형식은 ISO 8601을 따릅니다.
filter의 시간 범위가 선택한 시간 측정기준의 세부사항과 완벽하게 일치하지 않으면 전체 기간을 포함하도록 범위가 확장됩니다. 예를 들어 dimension: ["month"]를 사용하여 하루의 일부를 필터링하면 전체 월의 데이터가 포함됩니다.

측정항목

측정항목은 측정기준으로 정의된 각 그룹에 대해 측정하려는 정량적 값입니다. 지원되는 측정항목은 다음과 같습니다.

측정항목	유형	설명
`cost`	RECORD	요청된 통화로 표시된 금전적 비용입니다.
`cpu_mean_utilization`	FLOAT64	평균 CPU 사용률 (0.0~1.0)입니다.
`cpu_p95_utilization`	FLOAT64	95번째 백분위수 CPU 사용률 (0.0~1.0)입니다.
`cpu_usage_core_seconds`	INT64	실행된 총 CPU 작업입니다.
`cpu_allocation_core_seconds`	INT64	프로비저닝된 총 CPU 용량입니다.
`memory_mean_utilization`	FLOAT64	평균 메모리 사용률 (0.0~1.0)입니다.
`memory_p95_utilization`	FLOAT64	95번째 백분위수 메모리 사용률 (0.0~1.0)입니다.
`memory_usage_byte_seconds`	INT64	시간 경과에 따른 총 메모리 사용량입니다.
`memory_allocation_byte_seconds`	INT64	시간이 지남에 따라 프로비저닝된 총 메모리입니다.

유효한 조합

일부 측정기준은 App Optimize API의 모든 측정항목과 결합할 수 없습니다. 다음 표에는 유효한 측정기준 세트와 함께 사용할 수 있는 측정항목의 예가 나와 있습니다. 잘못된 조합이 요청되면 API에서 오류를 반환합니다. 유효한 조합은 해당 오류를 참고하세요.

측정기준	`cost` 측정항목 지원	`cpu_mean_utilization` 측정항목 지원
`application`, `product_display_name`
`application`
`location`, `product_display_name`, `project`, `resource`, `resource_type`, `sku`
`location`, `product_display_name`, `project`, `resource`, `resource_type`
`location`, `product_display_name`, `project`, `service_or_workload`
`location`, `product_display_name`, `project`, `sku`
`product_display_name`, `project`
`product_display_name`, `resource_type`
`product_display_name`, `resource`
`product_display_name`
`project`

필터

filter 필드를 사용하여 CEL 문자열을 통해 데이터를 좁힙니다. 측정기준 표에 나열된 필드를 사용하여 필터 표현식을 작성할 수 있습니다.

필터링은 다음 제약 조건을 준수해야 합니다.

모든 문자열 필드 술어는 정확한 문자열 일치를 사용해야 합니다. 예를 들면 location == 'us-east1'입니다.
동일한 문자열 필드를 참조하는 여러 술어는 논리 OR 연산자 ||를 사용하여 결합해야 합니다. 예를 들면 location == 'us-east1' || location == 'us-west1'입니다.
다른 모든 술어는 논리적 AND 연산자 &&를 사용하여 결합해야 합니다.
시작 시간을 지정하는 day와 같은 시간 측정기준의 술어는 크거나 같음 비교(>=)를 사용해야 합니다.
종료 시간을 지정하는 시간 측정기준의 조건자는 미만 비교(<)를 사용해야 합니다.

기간

filter에서 시간 측정기준 (month, day, hour)을 생략하면 보고서가 이전 태평양 시간 자정으로 끝나는 7일 범위로 기본 설정되며 일광 절약 시간이 적용됩니다. 최대 기간은 현재 날짜로부터 90일 전이며 시작 시간은 90일 기간 내에 있어야 합니다.

예를 들어 현재 태평양 표준시가 2026-01-05T12:00:00이면 기본 범위는 2025-12-29T00:00:00~2026-01-05T00:00:00 태평양 표준시입니다. 기간의 가장 빠른 시작 시간은 2025-10-07T00:00:00입니다.

Cloud Run 측정항목은 현재 날짜로부터 6주 전까지만 사용할 수 있습니다.

필터 예시

CEL 필터 문자열을 구성하는 방법의 몇 가지 예는 다음과 같습니다.

특정 리소스 유형의 보고서 데이터를 필터링하려면 resource_type 측정기준에 == 연산자를 사용합니다.
```
resource_type == 'compute.googleapis.com/Instance'
```
단일 위치의 데이터만 포함하려면 location 측정기준으로 필터링합니다.
```
location == 'us-east1'
```
특정 위치 목록의 데이터를 포함하려면 || 연산자를 사용하여 location 측정기준의 조건을 결합합니다.
```
location == 'us-east1' || location == 'us-west1'
```
시간 단위로 세분화된 특정 기간 내의 데이터를 가져오려면 hour 측정기준을 기준으로 필터링하면 됩니다. 이 예시에는 2024년 1월 1일부터 2024년 2월 1일(비포함)까지의 데이터가 포함됩니다.
```
hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```
전체 날짜를 필터링하려면 day 측정기준을 사용하세요. 일 경계는 태평양 표준시로 해석되므로 오프셋을 지정하는 것이 좋습니다. 이 예에는 2024년 3월 15일과 2024년 3월 16일의 모든 데이터가 포함됩니다.
```
day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')
```
마찬가지로 month 측정기준을 사용하여 캘린더 월별로 필터링할 수 있습니다. 정확한 경계는 태평양 표준시를 참고하세요. 이 예시에는 2025년 10월과 11월의 모든 데이터가 포함됩니다.
```
month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')
```
지난 72시간 동안의 데이터를 가져오려면 hour 측정기준에서 now() 및 duration() 함수를 사용합니다.
```
hour >= now() - duration('72h')
```
지난 7일간의 데이터를 가져오려면 hour 측정기준과 함께 duration()를 사용하면 됩니다.
```
hour >= now() - duration('168h')
```
이전과 같이 특정 달을 필터링하려면 애플리케이션 코드에서 시작 및 종료 타임스탬프를 계산해야 합니다. 그런 다음 계산된 타임스탬프를 CEL 표현식에 삽입합니다. 개념적으로는 day 측정기준으로 필터링하는 다음과 같은 모습일 수 있습니다.
```
day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')
```
다음을 바꿉니다.
- START_OF_LAST_MONTH: 태평양 표준시의 이전 달 시작을 나타내는 ISO 8601 타임스탬프 문자열입니다(예: 2025-12-01T00:00:00-08:00).
- START_OF_THIS_MONTH: 태평양 표준시의 현재 월 시작을 나타내는 ISO 8601 타임스탬프 문자열입니다(예: 2026-01-01T00:00:00-08:00).
애플리케이션 코드에서 현재 날짜, 시간대 (태평양 표준시), 일광 절약 시간제 전환을 고려하여 정확한 타임스탬프 문자열을 계산해야 합니다.
&& 연산자를 사용하여 문자열 및 시간 필터를 결합할 수 있습니다. 이 예에서는 특정 2개월 기간 내의 두 위치를 필터링합니다.
```
(location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```

다음은 resource_type, project, day 기반 시간 범위를 결합한 더 복잡한 예입니다.

resource_type == 'compute.googleapis.com/Instance' && project == 'projects/my-project' && day >= timestamp('2025-01-01T00:00:00-08:00') && day < timestamp('2025-02-01T00:00:00-08:00')

보고서 데이터 구조

보고서를 읽기에 성공하면 서비스는 데이터를 columns 및 rows로 반환합니다.

열

columns 배열은 각 필드가 rows에 표시되는 순서대로 데이터의 스키마를 설명합니다. columns 배열의 각 객체에는 name, type가 있으며 유형이 RECORD인 경우 중첩된 columns가 있습니다.

요청한 측정기준이 STRING 유형의 필드로 표시됩니다.
요청한 측정항목은 cost과 같은 복잡한 유형의 경우 INT64, FLOAT64 또는 RECORD와 같은 유형의 필드로 표시됩니다.

예를 들어 REST API를 사용하여 dimensions: ["application", "product_display_name"] 및 metrics: ["cost", "cpu_mean_utilization"]를 요청하면 이에 대한 응답으로 App Optimize API가 다음과 같은 columns 배열을 생성합니다.

"columns": [
  {
    "name": "application",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "product_display_name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "cost",
    "type": "RECORD",
    "mode": "NULLABLE",
    "columns": [
      {
        "name": "currency_code",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "units",
        "type": "INT64",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INT64",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "cpu_mean_utilization",
    "type": "FLOAT64",
    "mode": "NULLABLE"
  }
]

행

rows 필드에는 실제 데이터가 포함됩니다. 각 행은 단일 레코드를 나타내는 값의 배열입니다. 각 내부 배열 내의 값 순서는 columns 배열에 정의된 필드 순서와 직접적으로 대응합니다.

REST API에서 application, product_display_name, cost, cpu_mean_utilization를 요청한 예시를 계속 살펴보면 생성된 rows 배열의 단일 행은 다음과 같을 수 있습니다.

"rows": [
  [
    "//apphub.googleapis.com/projects/my-proj/locations/us-central1/applications/my-app",
    "Compute Engine",
    {
      "currency_code": "USD",
      "units": "12",
      "nanos": 750000000
    },
    0.65
  ],
  [
    "//apphub.googleapis.com/projects/my-proj/locations/us-east1/applications/another-app",
    "Cloud Storage",
    {
      "currency_code": "USD",
      "units": "5",
      "nanos": 200000000
    },
    0.15
  ]
]

다음 표는 단일 행 배열 내의 값이 행 배열의 값 색인을 사용하여 columns 배열에 정의된 스키마에 매핑되는 방식을 시각화합니다.

행 내 색인	해당 열	유형	예시 값
0	`application`	문자열	`"//apphub.googleapis.com/.../applications/my-app"`
1	`product_display_name`	문자열	`"Cloud Storage"`
2	`cost`	RECORD	`{ "currency_code": "USD", "units": "10", ... }`
3	`cpu_mean_utilization`	FLOAT64	`0.65`

rows 목록의 각 요소는 값의 순서가 columns 배열의 필드 정의 순서와 일치하는 배열입니다. 따라서 지정된 행 배열의 색인 n에 있는 값은 columns 배열의 색인 n에 정의된 열에 해당합니다.

비용 측정항목 해석

보고서에 cost 측정항목이 포함된 경우 값은 표준 google.type.Money 유형에 따라 다음 필드가 포함된 RECORD로 반환됩니다.

필드	유형	설명
`currency_code`	문자열	3자리 ISO 4217 통화 코드입니다(예: 'USD').
`units`	INT64	금액의 전체 단위입니다.
`nanos`	INT64	금액의 나노 (10^-9) 단위입니다. -999,999,999~+999,999,999(끝값 포함) 사이여야 합니다.

전체 금액 값을 가져오려면 units 필드와 nanos 필드를 결합합니다. nanos 필드는 통화 값의 소수 부분을 나타냅니다. 예를 들면 다음과 같습니다.

currency_code이 'USD'이고 units이 106이며 nanos이 321590000인 경우: 값은 106 + (321,590,000 / 1,000,000,000) = 106.32159 USD입니다.
currency_code이 'EUR'이고 units이 5이며 nanos이 750000000인 경우 값은 5 + (750,000,000 / 1,000,000,000) = 5.75 EUR입니다.

일반적으로 표준 통화 형식 라이브러리를 사용하여 적절한 통화 기호를 포함한 사용자 친화적인 형식으로 이 값을 표시합니다.

API에서 반환되는 데이터에 대해 자세히 알아보고 제한사항을 이해하려면 데이터 이해하기를 참고하세요.

만료 신고

각 보고서는 보고서가 생성된 후 24시간이 지나면 App Optimize API 서비스에서 자동으로 삭제됩니다. 이 시간이 지나면 API를 통해 보고서와 데이터를 검색할 수 없습니다. 보고서의 예약된 만료 시간을 확인하려면 보고서의 메타데이터를 가져와 expireTime 필드를 확인합니다.