Geração de relatórios da Plataforma Google Maps

É importante monitorar o uso, a cota e o faturamento da Plataforma Google Maps com frequência. Isso ajuda a rastrear as solicitações feitas por projetos, permanecer dentro dos limites de consumo predefinidos e controlar os custos com orçamentos planejados. Esse monitoramento também ajuda a detectar interações inesperadas entre seus projetos e os serviços da Plataforma Google Maps.

Console do Cloud

É possível monitorar o uso, a cota e o faturamento da Plataforma Google Maps usando o Console do Google Cloud, também conhecido como Console do Cloud.

APIs e serviços

A seção APIs e serviços do Console do Cloud exibe as métricas de uso para todas as APIs ativadas no seu projeto: as APIs e os SDKs da Plataforma Google Maps, bem como outras APIs e serviços do Google.

APIs e serviços

Para ver a seção "APIs e serviços", faça o seguinte:

  1. Abra o Console do Cloud.
  2. Selecione um projeto.
  3. Clique no botão de menu menu e em APIs e serviços.

Plataforma Google Maps

A seção Plataforma Google Maps do Console do Cloud exibe apenas as métricas de uso e cotas para as APIs e os SDKs da Plataforma Google Maps, chamados a partir de agora de APIs da Plataforma Google Maps ou simplesmente APIs.

Painel do Google Maps

Para acessar a Plataforma Google Maps:

  1. Abra o Console do Cloud.
  2. Selecione um projeto.
  3. Clique no botão de menu menu, role a tela para baixo até OUTRAS SOLUÇÕES DO GOOGLE e clique em Plataforma Google Maps.

Faturamento

A seção Faturamento do Console do Cloud exibe informações sobre cobranças e custos relacionados ao projeto que você selecionou.

Painel de faturamento

Para ver a seção "Faturamento", faça o seguinte:

  1. Abra o Console do Cloud.
  2. Selecione um projeto.
  3. Clique no botão de menu menu e em Faturamento.
  4. Se você tiver várias contas de faturamento, clique em Acessar a conta de faturamento vinculada.
    Será exibida a página Visão geral para a conta de faturamento vinculada.
  5. No menu à esquerda, clique em Relatórios.
    Será exibida a página Relatórios para a conta de faturamento vinculada.

Relatórios de uso

O uso é calculado com base no número de solicitações que o projeto faz para as APIs da Plataforma Google Maps usando as credenciais associadas a ele. Isso inclui as solicitações bem-sucedidas, aquelas que resultam em erros no servidor e as que resultam em erros do cliente. As credenciais contêm as chaves de API e IDs de cliente (para plano Premium e projetos Premium migrados).

As métricas de uso são exibidas em tabelas (solicitações, erros e latência) e gráficos (tráfego, erros e latência). Para fins de rastreamento, as seguintes condições se aplicam:

  • As métricas de uso de todas as APIs podem ser filtradas por período e API. Também é possível ver tráfego, erro e latência agrupados por código de resposta, API e credencial.
  • As métricas de uso de uma API específica podem ser filtradas por período e por versões, credenciais e métodos dela. Também é possível ver tráfego, erro e latência agrupados por credencial, código de resposta e método e versão da API.

Página do painel de APIs e serviços

A página Painel de APIs e serviços fornece uma visão geral das métricas de uso de todas as APIs ativadas no seu projeto: APIs da Plataforma Google Maps, bem como outras APIs e serviços.

A página "Painel" apresenta três gráficos e uma tabela. É possível filtrar o uso exibido nos gráficos e nas tabelas selecionando um período (de 1 hora até os últimos 30 dias).

O gráfico de tráfego detalha o uso em consultas por segundo (QPS) por API. O gráfico "Erros" mostra a porcentagem de solicitações por API que resultaram em erros. O gráfico de latência apresenta a latência média das solicitações por API.

Abaixo dos gráficos, há uma tabela que exibe as APIs e os serviços ativados. As solicitações representam o número de solicitações para o período selecionado. Os erros indicam o número dessas solicitações que resultaram em erros. A latência (média e percentil) é a latência das solicitações.

Para mais informações, consulte Como monitorar o uso da API.

monitoramento de APIs

Página de visão geral do Google Maps

A página Visão geral do Google Maps inclui uma tabela que mostra as APIs ativadas e as solicitações de uso dos últimos 30 dias. As solicitações por API também são exibidas na forma de gráfico. Um gráfico de faturamento detalha a fatura atual e o uso total nos últimos três meses.

Observação: se você clicar no nome de qualquer API ativada, será exibida a página Métricas do Google Maps relativa a essa API.

visão geral

Página de APIs da Plataforma Google Maps

A página APIs do Google Maps inclui duas tabelas. A tabela de APIs ativadas mostra o número de solicitações, o número de erros e a latência média de cada API ativada para os últimos 30 dias. A tabela de APIs complementares exibe as APIs que não foram ativadas, ou seja, nenhum uso foi registrado.

Observação: se você clicar no nome de qualquer API ativada, será exibida a página Métricas do Google Maps relativa a essa API.

APIs

Página de métricas do Google Maps

A página Métricas do Google Maps exibe três gráficos: Tráfego, Erros e Latência média. Os dados de uso dos gráficos podem ser agrupados por Código de resposta, API, Método de API ou Credencial.

Abaixo dos gráficos, a página "Métricas" inclui uma tabela de APIs que mostra solicitações, erros e latência para as APIs escolhidas.

Usando a lista suspensa da API na parte superior e as opções de filtragem no painel à direita, é possível filtrar as métricas de uso exibidas selecionando um ou vários Códigos de resposta, APIs e/ou Credenciais. Também é possível selecionar um período (de 1 hora até os últimos 30 dias) e a granularidade (por segundo ou dia) para as métricas de uso exibidas.

métricas

Gráficos de código de resposta

Os gráficos "Tráfego por código de resposta" e "Erro por código de resposta" detalham o uso por classe de código de resposta. A tabela abaixo mostra o mapeamento entre o status da resposta e a classe de código de resposta da API da Plataforma Google Maps:

Status da resposta Classe do código de resposta
(2xx, 3xx, 4xx, 5xx)
Observações
OK 2xx Resposta bem-sucedida.

Essa é uma solicitação faturável e consumirá a cota.
OK 3xx Resposta bem-sucedida.

Essa é uma solicitação faturável e consumirá a cota.

Por exemplo, as solicitações bem-sucedidas do Place Photo retornam redirecionamento 302 para a imagem referenciada.
ZERO_RESULTS 2xx A resposta foi bem-sucedida, mas não retornou nenhum resultado.

Essa é uma solicitação faturável e consumirá a cota.
NOT_FOUND 2xx Para a API Directions, isso indica que não foi possível geocodificar pelo menos um dos locais especificados na origem, no destino ou nos waypoints da solicitação.

Para a API Places, isso indica que o local referenciado (place_id) não foi encontrado no banco de dados do Places.

Essa é uma solicitação faturável e consumirá a cota.
REQUEST_DENIED 4xx Erro de cliente causado por erros de autenticação, de acesso etc. Verifique a resposta da API para mais detalhes.
OVER_DAILY_LIMIT,
OVER_QUERY_LIMIT,
RESOURCE_EXHAUSTED,
rateLimitExceeded,
dailyLimitExceeded,
userRateLimitExceeded
4xx Erro de cliente causado por muitas solicitações no período permitido. Tente fazer a solicitação mais tarde. Veja a resposta da API para mais detalhes.
INVALID_REQUEST (parâmetro inválido ou ausente, erro de análise de solicitação) 4xx Erro de cliente causado por uma solicitação inválida. Veja a resposta da API para mais detalhes.
NOT_FOUND (404) 4xx Para a API Geolocation, isso indica que as entradas não foram suficientes para produzir uma estimativa de local.

Para a API Roads, isso indica que as entradas não puderam ser correspondidas em vias.

Essa é uma solicitação faturável e consumirá a cota.
INVALID_REQUEST (valor de parâmetro inválido),
MAX_WAYPOINTS_EXCEEDED,
MAX_ROUTE_LENGTH_EXCEEDED etc.
4xx Erro causado por um valor de parâmetro inválido, por um excesso de valores fornecidos etc. Verifique a resposta da API para mais detalhes.

Essa é uma solicitação faturável e consumirá a cota.
UNKNOWN_ERROR 5xx Erro de servidor indicando que não é possível prosseguir com a solicitação: erro interno, serviço sobrecarregado ou indisponível, erro de tempo excedido etc.

Para mais informações sobre códigos de status e mensagens de erro, consulte a documentação de resposta da API que você quer usar (por exemplo, Respostas da API Geocoding ou Respostas da API Directions).

Relatórios de cotas

As cotas definem limites quanto ao número de solicitações que seu projeto pode fazer para as APIs da Plataforma Google Maps. As solicitações podem ser limitadas de três maneiras: por dia, por segundo e por usuário por segundo. Somente as solicitações bem-sucedidas e as que causam erros de servidor são contabilizadas na cota (aquelas que causam erros de cliente não são).

O uso da cota é exibido nos gráficos e pode ser agrupado em solicitações por dia ou por 100 segundos. Os limites de cota atuais para as APIs selecionadas são mostrados nas tabelas abaixo dos gráficos de uso da cota.

Página de cotas do Google Maps

A página Cotas do Google Maps apresenta os limites e o consumo de cota da API selecionada.

O gráfico de uso de cota no Console do Google Cloud mostra o tráfego total das chaves de API e dos IDs de cliente. O tráfego do ID do cliente também está disponível no gráfico de métricas no Console do Cloud. Para saber mais, consulte o Problema 158809616 (em inglês).

A página exibe apenas as solicitações que consomem cota: solicitações bem-sucedidas (OK, ZERO_RESULTS) e solicitações que causam erros de servidor (NOT_FOUND, INVALID_VALUE, UNKNOWN_ERROR).

Solicitações que causam erros de cliente (erros de autenticação/autorização/argumentos inválidos REQUEST_DENIED, OVER_QUERY_LIMIT, INVALID_REQUEST) não consomem a cota e não são exibidas.

A unidade de cota é uma solicitação para a maioria das APIs da Plataforma Google Maps (API Static Maps, API Street View Static, API Geocoding, API Directions, API Timezone, API Geolocation e API Elevation). Mas há algumas exceções:

  • Na API Distance Matrix, a unidade de cota é um elemento, que é um par de origem e destino.
  • Na API Maps JavaScript, é um carregamento de mapa.
  • No SDK do Maps para Android e no SDK do Maps para iOS, a unidade de cota é uma solicitação do Street View/carregamento de panoramas (os carregamentos de mapa são gratuitos e não consomem cota).
cotas

Unidades de cota

A tabela abaixo mostra a unidade de cota das APIs da Plataforma Google Maps.

API da Plataforma Google Maps Unidade de cota
Maps
SDK do Maps para Android 1 panorama
SDK do Maps para iOS 1 panorama
API Maps Static 1 solicitação
API Maps JavaScript 1 carregamento de mapa
API Street View Static 1 solicitação
API Maps Embed 1 carregamento de mapa
Routes
API Directions 1 solicitação
API Distance Matrix 1 elemento (par de origem e destino)
API Roads 1 solicitação
Places
API Places 1 solicitação
API Geocoding 1 solicitação
API Geolocation 1 solicitação
API Time Zone 1 solicitação

Relatórios de faturamento

Ver seu relatório de faturamento

Os relatórios de faturamento para uso dos produtos da Plataforma Google Maps estão disponíveis no Console do Google Cloud (acesse Faturamento).

Como ler o gráfico do relatório de faturamento

Os relatórios de faturamento exibem o custo ao longo do tempo como um gráfico de linhas empilhadas. A visualização padrão mostra os custos diários de uso do mês atual agrupados por projeto para todos os produtos. Isso inclui todos os créditos de uso aplicados, bem como o total de custos previstos para todo o mês atual. Cada linha do gráfico e da tabela de resumo corresponde a um projeto, classificados por custo: do menor ao maior. Saiba mais sobre como interpretar o gráfico do relatório de faturamento.

relatórios de faturamento
Figura 1: o relatório de faturamento exibindo o gráfico e a tabela na visualização predefinida padrão.

Dica: analisar o uso e o custo por SKU

Para entender melhor os detalhes do modelo de preços de pagamento por utilização e como ele afeta a implementação, veja seu uso e custo por SKU.

Relatório de faturamento agrupado por SKU
Figura 2: a tabela de faturamento exibindo o uso e os itens de linha de custo por SKU.
Filtros do relatório de faturamento
Figura 3: os filtros do relatório de faturamento.
Alterar a vista de relatórios para exibir itens de linha por SKU:
  1. No painel à direita do gráfico, abra o filtro Agrupar por.
  2. Selecione a SKU.

Outros filtros do relatório de faturamento disponíveis incluem Intervalo de tempo, Projetos, Produtos, SKUs e Locais, que permitem filtrar pelo local em que as solicitações de API são exibidas.

Para categorizar a origem do uso, além do produto, agrupe os relatórios de faturamento por um dos valores listados. As três chaves relacionadas às APIs da Plataforma Google Maps são: goog-maps-api-key-suffix (os últimos quatro caracteres de uma chave de API), goog-maps-platform-type (a plataforma: Android, iOS, JavaScript ou serviço Web) e goog-maps-channel (um valor numérico do canal definido com base em uma consulta da API). Mais informações sobre filtragem e agrupamento.

Altere a visualização do gráfico para excluir os créditos de uso. Basta desmarcar a caixa seleção Incluir créditos no custo no painel à direita.

Monitorar e restringir o consumo

Para planejar seu orçamento e controlar os custos, faça o seguinte:

  • Defina um alerta de orçamento para rastrear o aumento de gastos em relação a um determinado valor. Definir um orçamento não limita o uso da API, apenas avisa quando seu gasto está próximo do valor especificado.
  • Limite o uso diário da API para gerenciar o custo de uso das APIs faturáveis. Ao definir limites nas solicitações por dia, você pode restringir seus gastos. Use uma equação simples para determinar o limite diário, dependendo de quanto você quer gastar. Por exemplo: (gasto mensal / preço unitário)/30 = limite de solicitações por dia (para uma API). Sua implementação pode usar várias APIs faturáveis, então ajuste a equação conforme necessário. Ao fazer o cálculo, lembre-se de que um crédito de US$ 200 da Plataforma Google Maps está disponível todos os meses.

Rastreamento de uso por canal

Para rastrear o uso por meio de canais numéricos, adicione o parâmetro "channel" às solicitações de API. Os únicos valores de canal aceitáveis são números de 0 a 999. Veja alguns exemplos:

  • API Geocoding Web Service

    https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY&channel=1
  • API Maps JavaScript

    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&channel=2&callback=initMap"
    async defer></script>

Monitore o uso do canal diretamente no relatório de faturamento. Os canais serão incluídos em Rótulos como a chave goog-maps-channel.

Filtrar por rótulos
Figura 4: filtrar por SKU e canais
Filtrar seu relatório de faturamento por SKU e canal
  1. Use o filtro de SKU Agrupar por.
  2. Clique no cursor de texto Rótulos.
  3. Clique no menu suspenso Chave e selecione goog-maps-channel.
  4. Clique no menu suspenso Valor e selecione os canais numéricos que você quer filtrar.

Agrupe pela chave de rótulo goog-maps-channel para ver o custo gerado em cada canal.

Depois de implementar os dados de uso de canal nas solicitações, pode haver um pequeno atraso (de até 24 horas) até que os dados sejam aplicados no seu relatório de faturamento.

Exportar dados de faturamento com o BigQuery

É possível também exportar seus dados de faturamento para o BigQuery.

O BigQuery Export permite exportar dados detalhados do Cloud Billing (como dados de uso e de estimativa de custos) automaticamente ao longo do dia para um conjunto de dados do BigQuery especificado. Depois, você poderá acessar seus dados de faturamento do BigQuery para uma análise detalhada. Isso proporciona uma camada adicional de granularidade para entender a origem do uso da Plataforma Google Maps.

Se você quiser começar a usar o BigQuery Export e fazer consultas de dados, veja o exemplo abaixo. Antes de realizar essa consulta, você precisa seguir estas etapas:

  • Ative o faturamento e a exportação de faturamento do BigQuery na sua conta.
  • O formato da tabela é PROJECT_ID.DATASET_NAME.gcp_billing_export_v1_BILLING_ACCOUNT_ID, em que:
    • PROJECT_ID é o ID do projeto real (por exemplo, "my-project-123456").
    • DATASET_NAME é o nome do conjunto de dados que você criou (por exemplo, "SampleDataSet");
    • BILLING_ACCOUNT_ID é uma referência do ID da conta de faturamento, com o prefixo "gcp_billing_export_v1_" e traços (-) substituídos por sublinhados (_). Por exemplo, o ID da conta de faturamento 123456-7890AB-CDEF01 seria gcp_billing_export_v1_123456_789AB_CDEF01.

Observação: quando você cria um novo conjunto de dados, ele aparece na interface imediatamente, mas a tabela a ser consultada ainda não aparece. Ela será gerada automaticamente após algumas horas. Levará aproximadamente 24 horas para ver os dados. O conjunto de dados do BigQuery só reflete os dados de uso e custo gerados a partir da data em que você configurou a exportação de faturamento. Em outras palavras, os dados de faturamento não são adicionados de forma retroativa. Portanto, você não verá os dados de faturamento antes de ativar o BigQuery Export.

  #standardSQL
  SELECT   Date(usage_start_time, "America/Los_Angeles") AS billing_day,
           invoice.month                                 AS invoice_month,
           service.description                           AS service,
           sku.description                               AS sku,
           (
                  SELECT l.value
                  FROM   Unnest(labels) AS l
                  WHERE  l.KEY = 'goog-maps-channel' ) AS goog_maps_channel,
           Round(Sum(usage.amount), 2)                 AS usage_amount,
           usage.unit                                  AS usage_unit,
           Round(Sum(cost), 2)                         AS cost,
           cost_type,
           currency
  FROM     `PROJECT_ID.DATASET_NAME.gcp_billing_export_v1_BILLING_ACCOUNT_ID`
  WHERE    invoice.month = '202002' -- Change the invoice month with the same format as the example.
  GROUP BY billing_day,
           invoice_month,
           service,
           sku,
           goog_maps_channel,
           usage_unit,
           cost_type,
           currency
  ORDER BY billing_day,
           service,
           sku
  

Cloud Billing:

Plataforma Google Maps:

Status de resposta e relatórios

A tabela abaixo mostra o status da resposta e a classe do código de resposta e indica se a solicitação correspondente aparece nos relatórios de uso, cota e/ou faturamento.

Status da resposta Classe do código de resposta
(2xx, 3xx, 4xx, 5xx)
Relatório de uso Relatório de cotas Relatório de faturamento
OK 2xx,
3xx
Sim Sim Sim
ZERO_RESULTS,
NOT_FOUND
2xx Sim Sim Sim
REQUEST_DENIED 4xx Sim Não Não
OVER_DAILY_LIMIT,
OVER_QUERY_LIMIT,
RESOURCE_EXHAUSTED,
dailyLimitExceeded,
rateLimitExceeded,
userRateLimitExceeded
4xx Sim Não Não
INVALID_REQUEST (parâmetro inválido, erro na análise de solicitação) 4xx Sim Não Não
NOT_FOUND (API Geolocation e Roads) 4xx Sim Sim Sim
INVALID_REQUEST (valor de parâmetro inválido),
MAX_WAYPOINTS_EXCEEDED,
MAX_ROUTE_LENGTH_EXCEEDED,
etc.
4xx Sim Sim Sim
UNKNOWN_ERROR 5xx Sim Sim Não