Usar chaves de API

Para proteger os produtos da Plataforma Google Maps contra uso não autorizado, as chamadas de API ficam restritas àquelas com as credenciais de autenticação adequadas. Essas credenciais vêm na forma de uma chave de API, uma string alfanumérica exclusiva que associa a conta de faturamento do Google ao seu projeto e à API ou ao SDK específico.

Este guia mostra como criar, restringir e usar uma chave de API para a Plataforma Google Maps.

Antes de começar

Para usar a API Maps JavaScript, você precisa ter um projeto com uma conta de faturamento e ativar a API Maps JavaScript. Para saber mais, consulte Configurar no Console do Cloud.

Criar chaves de API

A chave de API é um identificador exclusivo que autentica solicitações associadas ao seu projeto para fins de uso e faturamento. Você precisa ter pelo menos uma chave de API associada ao projeto.

Para criar uma chave de API, siga estas etapas:

Console

  1. Acesse a página Plataforma Google Maps > Credenciais.

    Acessar a página "Credenciais"

  2. Na página Credenciais, clique em Criar credenciais > Chave de API.
    A caixa de diálogo Chave de API criada exibirá sua chave recém-criada.
  3. Clique em Fechar.
    A nova chave vai aparecer na página Credenciais, em Chaves de API.
    Lembre-se de restringir a chave de API antes de usar na produção.

SDK Cloud

gcloud alpha services api-keys create \
    --project "PROJECT" \
    --display-name "DISPLAY_NAME"

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

Restringir chaves de API

O Google recomenda que você restrinja as chaves de API limitando o uso somente às APIs necessárias para o aplicativo. Isso deixa o app mais seguro, protegendo contra solicitações não autorizadas. Para mais informações, consulte Práticas recomendadas de segurança de APIs.

Para restringir uma chave de API, faça o seguinte:

Console

  1. Acesse a página Plataforma Google Maps > Credenciais.

    Acessar a página "Credenciais"

  2. Selecione a chave de API em que você quer definir uma restrição. A página de propriedades será exibida.
  3. Em Restrições de chave, defina as seguintes opções:
    • Restrições do aplicativo:
      1. Para aceitar as solicitações da lista de sites que você informou, selecione Referenciadores HTTP (sites) na lista de Restrições do aplicativo.
      2. Especifique um ou mais sites de referenciadores. Você pode usar caracteres curingas para autorizar todos os subdomínios (por exemplo, https://*.google.com aceita todos os sites que terminam em .google.com quando acessado pelo HTTPS). Se você especificar www.domain.com, ele será interpretado como um caractere curinga www.domain.com/* e vai autorizar todos os subcaminhos nesse nome de host. Especifique os esquemas de referenciador https:// e http:// no estado em que se encontra. Para outros protocolos de URL, é necessário usar uma representação especial. Por exemplo, formate file:///path/to/ como __file_url__//path/to/*. Depois de ativar sites, monitore o uso para garantir que eles atendam às suas expectativas. Os seguintes protocolos têm suporte: about://, app://, applewebdata://, asset://, chrome://, content://, file://, ftp://, ionic://, local://, ms-appx://, ms-appx-web://, ms-local-stream://, prism://, qrc://, res://, saphtmlp://.
    • Restrições de API:
      1. Clique em Restringir chave.
      2. Escolha API Maps JavaScript no menu suspenso Selecionar APIs. Você vai precisar habilitar a API Maps JavaScript se ela não aparecer nessa lista.
      3. Caso seu projeto use a biblioteca Places, selecione também a API Places. Além disso, se ele usa outros serviços na API JavaScript (Directions Service, Distance Matrix Service, Elevation Service e/ou Geocoding Service), também será preciso ativar e selecionar a API correspondente nessa lista.
  4. Para concluir as mudanças, clique em Salvar.

SDK Cloud

Liste as chaves atuais.

gcloud services api-keys list --project="PROJECT"

Limpe as restrições atuais na chave.

gcloud alpha services api-keys update "projects/PROJECT/keys/KEY_ID" \
    --clear-restrictions

Defina novas restrições para as chaves atuais.

gcloud alpha services api-keys update "projects/PROJECT/keys/KEY_ID" \
    --api-target="maps-backend.googleapis.com"
    --allowed-referrers="referer"

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

Adicionar a chave de API à solicitação

Você precisa incluir uma chave de API em todas as solicitações da API Maps JavaScript. No exemplo a seguir, substitua YOUR_API_KEY pela chave da API.

<script>
  (g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
    key: "YOUR_API_KEY",
    v: "weekly",
    // Use the 'v' parameter to indicate the version to use (weekly, beta, alpha, etc.).
    // Add other bootstrap parameters as needed, using camel case.
  });
</script>