Configurar a API Map Tiles

Desenvolvedores do Espaço Econômico Europeu (EEE)

Neste documento, descrevemos as etapas para começar a usar a API Map Tiles.

Pré-requisitos

Este procedimento orienta você na configuração de uma conta do Google Cloud e de um projeto na nuvem com o faturamento ativado. Também é importante saber como as cobranças pelo uso da API Map Tiles são feitas.

  1. Consulte o faturamento e o custo de uso em Uso e faturamento da API Map Tiles.

  2. Verifique se você tem uma Conta do Google Cloud.

    Faça login no console do Google Cloud

  3. Verifique se você tem um projeto do Google Cloud com o faturamento ativado.

    Acessar a página "Faturamento"
    1. Selecione o projeto para abrir a página Faturamento.

    2. Na página Faturamento:

      • Se o faturamento já estiver ativado para o projeto selecionado e você tiver apenas uma conta de faturamento, a página Faturamento será aberta.
      • Se você tiver várias contas de faturamento, selecione Acessar a conta de faturamento vinculada para ver os detalhes da conta de faturamento associada ao projeto.
      • Se uma conta de faturamento existir, mas não estiver associada ao projeto, será solicitado que você vincule uma conta de faturamento ao projeto.
      • Se não houver uma conta de faturamento ou se você quiser criar uma nova, selecione Gerenciar contas de faturamento para criar uma nova conta de faturamento. Para mais informações, consulte Criar uma nova conta do Cloud Billing de autoatendimento.

Ativar a API

Antes de usar a API Map Tiles, use o console do Google Cloud ou o comando gcloud para ativá-la no seu projeto na nuvem do Google Cloud.

Para ativar a API:

Console

  1. Abra a página do produto no console do Google Cloud:

    Ativar a API Map Tiles

  2. Clique no botão Ativar.

gcloud

gcloud services enable \
    --project "PROJECT" \
    "tile.googleapis.com"

Saiba mais sobre o SDK Google Cloud, a instalação do SDK Cloud e os seguintes comandos:

Receber uma chave de API para usar com a API Map Tiles

Para proteger os produtos da Plataforma Google Maps contra uso não autorizado, as chamadas de API precisam incluir uma chave de API ou um token OAuth. O procedimento da chave de API vem primeiro. Para usar um token OAuth, consulte Criar um token OAuth.

Uma chave de API é uma string alfanumérica exclusiva que associa sua conta do Cloud Billing e o projeto na nuvem do Google Cloud à solicitação que seu aplicativo faz a uma API ou um SDK da Plataforma Google Maps. Para criar uma nova chave ou adicionar uma API ou um SDK a uma chave, siga estas instruções.

Console

  1. Acesse a página Plataforma Google Maps > Chaves e credenciais.

    Acessar a página Chaves e credenciais

  2. Se solicitado, selecione o projeto.

  3. Escolha uma destas opções:

    • Crie uma nova chave:

      1. Clique em Criar credenciais > Chave de API.
      2. No painel Criar chave de API, abra a lista Selecionar restrições de API.
      3. Remova as APIs que não são necessárias para essa chave e verifique se a API Map Tiles permanece selecionada.
      4. Clique em Criar. O painel mostra sua nova chave de API.

    • Usar uma chave atual:

      1. Clique no nome da chave.
      2. Na lista Selecionar restrições da API, escolha API Map Tiles.
      3. Clique em Salvar.

    Selecionar uma API aqui não a ativa. Verifique se a API Map Tiles está ativada na página da biblioteca de APIs.

  4. Para ver a string da chave mais tarde, acesse a página Chaves e credenciais e clique em Mostrar chave.

Se o console estiver diferente do que é mostrado nestas etapas, consulte Criar uma chave de API e Adicionar restrições de API na documentação do Google Cloud.

gcloud

Substitua PROJECT_ID pelo ID do projeto nos comandos a seguir.

  • Crie uma nova chave: execute o comando a seguir e substitua DISPLAY_NAME por um nome para a chave. 

    gcloud services api-keys create \
    --project="PROJECT_ID" \
    --display-name="DISPLAY_NAME" \
    --api-target=service=tile.googleapis.com

    Saiba mais sobre o SDK Google Cloud, a instalação do SDK Cloud e os seguintes comandos:

  • Usar uma chave atual: execute o comando a seguir e substitua KEY_ID pelo ID da chave. A flag --append mantém as APIs que a chave já permite. Sem ele, o comando as substitui.

    gcloud services api-keys update KEY_ID \
    --project="PROJECT_ID" \
    --append \
    --api-target=service=tile.googleapis.com

    Saiba mais sobre o SDK Google Cloud, a instalação do SDK Cloud e os seguintes comandos:

    O ID da chave não é a string de chave nem o nome de exibição. Para encontrá-lo, execute gcloud services api-keys list --project="PROJECT_ID". O ID é a última parte do campo name: projects/PROJECT_NUMBER/locations/global/keys/KEY_ID.

Para ver a string de chave, execute gcloud services api-keys get-key-string KEY_ID --project="PROJECT_ID".

Fazer uma solicitação de API

Faça uma solicitação de API Map Tiles para retornar uma resposta JSON de uma consulta que contém um token de sessão para um bloco de mapa 2D. É preciso incluir a string alfanumérica da chave de API em todas as solicitações e usar HTTPS para solicitações que incluem a chave de API.

  1. Clique em API_KEY no código abaixo para inserir a string alfanumérica da chave:

    curl -X POST \
-H "Content-Type: application/json" \
 -d '{
  "mapType": "roadmap",
  "language": "en-US",
  "region": "US"
}' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"
  2. Clique no ícone de cópia no exemplo de código, Selecione o ícone de cópia., para copiar o comando curl.
  3. Cole o comando em uma janela do terminal e execute-o.

A resposta é um objeto JSON no formato:

{
  "session": "AJVsH2yfm-qbTsquzjqT_mZpa6zjxUDJHQayGufwg",
  "expiry": "1738183946",
  "tileWidth": 256,
  "imageFormat": "png",
  "tileHeight": 256
}

Aplicar restrições de chave de API

O Google recomenda que você restrinja as chaves de API limitando o uso somente às APIs e aos apps que precisam delas. Restringir chaves de API adiciona segurança ao seu aplicativo, protegendo-o contra solicitações não autorizadas. As chaves de API são compatíveis com dois tipos de restrições:

  • As restrições de API especificam quais SDKs e APIs podem ser chamados com a chave de API. O console e a CLI gcloud exigem pelo menos uma restrição de API quando você cria uma chave.
  • As restrições de aplicativo especificam quais sites, endereços IP ou apps podem usar uma chave de API.

Para mais informações sobre como aplicar restrições, consulte Restringir suas chaves de API.

Criar um token OAuth

A API Map Tiles é compatível com o OAuth 2.0 para autenticação. O Google é compatível com cenários comuns do OAuth 2.0, como os de um servidor da Web.

Neste documento, descrevemos como transmitir um token OAuth para uma chamada da API Map Tiles no seu ambiente de desenvolvimento. Para mais informações sobre como usar o OAuth em um ambiente de produção, consulte Métodos de autenticação no Google.

É possível chamar as APIs Google Maps diretamente fazendo solicitações de API ao servidor ou usar bibliotecas de cliente para simplificar seu código. O Google Maps oferece bibliotecas de cliente para Go, Java, Node.js e Python. Para mais informações, consulte as bibliotecas de cliente da API Map Tiles.

Visão geral do OAuth

É possível criar e gerenciar tokens de acesso com o OAuth de várias maneiras, dependendo do seu ambiente de implantação.

É possível usar o OAuth 2.0 para interações de servidor para servidor entre seu aplicativo e um serviço do Google. Nesse cenário, você usa uma conta de serviço associada ao aplicativo, em vez de um usuário individual. É possível fazer solicitações de API usando a conta de serviço sem envolver os usuários diretamente. Para mais informações sobre métodos de autenticação, consulte Métodos de autenticação no Google.

Como alternativa, é possível integrar a API Map Tiles a um app para dispositivos móveis Android ou iOS. Para mais informações sobre como usar o OAuth e gerenciar tokens de acesso para diferentes ambientes de implantação, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

Escopos do OAuth

Para usar o OAuth com a API Map Tiles, atribua ao token OAuth o seguinte escopo:

https://www.googleapis.com/auth/cloud-platform

Exemplo: testar chamadas de API REST no ambiente de desenvolvimento local

Se você não tiver um ambiente que gere tokens e quiser testar a API Map Tiles com um token OAuth, use o procedimento nesta seção.

Este exemplo descreve como usar o token OAuth fornecido pelo Application Default Credentials (ADC) para fazer a chamada. Para mais informações sobre como usar o ADC para chamar APIs do Google com bibliotecas de cliente, consulte Autenticar usando bibliotecas de cliente.

Use o procedimento REST a seguir apenas para desenvolvimento ou teste, não para produção.

Pré-requisitos

Antes de fazer uma solicitação REST usando o ADC, use a CLI gcloud para fornecer credenciais ao ADC:

  1. Instale e inicialize a CLI gcloud. Para mais informações, consulte Instalar a CLI gcloud.

  2. Faça a autenticação com a gcloud CLI:

    gcloud auth application-default login

  3. Conclua o processo de login para salvar suas credenciais no arquivo de credenciais local usado pelo ADC.

Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local.

Fazer uma solicitação REST

Neste exemplo, você transmite dois cabeçalhos da solicitação:

  • Transmita o token OAuth no cabeçalho Authorization usando o seguinte comando para gerar o token:

    gcloud auth application-default print-access-token

    O token retornado tem um escopo de https://www.googleapis.com/auth/cloud-platform.

  • Transmita o ID ou o nome do projeto na nuvem do Google Cloud com o faturamento ativado no cabeçalho X-Goog-User-Project.

Para chamar a API Map Tiles usando um token OAuth, siga estas etapas:

  1. No exemplo de código a seguir, substitua PROJECT_ID pelo ID do projeto do Google Cloud.

    O exemplo a seguir acessa um bloco de mapa 2D. Para blocos fotorrealistas em 3D, use um renderizador de blocos em 3D. Para mais informações, consulte Trabalhar com um renderizador de blocos 3D.

    curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "X-Goog-User-Project: PROJECT_ID" -d '{
"mapType": "roadmap",
"language": "en-US",
"region": "US"
}' \
"https://tile.googleapis.com/v1/createSession"

  2. Para copiar o comando curl, clique em Copiar no exemplo de código.

  3. Cole o comando em uma janela do terminal e execute-o.

A resposta é um objeto JSON:

{
  "session": "AJVsH2yfm-qbTsquzjqT_mZpa6zjxUDJHQayGufwg",
  "expiry": "1738183946",
  "tileWidth": 256,
  "imageFormat": "png",
  "tileHeight": 256
}

Solução de problemas

Se a solicitação retornar uma mensagem de erro informando que essa API não é compatível com credenciais de usuário final, consulte Resolver problemas de configuração do ADC.

A seguir

Acessar blocos 2D

Depois de configurar a autenticação, crie um token de sessão. Em seguida, use sua chave de API ou o token do OAuth e o token de sessão nas solicitações de blocos de mapa 2D e blocos do Street View.

Usar tokens de sessão

Receber blocos 3D

Depois de configurar a autenticação, você pode acessar os blocos 3D.

Visão geral dos 3D Tiles