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ê usa a API REST.

Antes de começar

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

Esse projeto é escolhido por você e identificado por PROJECT_ID. Para simplificar, neste guia, seu projeto vai hospedar o recurso de relatório e fornecer o escopo de dados.

A API App Optimize permite criar relatórios em um projeto que analisam dados de um projeto de origem diferente ou de aplicativos em limites de projeto único ou no nível da pasta. Se você estiver gerando um relatório em um aplicativo do App Hub, que pode ser composto de vários projetos, precisará 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. Nos exemplos desta documentação, esse é o projeto identificado por PROJECT_ID.

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.

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.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Verifique se você tem as permissões necessárias para concluir este guia.

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.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Verifique se você tem as permissões necessárias para concluir este guia.

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, envie uma solicitação HTTP POST ao caminho do recurso projects.locations.reports da API REST.

Siga estas etapas para criar o relatório.

Use o seguinte comando curl para enviar a solicitação:

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 estejam 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, use o método personalizado :read depois que a LRO for concluída:

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 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, envie uma solicitação HTTP DELETE ao endpoint de 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.