Criar e ler um relatório

Saiba como criar um relatório da API App Optimize sobre seus gastos com Google Cloud, monitorar a geração do relatório e ler os dados resultantes quando eles estiverem prontos. Neste guia de início rápido, você pode usar a API REST ou a biblioteca de cliente Python.

Antes de começar

Os exemplos neste guia exigem um Google Cloud projeto com recursos ativos para análise. A API App Optimize precisa de dados de faturamento e utilização para produzir resultados significativos. Os relatórios executados em projetos novos ou vazios vão ficar vazios.

Neste guia, o projeto identificado como PROJECT_ID fornece o escopo de dados e hospeda o recurso de relatório.

A API App Optimize permite criar relatórios em um projeto que analisam dados de outro projeto ou de aplicativos em limites de projeto único ou no nível da pasta. Para gerar um relatório sobre um aplicativo do App Hub, que pode ser composto por vários projetos, você precisa ter as permissões de monitoramento e faturamento necessárias em todos os projetos associados do aplicativo para criar o relatório.
Verifique se a App Optimize API está ativada no projeto que você vai usar para criar e gerenciar o recurso de relatório.

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
Verify that you have the permissions required to complete this guide.

Verify that you have the permissions required to complete this guide.
Selecione a guia para definir como você quer usar as amostras neste documento:

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

Para informações sobre como configurar a autenticação em um ambiente de produção, consulte Configurar o Application Default Credentials para código executado em Google Cloud na documentação de autenticação do Google Cloud .

Python

Instale a biblioteca de cliente Python para a App Optimize API.
Para usar os exemplos do Python nesta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.
1. Instale a CLI do Google Cloud.
2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.
3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:
```
gcloud auth application-default login
```
  Não é necessário fazer isso se você estiver usando o Cloud Shell.
  
  Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.
Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

Para informações sobre como configurar a autenticação em um ambiente de produção, consulte Configurar o Application Default Credentials para código executado em Google Cloud na documentação de autenticação do Google Cloud .

REST

Para usar as amostras da API REST desta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para gcloud CLI.

Instale a CLI do Google Cloud.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Funções exigidas

Para receber as permissões necessárias a fim de criar e ler um relatório usando este guia de início rápido, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto com recursos ativos:

Administrador do App Optimize (roles/appoptimize.admin)
Leitor (roles/viewer) ou outro papel que conceda billing.resourceCosts.get

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Para mais informações sobre as permissões e os papéis necessários para a App Optimize API, consulte Controle de acesso com o IAM.

Crie um relatório

Este exemplo cria um relatório do gasto total no seu PROJECT_ID escolhido. O relatório detalha os custos por cada produto usado, como Compute Engine e Cloud Storage, e pela SKU e local específicos.Google Cloud O relatório abrange os últimos três dias de dados.

Para criar o recurso de relatório, siga as instruções do seu método preferido:

gcloud

Use o comando gcloud beta app-optimize reports create para criar o relatório.

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

Substitua:

PROJECT_ID: o ID do projeto Google Cloud .
REPORT_ID: um ID exclusivo para seu novo relatório. Por exemplo, my-first-report.

O comando aguarda a conclusão da operação de criação do relatório e, em seguida, retorna o recurso de relatório criado.

Python

O código Python a seguir usa AppOptimizeClient.create_report() para criar um relatório.

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"

# Create the App Optimize client and prepare a request for a new report
client = appoptimize_v1beta.AppOptimizeClient()
report = appoptimize_v1beta.Report(
    dimensions=['location', 'product_display_name', 'project', 'sku'],
    metrics=['cost'],
    filter='hour >= now - duration("72h")',
    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,
)

# Request the creation of the report and wait until the process is done
operation = client.create_report(request=request)
print("Waiting for report creation operation to complete...")
response = operation.result()
print(response)

Substitua:

PROJECT_ID: o ID do projeto Google Cloud .
REPORT_ID: um ID exclusivo para seu novo relatório. Por exemplo, my-first-report.

O método operation.result() aguarda a conclusão da operação de criação do relatório.

REST

Envie uma solicitação HTTP POST para o caminho do recurso projects.locations.reports da API REST.

Para enviar a solicitação, use o seguinte comando 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",
      "sku"
    ],
    "metrics": [
      "cost"
    ],
    "filter": "hour >= now - duration(\"72h\")"
  }' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports?report_id=REPORT_ID"

Substitua:

PROJECT_ID: o ID do projeto Google Cloud .
REPORT_ID: um ID exclusivo para seu novo relatório. Por exemplo, my-first-report.

A API retorna um objeto de operação de longa duração (LRO), que representa o processo de geração de relatórios. Confira um exemplo de resposta:

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

O status "done": false indica que o relatório ainda está sendo gerado. Anote o OPERATION_ID, que será usado na próxima etapa.

Como a geração de relatórios pode levar tempo, é necessário fazer uma pesquisa na LRO até que ela indique que o processo de geração foi concluído e os dados do relatório estão prontos para download.

Para verificar o status do processo de geração, envie uma solicitação HTTP GET para o nome do recurso da operação:

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

Confira a resposta. Se "done" for false, aguarde de 5 a 15 segundos e repita esta etapa. Se "done" for true, o relatório estará pronto.

Confira a seguir um exemplo de resposta quando a operação é concluída:

{
  "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",
    "scopes": [
      {
        "project": "projects/PROJECT_ID"
      }
    ],
    "dimensions": [
      "location",
      "product_display_name",
      "project",
      "sku"
    ],
    "metrics": [
      "cost"
    ],
    "filter": "hour >= now - duration(\"72h\")",
    "expireTime": "2026-02-04T22:05:05Z"
  }
}

Ler os dados do relatório

Para recuperar os dados do relatório, siga as instruções do seu método preferido:

gcloud

Use o seguinte comando gcloud beta app-optimize reports read para buscar os dados do relatório.

gcloud beta app-optimize reports read REPORT_ID \
  --project=PROJECT_ID \
  --location=global

Python

O código Python a seguir usa AppOptimizeClient.read_report() para buscar os dados do relatório.

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"
name = f"projects/{project_id}/locations/global/reports/{report_id}"

# Create the App Optimize client and read your report's data
client = appoptimize_v1beta.AppOptimizeClient()
request = appoptimize_v1beta.ReadReportRequest(
        name=name,
)
result = client.read_report(request=request)

# Display the report's data
print(result)

REST

Quando a LRO for concluída, use o método personalizado :read da API REST:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://appoptimize.googleapis.com/v1beta/projects/PROJECT_ID/locations/global/reports/REPORT_ID:read"

A resposta da API contém as linhas de dados do relatório e as definições de coluna. Confira a seguir um exemplo de resposta bem-sucedida:

{
  "rows": [
    [
      "us-central1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "6EC2-384A-47D9",
      {
        "currency_code": "USD",
        "units": "25",
        "nanos": 750000000
      }
    ],
    [
      "us-central1",
      "Cloud Storage",
      "projects/PROJECT_ID",
      "9ADA-9ADC-2FBE",
      {
        "currency_code": "USD",
        "units": "5",
        "nanos": 100000000
      }
    ],
    [
      "europe-west1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "6EC2-384A-47D9",
      {
        "currency_code": "USD",
        "units": "18",
        "nanos": 500000000
      }
    ],
    [
      "us-central1",
      "Compute Engine",
      "projects/PROJECT_ID",
      "F61D-4D51-AAFC",
      {
        "currency_code": "USD",
        "units": "12",
        "nanos": 200000000
      }
    ]
  ],
  "columns": [
    {
      "name": "location",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "product_display_name",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "project",
      "type": "STRING",
      "mode": "NULLABLE"
    },
    {
      "name": "sku",
      "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"
        }
      ]
    }
  ],
  "next_page_token": ""
}

Os relatórios com muitas linhas são paginados. Para processar várias páginas, consulte Ler os dados de um relatório.

Para entender os valores no campo cost, consulte Como interpretar métricas de custo. Para mais informações sobre os dados e entender as limitações deles, consulte Entender os dados.

Limpar

A API App Optimize exclui automaticamente seu relatório 24 horas após a criação. Para excluir o relatório antes, siga as instruções do seu método preferido:

gcloud

Use o comando gcloud beta app-optimize reports delete para remover o relatório.

gcloud beta app-optimize reports delete REPORT_ID \
  --project=PROJECT_ID \
  --location=global

Python

O código a seguir usa AppOptimizeClient.delete_report() para remover o relatório.

from google.cloud import appoptimize_v1beta

project_id = "PROJECT_ID"
report_id = "REPORT_ID"

name = f"projects/{project_id}/locations/global/reports/{report_id}"
client = appoptimize_v1beta.AppOptimizeClient()
request = appoptimize_v1beta.DeleteReportRequest(name=name)
client.delete_report(request=request)
print(f"Deleted report: {name}")

REST

Envie uma solicitação HTTP DELETE para o endpoint do recurso do relatório:

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

A seguir

Saiba mais sobre os relatórios.
Conheça outras maneiras de gerenciar relatórios:
Consulte a visão geral da App Optimize API.