Criar e ler um relatório

Saiba como criar um relatório da API App Optimize dos Google Cloud custos de recursos, monitorar a geração do relatório e ler os dados resultantes quando 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 estarão 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 oferece suporte à criação de relatórios em um projeto que analisa dados de outro projeto ou de aplicativos em limites de projeto único ou de pasta. Para gerar um relatório em 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 API App Optimize está ativada para o projeto que você usará para criar e gerenciar o recurso de relatório.

gcloud

No Google Cloud console, ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do Google Cloud console, uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a Google Cloud CLI 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 em execução em Google Cloud na Google Cloud documentação de autenticação.

Python

  1. Instale a biblioteca de cliente Python para a API App Optimize.

  2. 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 Google Cloud CLI.

    2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud 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.

    Saiba mais em Configurar o ADC para um ambiente de desenvolvimento local na Google Cloud documentação de autenticação do.

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

REST

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

    Instale a Google Cloud CLI.

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

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

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

Funções exigidas

Para receber as permissões necessárias para 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:

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 com papéis personalizados ou outros papéis predefinidos.

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

Crie um relatório

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

Para criar o recurso de relatório, siga as instruções do 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 Google Cloud projeto.
  • REPORT_ID: um ID exclusivo para o novo relatório, por exemplo, my-first-report

O comando aguarda a conclusão da operação de criação do relatório e 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 Google Cloud projeto.
  • REPORT_ID: um ID exclusivo para o 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.

  1. Para enviar a solicitação, use o seguinte curl comando:

    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 Google Cloud projeto.
    • REPORT_ID: um ID exclusivo para o 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, porque você o usará na próxima etapa.

  2. Como a geração de relatórios pode levar tempo, é necessário consultar a 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 for 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 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

Depois que 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 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 o relatório 24 horas após a criação. Para excluir o relatório antes, siga as instruções do 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