보고서 생성

앱 최적화 API는 보고서를 생성하여 비용 및 리소스 사용량 데이터를 분석하는 데 도움이 됩니다. 이 정보를 가져오려면 먼저 API 요청을 전송하여 보고서를 만듭니다. 이 요청에서는 데이터의 범위, 집계 또는 그룹화 방법, 적용할 필터를 정의합니다.

보고서가 준비되면 데이터를 읽을 수 있습니다.

사용 가능한 범위, 측정기준, 측정항목, 필터 및 이러한 설정의 유효한 조합에 대한 자세한 내용은 보고서 정보를 참고하세요.

시작하기 전에

이 가이드의 예시에는 분석할 활성 리소스가 있는 Google Cloud 프로젝트가 필요합니다. App Optimize API는 의미 있는 결과를 생성하기 위해 청구 및 사용 데이터가 필요합니다. 새 프로젝트나 빈 프로젝트에 대해 실행되는 보고서는 비어 있습니다.

이 가이드에서 PROJECT_ID로 식별된 프로젝트는 데이터 범위를 제공하고 보고서 리소스를 호스팅합니다.

App Optimize API는 한 프로젝트에서 다른 프로젝트 또는 단일 프로젝트 또는 폴더 수준 경계의 애플리케이션 데이터를 분석하는 보고서를 만드는 것을 지원합니다. 여러 프로젝트로 구성될 수 있는 App Hub 애플리케이션에 관한 보고서를 생성하려면 보고서를 생성할 수 있도록 애플리케이션과 연결된 모든 프로젝트에 필요한 모니터링 및 결제 권한이 있어야 합니다.
보고서 리소스를 만들고 관리하는 데 사용할 프로젝트에 앱 최적화 API가 사용 설정되어 있는지 확인합니다.

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.
Verify that you have the permissions required to complete this guide.

Verify that you have the permissions required to complete this guide.
이 문서의 샘플 사용 방법에 대한 탭을 선택하세요.

gcloud

Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

Cloud Shell 활성화

Google Cloud 콘솔 하단에 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

프로덕션 환경의 인증 설정에 대한 자세한 내용은 Google Cloud 인증 문서의 Google Cloud에서 실행되는 코드의 애플리케이션 기본 사용자 인증 정보 설정 을 참고하세요.

Python

App Optimize API용 Python 클라이언트 라이브러리를 설치합니다.
로컬 개발 환경에서 이 페이지의 Python 샘플을 사용하려면 gcloud CLI를 설치하고 초기화한 후 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정합니다.
1. Google Cloud CLI를 설치합니다.
2. 외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.
3. 로컬 셸을 사용하는 경우 사용자 계정에 대한 로컬 인증 사용자 인증 정보를 만듭니다.
```
gcloud auth application-default login
```
  Cloud Shell을 사용하는 경우 이 작업을 수행할 필요는 없습니다.
  
  인증 오류가 반환되고 외부 ID 공급업체(IdP)를 사용하는 경우 제휴 ID로 gcloud CLI에 로그인했는지 확인합니다.
자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경의 ADC 설정을 참고하세요.

프로덕션 환경의 인증 설정에 대한 자세한 내용은 Google Cloud 인증 문서의 Google Cloud에서 실행되는 코드의 애플리케이션 기본 사용자 인증 정보 설정 을 참고하세요.

REST

로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

Google Cloud CLI를 설치합니다.

외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.

필요한 역할

이 가이드를 사용하여 보고서를 만드는 데 필요한 권한을 얻으려면 관리자에게 활성 리소스가 있는 프로젝트에 대해 다음 IAM 역할을 부여해 달라고 요청하세요.

App Optimize 관리자 (roles/appoptimize.admin)
모니터링 뷰어(roles/monitoring.viewer)
뷰어 (roles/viewer) (또는 billing.resourceCosts.get 권한을 부여하는 다른 역할)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

App Optimize API에 필요한 권한 및 역할에 대한 자세한 내용은 IAM으로 액세스 제어를 참고하세요.

보고서 생성

다음 단계에서는 보고서 생성을 시작하는 방법을 설명합니다. 이 예에서는 지난 한 주 동안 선택한 프로젝트의 비용과 평균 CPU 사용량을 파악하는 데 도움이 되는 보고서를 만듭니다. 이 보고서는 리소스 유형, Google Cloud 제품, 위치 등 각 개별 리소스별로 이 정보를 분류합니다.

보고서 리소스를 만들려면 선호하는 방법에 대한 안내를 따르세요.

gcloud

다음 gcloud beta app-optimize reports create 명령어를 사용하여 보고서를 만듭니다.

gcloud beta app-optimize reports create REPORT_ID \
  --project=PROJECT_ID \
  --location=global \
  --dimensions=location,product_display_name,project,resource,resource_type \
  --metrics=cost,cpu_mean_utilization \
  --report-filter='hour >= now - duration("168h")' \
  --scopes=project=projects/PROJECT_ID

다음을 바꿉니다.

REPORT_ID: 새 보고서의 고유 ID입니다(예: my-resource-cost-report-1).
PROJECT_ID: Google Cloud 프로젝트 ID입니다.

보고서를 생성하는 명령어는 작업이 완료될 때까지 자동으로 기다립니다.

Python

다음 Python 코드는 AppOptimizeClient.create_report()를 사용하여 보고서를 만듭니다.

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"

# Create the App Optimize client
client = appoptimize_v1beta.AppOptimizeClient()

# Initialize the report request
report = appoptimize_v1beta.Report(
    dimensions=['location', 'product_display_name', 'project', 'resource', 'resource_type'],
    metrics=['cost', 'cpu_mean_utilization'],
    filter='hour >= now - duration("168h")',
    scopes=[
        appoptimize_v1beta.Scope(project=f"projects/{project_id}"),
    ],
)
request = appoptimize_v1beta.CreateReportRequest(
    parent=f"projects/{project_id}/locations/global",
    report=report,
    report_id=report_id,
)

# Send the request and wait for completion
operation = client.create_report(request=request)
print("Waiting for operation to complete...")
response = operation.result()
print(response)

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
REPORT_ID: 새 보고서의 고유 ID입니다(예: my-first-report).

클라이언트 라이브러리의 operation.result() 메서드는 작업이 완료될 때까지 자동으로 기다립니다. 수동 폴링 루프가 필요하지 않습니다.

REST

REST API의 projects.locations.reports 리소스 경로에 HTTP POST 요청을 보냅니다.

요청을 보내려면 다음 curl 명령어를 사용합니다.

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": [
      {
        "project": "projects/PROJECT_ID"
      }
    ],
    "dimensions": [
      "location",
      "product_display_name",
      "project",
      "resource",
      "resource_type"
    ],
    "metrics": [
      "cost",
      "cpu_mean_utilization"
    ],
    "filter": "hour >= now - duration(\"168h\")"
  }' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports?report_id=REPORT_ID"

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
REPORT_ID: 새 보고서의 고유 ID입니다(예: my-resource-cost-report-1).

API는 장기 실행 작업 (LRO) 객체를 반환합니다. 작업 상태를 확인하는 데 사용할 응답의 name 필드를 확인합니다.

{
  "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.OperationMetadata"
  },
  "done": false
}

응답에서 done 필드는 false이며, 이는 보고서 생성이 진행 중임을 나타냅니다.

보고서가 준비되었는지 확인하려면 이전 단계에서 반환된 작업 name에 GET HTTP 요청을 보냅니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/operations/OPERATION_ID"

PROJECT_ID 및 OPERATION_ID을 LRO 응답의 값으로 바꿉니다.

응답을 검사하여 작업 상태를 확인합니다.

보고서가 아직 생성 중인 경우 응답은 초기 LRO 응답과 유사하며 done이 false로 설정됩니다. 5~15초와 같은 짧은 시간 동안 기다린 후 이 단계를 반복하여 다시 폴링해야 합니다.

보고서 생성이 완료되면 응답에 "done": true가 포함되고 response 필드에 보고서 리소스가 포함됩니다.

  {
    "name": "projects/PROJECT_ID/locations/global/operations/OPERATION_ID",
    "metadata": {
      "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.OperationMetadata"
    },
    "done": true,
    "response": {
      "@type": "type.googleapis.com/google.cloud.appoptimize.v1beta.Report",
      "name": "projects/PROJECT_ID/locations/global/reports/REPORT_ID",
      "dimensions": [
        "location",
        "product_display_name",
        "project",
        "resource",
        "resource_type"
      ],
      "scopes": [
        {
          "project": "projects/PROJECT_ID"
        }
      ],
      "filter": "hour >= now - duration(\"168h\")",
      "expireTime": "2026-02-05T18:50:25.273833857Z",
      "metrics": [
        "cost",
        "cpu_mean_utilization"
      ]
    }
  }
  ```

LRO에서 오류가 발생하면 응답에 response 필드 대신 error 필드가 포함되어 실패에 관한 세부정보를 제공합니다.

작업이 완료되면 보고서의 데이터를 읽을 수 있습니다.

동시 실행 제한

보고서를 만들면 App Optimize API가 Cloud Billing에서 비용 데이터를 가져오고 Cloud Monitoring에서 보고서의 각 target_project에 대한 사용률 데이터를 가져옵니다.

단일 프로젝트로 범위가 지정된 보고서의 경우 해당 프로젝트가 타겟 프로젝트입니다.
App Hub 애플리케이션의 경우 애플리케이션의 서비스 또는 워크로드가 포함된 각 프로젝트가 타겟 프로젝트입니다.

App Optimize API는 동시 CreateReport 작업이라는 동시 실행 할당량을 적용하며, 이를 통해 타겟 프로젝트당 보고서 데이터에 대한 동시 요청을 최대 10개까지 허용합니다. 보고서를 만들면 App Optimize API가 보고서의 타겟 프로젝트 수를 계산하고 보고서 생성 LRO가 완료될 때까지 필요한 할당량 단위를 잠급니다.

몇 분 이내에 완료되는 보고서는 시스템 수준 측정 타이밍으로 인해 동시성 한도에 포함되지 않을 수 있습니다.

Google Cloud 콘솔의 할당량 및 시스템 한도 페이지에서 현재 API 활동을 확인하고 이러한 한도를 관리할 수 있습니다.

여러 보고서를 동시에 만들 계획이라면 팀에서 보고서를 실행하는 시점과 App Hub 애플리케이션의 구조를 고려하세요.

여러 팀에서 동일한 타겟 프로젝트가 포함된 보고서를 실행하는 경우 각 팀의 보고서 생성 시작 시간을 엇갈리게 할 수 있습니다.
애플리케이션은 여러 프로젝트의 리소스를 포함할 수 있으며, 둘 이상의 애플리케이션이 단일 프로젝트의 리소스를 사용할 수 있습니다. 이러한 유형의 애플리케이션에 대해 동시에 보고서를 만들면 타겟 프로젝트에 대한 요청이 여러 개 발생합니다.

예를 들어 크리에이티브 아트를 학습하기 위한 애플리케이션 모음을 표준 및 프리미엄 변형으로 작업하는 팀을 생각해 보겠습니다. 다음 표의 첫 번째 열에는 애플리케이션 목록이 표시됩니다. 나머지 열에서 체크표시 아이콘 ()은 프로젝트에 나열된 애플리케이션의 서비스 또는 워크로드가 포함되어 있음을 나타냅니다.

애플리케이션	common-project	dance-project	draw-project	animate-project	music-project
dance-app
draw-app
music-app
animate-app
choreograph-app
storyteller-app
dance-premium-app
draw-premium-app
music-premium-app
animate-premium-app
choreograph-premium-app
storyteller-premium-app

나열된 모든 애플리케이션의 비용 및 사용량 데이터를 동시에 보고서로 만드는 경우 일부 프로젝트에서 App Optimize API가 동시 실행 제한의 단위를 두 개 이상 사용합니다. 특히 공유 프로젝트 common-project는 비용 및 사용량 데이터에 대한 요청을 12개 수신합니다. 이 숫자는 동시성 한도를 초과하므로 데이터 요청 2개가 실패합니다.

이 문제를 방지하려면 먼저 애플리케이션의 표준 버전에 대한 보고서를 실행한 다음 프리미엄 버전에 대한 보고서를 실행하면 됩니다.

다음 단계

측정기준, 측정항목, 필터를 이해하려면 보고서 정보를 참고하세요.
보고서를 관리하는 다른 방법을 살펴보세요.

보고서 생성 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

gcloud

Python

REST

필요한 역할

보고서 생성

gcloud

Python

REST

동시 실행 제한

다음 단계

보고서 생성