O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Sobre os relatórios de custo e uso

Para ajudar você a entender e gerenciar seus custos Google Cloud , a API App Optimize permite criar relatórios com parâmetros especificados, como escopo, dimensões, período e filtros.

Para recuperar dados de custo e utilização com a API App Optimize, primeiro crie um recurso de relatório em um projeto Google Cloud de sua escolha. Esse recurso funciona como uma definição persistente dos dados que você quer analisar.

O projeto que armazena seu relatório não precisa ser a fonte dos dados dele. É possível criar um relatório em um projeto que analisa dados de outro projeto de origem ou de um aplicativo do App Hub.

Depois que você cria um relatório, a API gera os dados solicitados de forma assíncrona. Em seguida, use o nome do recurso do relatório para buscar o conjunto de dados resultante quando o relatório estiver pronto.

O fluxo de trabalho é o seguinte:

Você cria um relatório especificando seus critérios.
O sistema processa essa solicitação de forma assíncrona.
Quando a operação for concluída, leia os dados resultantes.

Este documento detalha a estrutura e os parâmetros configuráveis dos relatórios da API App Optimize, incluindo dimensões, métricas e opções de filtragem disponíveis, e explica o formato dos dados retornados.

Para informações sobre limitações de custo e utilização, consulte Entender os dados.

Definir um relatório

Para criar um relatório, defina um recurso Report com os seguintes parâmetros de configuração, que são descritos nas próximas subseções:

Parâmetro	Tipo	Descrição
`scopes`	Matriz	O projeto ou aplicativo do App Hub a ser analisado. Você precisa fornecer exatamente um elemento de escopo.
`dimensions`	Matriz	Os atributos para recuperar e agrupar os dados, incluindo agrupamentos com base em tempo.
`metrics`	Matriz	As medições específicas a serem retornadas.
`filter`	String	Uma expressão da Common Expression Language (CEL) para restringir os dados, incluindo intervalos de tempo.

Escopos

O campo scopes define o conjunto de recursos que a API App Optimize vai analisar. Embora o campo seja uma matriz, você precisa especificar exatamente um elemento, que pode ser um projeto ou um aplicativo do App Hub:

project: uma string que representa um projeto Google Cloud . Ele precisa ser formatado como:
```
projects/PROJECT_ID
```
Substitua PROJECT_ID pelo ID do projeto Google Cloud a ser analisado. Por exemplo, projects/my-project-1.
application: uma string que representa o nome completo do recurso de um aplicativo do App Hub. Ele precisa estar no formato:
```
projects/PROJECT_ID/locations/LOCATION/applications/APPLICATION_ID
```
Substitua:
- PROJECT_ID: o ID do projeto host do App Hub.
- LOCATION: a região do aplicativo App Hub, como us-central1.
- APPLICATION_ID: o ID do aplicativo do App Hub.
Por exemplo, projects/my-host-proj/locations/us-central1/applications/my-app

Confira exemplos de matrizes scopes em JSON para uma solicitação de criação de relatório, mostrando um único elemento de escopo:

Escopo por projeto:

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

Escopo por aplicativo:

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

Dimensões

As dimensões determinam quais dados são retornados e como eles são agrupados. Por exemplo, se você selecionar project e product_display_name, a saída vai conter uma linha para cada combinação exclusiva de valores de projeto e nome do produto encontrada nos dados.

Confira uma tabela de dimensões compatíveis:

Dimensão	Tipo	Descrição	Valor de exemplo
`project`	STRING	O ID do projeto Google Cloud .	`projects/my-project`
`application`	STRING	O aplicativo do App Hub.	`projects/my-project/locations/us-central1/applications/my-app`
`service_or_workload`	STRING	O serviço ou a carga de trabalho do App Hub.	`projects/my-project/locations/us-central1/applications/my-app/services/my-service`
`resource`	STRING	O nome completo do recurso.	`//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/vm-1`
`resource_type`	STRING	O tipo de recurso da API.	`compute.googleapis.com/Instance`
`location`	STRING	A Google Cloud região ou multirregião.	`us-east1`
`sku`	STRING	O ID da SKU de faturamento.	`4496-8C0D-228F`
`product_display_name`	STRING	O nome do produto Google Cloud .	`Compute Engine`
`month`	STRING	O ano e o mês.	`2024-01`
`day`	STRING	O ano, o mês e o dia.	`2024-01-10`
`hour`	STRING	O ano, o mês, o dia e a hora.	`2024-01-10T00`

A dimensão location representa a Google Cloud região ou multirregião a que os custos e o uso são atribuídos. A forma como esse local é informado depende das configurações de localização dos recursos no escopo do relatório:

Para recursos implantados em uma zona específica, como us-central1-a, os custos e o uso são agregados e atribuídos à região principal. Neste exemplo, a dimensão location mostraria us-central1.
Para recursos implantados em uma região, como us-central1, a dimensão location reflete essa região específica.
Para recursos implantados ou configurados para uma multirregião, como us, a dimensão location reflete essa multirregião.

Dimensões de tempo

Para agregar resultados por tempo, inclua pelo menos uma dimensão de tempo, como month, day ou hour, na lista dimensions. Observação importante:

Todas as dimensões de tempo usam o horário do Pacífico e respeitam o horário de verão (DST).
Os formatos seguem o padrão ISO 8601.
Se o período no filter não estiver perfeitamente alinhado com a granularidade da dimensão de tempo selecionada, ele será expandido para abranger os períodos completos. Por exemplo, filtrar parte de um dia com dimension: ["month"] vai incluir dados de todo o mês.

Métricas

As métricas são os valores quantitativos que você quer medir para cada grupo definido pelas dimensões.

Métricas de custo

Métrica de custo	Tipo	Descrição
`cost`	RECORD	O custo monetário na moeda solicitada.
`network_cost`	RECORD	Custo total de rede, incluindo transferência e tratamento de dados.
`network_cost_standard_internet`	RECORD	Custo total da transferência de dados do nível Standard.
`network_cost_premium_internet`	RECORD	Custo total da transferência de dados do nível Premium.
`network_cost_inter_region`	RECORD	Custo total da transferência de dados entre regiões.
`network_cost_inter_zone`	RECORD	Custo total da transferência de dados entre zonas.
`network_cost_load_balancing_inbound`	RECORD	Custo total do tratamento de dados de entrada pelo Cloud Load Balancing.
`network_cost_load_balancing_outbound`	RECORD	Custo total do processamento de dados de saída pelo Cloud Load Balancing.
`network_cost_interconnect_inbound`	RECORD	Custo total da transferência de dados de entrada pelo Cloud Interconnect.
`network_cost_interconnect_outbound`	RECORD	Custo total da transferência de dados de saída pelo Cloud Interconnect.
`resource_cost`	RECORD	Custo total de recursos.

Métricas de utilização

Métrica de utilização	Tipo	Descrição
`cpu_mean_utilization`	FLOAT64	Utilização média da CPU (0,0 a 1,0).
`cpu_p95_utilization`	FLOAT64	Uso da CPU no 95º percentil (0,0 a 1,0).
`cpu_usage_core_seconds`	INT64	Trabalho total da CPU realizado.
`cpu_allocation_core_seconds`	INT64	Capacidade total de CPU provisionada.
`memory_mean_utilization`	FLOAT64	Uso médio da memória (0,0 a 1,0).
`memory_p95_utilization`	FLOAT64	Uso da memória do 95º percentil (0,0 a 1,0).
`memory_usage_byte_seconds`	INT64	Memória total usada ao longo do tempo.
`memory_allocation_byte_seconds`	INT64	Total de memória provisionada ao longo do tempo.

Combinações válidas

Nem todas as dimensões podem ser combinadas com todas as métricas na API App Optimize. A tabela a seguir mostra exemplos de conjuntos de dimensões válidos e as métricas que podem ser usadas com eles. A API vai retornar um erro se uma combinação inválida for solicitada. Consulte esse erro para ver as combinações válidas.

Dimensões	Suporte à métrica `cost`	Suporte à métrica `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`

Filtros

Use o campo filter para restringir os dados usando uma string CEL. É possível criar expressões de filtro usando qualquer um dos campos listados na tabela Dimensões.

A filtragem precisa obedecer a estas restrições:

Todos os predicados de campo de string precisam usar correspondências exatas de string. Por exemplo, location == 'us-east1'
Vários predicados que se referem ao mesmo campo de string precisam ser unidos usando o operador lógico OR, ||. Por exemplo, location == 'us-east1' || location == 'us-west1'.
Todos os outros predicados precisam ser unidos usando o operador lógico AND, &&.
Um predicado em uma dimensão de tempo, como day, que especifica o horário de início precisa usar a comparação maior ou igual a, >=.
Um predicado em uma dimensão de tempo que especifica o horário de término precisa usar a comparação menor que, <.

período

Se o filter omitir dimensões de tempo (month, day, hour), o relatório vai usar um intervalo de sete dias que termina na meia-noite anterior do Horário do Pacífico, respeitando o horário de verão. O período máximo é de 90 dias antes da data atual, e o horário de início precisa estar dentro da janela de 90 dias.

Por exemplo, se o horário atual do Pacífico for 2026-01-05T12:00:00, o intervalo padrão será das 2025-12-29T00:00:00 às 2026-01-05T00:00:00 no horário do Pacífico. O horário de início mais próximo para o período é 2025-10-07T00:00:00.

As métricas do Cloud Run estão disponíveis apenas por seis semanas antes da data atual.

Exemplos de filtros

Confira alguns exemplos de como estruturar suas strings de filtro CEL:

Para filtrar os dados do relatório por um tipo de recurso específico, use o operador == na dimensão resource_type:
```
resource_type == 'compute.googleapis.com/Instance'
```
Para incluir apenas dados de um único local, filtre pela dimensão location:
```
location == 'us-east1'
```
Para incluir dados de uma lista específica de locais, use o operador || para combinar condições na dimensão location:
```
location == 'us-east1' || location == 'us-west1'
```
Para receber dados em um período específico usando granularidade por hora, filtre pela dimensão hour. Este exemplo inclui dados do início de 2024-01-01 até 2024-02-01, mas não inclui essa data:
```
hour >= timestamp('2024-01-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```
Para filtrar dias inteiros, use a dimensão day. Os limites de dia são interpretados no horário do Pacífico. Por isso, especificar o ajuste é uma prática recomendada. Este exemplo inclui todos os dados de 15/03/2024 e 16/03/2024:
```
day >= timestamp('2024-03-15T00:00:00-07:00') && day < timestamp('2024-03-17T00:00:00-07:00')
```
Da mesma forma, é possível filtrar por meses do calendário usando a dimensão month, sempre considerando o horário do Pacífico para os limites exatos. Este exemplo inclui todos os dados de outubro e novembro de 2025:
```
month >= timestamp('2025-10-01T00:00:00-07:00') && month < timestamp('2025-12-01T00:00:00-08:00')
```
Para receber dados das últimas 72 horas, use as funções now() e duration() na dimensão hour:
```
hour >= now() - duration('72h')
```
Para acessar dados dos últimos sete dias, use duration() com a dimensão hour:
```
hour >= now() - duration('168h')
```
Para filtrar um mês civil específico, como o anterior, é necessário calcular os carimbos de data/hora de início e fim no código do aplicativo. Em seguida, insira esses carimbos de data/hora calculados na expressão CEL. Conceitualmente, ela pode ter esta aparência, filtrando na dimensão day:
```
day >= timestamp('START_OF_LAST_MONTH') && day < timestamp('START_OF_THIS_MONTH')
```
Substitua:
- START_OF_LAST_MONTH: a string de carimbo de data/hora ISO 8601 que representa o início do mês anterior no fuso horário do Pacífico, como 2025-12-01T00:00:00-08:00.
- START_OF_THIS_MONTH: a string de carimbo de data/hora ISO 8601 que representa o início do mês atual no fuso horário do Pacífico, como 2026-01-01T00:00:00-08:00.
Você precisa calcular essas strings de carimbo de data/hora exatas no código do aplicativo, considerando a data atual, o fuso horário (horário do Pacífico) e as transições do horário de verão.
É possível combinar filtros de string e de tempo usando o operador &&. Este exemplo filtra dois locais em um período específico de dois meses:
```
(location == 'us-east1' || location == 'us-west1') && hour >= timestamp('2023-12-01T00:00:00Z') && hour < timestamp('2024-02-01T00:00:00Z')
```

Confira um exemplo mais complexo que combina resource_type, project e um período com base em 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')

Estrutura de dados do relatório

Quando você lê um relatório, o serviço retorna os dados como columns e rows.

Colunas

A matriz columns descreve o esquema dos dados na ordem em que cada campo aparece no rows. Cada objeto na matriz columns tem um name, type e, às vezes, um columns aninhado se o tipo for RECORD.

As dimensões solicitadas aparecem como campos do tipo STRING.
As métricas solicitadas aparecem como campos com tipos como INT64, FLOAT64 ou RECORD para tipos complexos como cost.

Por exemplo, com a API REST, se você solicitar dimensions: ["application", "product_display_name"] e metrics: ["cost", "cpu_mean_utilization"], a API App Optimize em resposta vai gerar uma matriz columns assim:

"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"
  }
]

Linhas

O campo rows contém os dados reais. Cada linha é uma matriz de valores que representa um único registro. A ordem dos valores em cada matriz interna corresponde diretamente à ordem dos campos definidos na matriz columns.

Continuando o exemplo em que application, product_display_name, cost e cpu_mean_utilization foram solicitados da API REST, uma única linha na matriz rows gerada pode ser assim:

"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
  ]
]

A tabela a seguir mostra como os valores em uma matriz de linha única são mapeados para o esquema definido na matriz columns, usando o índice do valor na matriz de linha:

Índice na linha	Coluna correspondente	Tipo	Valor de exemplo
0	`application`	STRING	`"//apphub.googleapis.com/.../applications/my-app"`
1	`product_display_name`	STRING	`"Cloud Storage"`
2	`cost`	RECORD	`{ "currency_code": "USD", "units": "10", ... }`
3	`cpu_mean_utilization`	FLOAT64	`0.65`

Cada elemento na lista rows é uma matriz em que a ordem dos valores corresponde à ordem das definições de campo na matriz columns. Assim, o valor no índice n em qualquer matriz de linha corresponde à coluna definida no índice n na matriz columns.

Como interpretar métricas de custo

Quando um relatório inclui a métrica cost, o valor é retornado como um RECORD que contém os seguintes campos, com base no tipo padrão google.type.Money:

Campo	Tipo	Descrição
`currency_code`	STRING	O código de moeda ISO 4217 de três letras, como "USD".
`units`	INT64	As unidades inteiras do montante.
`nanos`	INT64	As unidades nano (10^-9) do valor. Precisa estar entre -999.999.999 e +999.999.999 (inclusive).

Para saber o valor monetário total, combine os campos units e nanos. O campo nanos representa a parte fracionária do valor da moeda. Exemplo:

Se currency_code for "USD", units será 106 e nanos será 321590000: O valor é 106 + (321.590.000 / 1.000.000.000) = 106,32159 BRL.
Se currency_code for "EUR", units for 5 e nanos for 750000000: O valor será 5 + (750.000.000 / 1.000.000.000) = 5,75 EUR.

Normalmente, você usaria uma biblioteca de formatação de moeda padrão para mostrar esse valor em um formato fácil de usar, incluindo o símbolo de moeda adequado.

Para mais informações sobre os dados retornados pela API e entender as limitações dela, consulte Entender os dados.

Expiração do relatório

Cada relatório é excluído automaticamente do serviço da API App Optimize 24 horas após a criação. Depois disso, não será possível recuperar o relatório e os dados dele pela API. Para verificar o horário de expiração programada de um relatório, extraia os metadados e consulte o campo expireTime.