Lista de verificação de pré-lançamento do Google Maps APIs for Work

Esta página é destinada apenas a clientes que têm uma licença antiga do Maps APIs for Work ou do Maps API for Business. Esta página não se aplica a clientes com o novo Google Maps APIs Premium Plan, disponibilizado em janeiro de 2016.

  1. Garantir que sua equipe tenha acesso aos recursos necessários
    1. Receber a carta de boas-vindas do Google Maps APIs for Work
    2. Ter acesso ao Google Cloud Support Portal e usá-lo
    3. Assinar os feeds de notificação relevantes
    4. Ter a linha direta de suporte à mão
  2. Otimização de aplicativos
    1. Configurar o firewall para permitir o acesso aos serviços das Google Maps APIs
    2. Carregar as APIs usando SSL
    3. Usar Maps APIs do lado do cliente em domínios SSL
    4. Selecionar a versão adequada da API
    5. Otimizar o uso da visualização de página
    6. Projeto do lado do cliente vs. projeto do lado do servidor: escolha o que for adequado ao caso de uso
    7. Cota e gerenciamento de Web Services
    8. Testes de carregamento
  3. Migrar de implementações gratuitas para implementações do Google Maps APIs for Work
    1. Autorização de domínios
    2. Integrar o ID do cliente
    3. Utilizar a chave criptográfica para assinar solicitações de Web Services
    4. Rastrear o uso de aplicativos e o parâmetro de canal
    5. Remover parâmetros obsoletos das solicitações de API

Garantir que sua equipe tenha acesso aos recursos necessários

Receber a carta de boas-vindas do Google Maps APIs for Work

Por que é importante: a carta de boas-vindas é o kit do iniciante do Google Maps APIs for Work e, talvez, também o kit de primeiros socorros. Ela contém informações essenciais, como o ID do cliente e a chave criptográfica, necessárias para começar a usar as Google Maps APIs. Além disso, ela contém todas as informações necessárias para entrar em contato com a equipe do Google Cloud Support, caso ocorram problemas técnicos com o uso das Google Maps APIs.

Ter acesso ao Google Cloud Support Portal e usá-lo

Por que é importante: o portal de suporte oferece acesso a informações como relatórios de uso, feeds de notícias e recursos úteis para desenvolvedores. E, o que é mais importante, o portal de suporte permite registrar casos de suporte com a equipe de suporte das Google Maps APIs, caso ocorram problemas técnicos durante o desenvolvimento ou o lançamento. O portal de suporte pode ser acessado neste URL:

https://google.secure.force.com/

Antes do lançamento, não deixe de ativar o acesso ao portal de suporte para todos os desenvolvedores responsáveis pela manutenção do aplicativo. Se ocorrer algum problema técnico, o acesso ao portal de suporte oferecerá o duplo benefício de permitir que membros da sua equipe entrem em contato com o suporte e permitir que nossa equipe de suporte entre em contato com as partes interessadas na sua organização. Por exemplo, poderá ser necessário que a equipe de suporte entre em contato com a organização se detectar tráfego ou comportamento anormal que possa causar falha no seu aplicativo. A certeza de termos os contatos adequados com os desenvolvedores pode ser a diferença entre uma interrupção inesperada e evitar essa interrupção. Se você não tiver acesso ao portal de suporte, solicite-o aqui:

Solicite uma conta do Google Cloud Support Portal

Assinar os feeds de notificação relevantes

Por que é importante: para garantir a atualização em relação à evolução e as mudanças das Google Maps APIs, recomendamos que você assine os feeds de notificação relevantes. Você deve assinar o Blog Google Geo Developers e os Grupos do Google de notificação relevantes para as APIs usadas, conforme descrito em:

https://developers.google.com/maps/faq#notify

Dedique alguns momentos agora para assinar os grupos de notificação para as APIs que você usa ou pretende usar. Você também pode assinar este feed RSS:

http://google.force.com/services/xml/MapsRSS

para receber atualizações das equipes de suporte das Google Maps APIs.

Ter a linha direta de suporte à mão

1-877-355-5787 para clientes dos EUA, +1 404-978-9282 para clientes fora dos EUA

Por que é importante: a linha direta é o meio de ligar para o Google Cloud Support Portal. Adicione esta página aos favoritos para encontrar os números de linha direta do suporte mais recentes e atualizados. Você pode usar a linha direta de suporte para relatar problemas técnicos para a nossa equipe, mas observe que ela é destinada apenas a casos de interrupção de produção ou serviços inutilizáveis. Os nossos níveis de prioridade são definidos em:

https://support.google.com/work/answer/184028

Otimização de aplicativos

Configurar o firewall para permitir o acesso aos serviços das Google Maps APIs

Por que é importante: os serviços das Google Maps APIs usam diversos domínios, alguns dos quais não pertencem ao domínio *google.com. Se você usa um firewall restritivo, é importante permitir acesso aos domínios usados pelos serviços da Maps API. Se o firewall não permitir acesso a esses domínios, as solicitações de API falharão, o que poderá causar erro nos aplicativos. Você pode encontrar uma lista completa de domínios usados pelas Maps APIs no portal de suporte:

  1. Faça login no Google Cloud Support Portal.
    O portal de suporte está disponível apenas para clientes com o Google Maps APIs Premium Plan ou uma licença anterior do Google Maps APIs for Work ou Google Maps for Business.
  2. Navegue até a guia Resources.
  3. Selecione List of domains used by the Google Maps APIs family.
  4. Permita que os aplicativos acessem os domínios listados.

Não recomendamos o gerenciamento de restrições de firewall por endereço IP, pois os IPs associados a esses domínios não são estáticos.

Observação: os serviços das Google Maps APIs usam a porta 80 (http) e 443 (https) para tráfego de entrada e saída. Esses serviços também exigem solicitações GET, POST, PUT, DELETE e HEAD. Configure o firewall para permitir tráfego por essas portas e permitir solicitações de acordo com a API e o caso de uso.

Carregar as APIs usando SSL

Por que é importante: os aplicativos que carregam as Maps JavaScript API, as Web Service APIs ou as APIs de imagem usando SSL devem fazê-lo do endereço https://maps.googleapis.com em vez do nome do host legado https://maps-api-ssl.google.com.

Usar Maps APIs do lado do cliente em domínios SSL

Por que é importante: ao usar uma API do lado do cliente com um domínio SSL, é essencial que você tenha autorizado explicitamente os domínios HTTPS para garantir que as solicitações não sejam rejeitadas. Observe que a autorização de http://yourdomain.com não ativa automaticamente o equivalente SSL, https://yourdomain.com. Você pode verificar a lista de domínios autorizados no Google Cloud Support Portal selecionando o link Maps: Manage Client ID no menu de navegação à esquerda. Para resolver erros relacionados ao uso de APIs do lado do cliente com um domínio SSL, recomendamos que você verifique antes se todos os elementos da página são carregados usando HTTP. Consulte também nosso artigo Resolver problemas de autorização para implementações do Google Maps APIs for Work.

Selecionar a versão adequada da API

Por que é importante: antes de desenvolver aplicativos, é importante estar ciente das versões obsoletas das APIs. A opção por desenvolver usando versões não obsoletas de APIs reduzirá o tempo de desenvolvimento e o custo quando essas versões obsoletas se tornarem indisponíveis.

Também é essencial compreender o esquema de controle de versão das APIs para evitar o uso acidental de uma versão incorreta da API no seu ambiente:

https://developers.google.com/maps/documentation/javascript/versions

Por exemplo, o uso de uma versão noturna (ou seja, experimental) da API no ambiente de desenvolvimento/teste pode ser aceitável, mas é altamente desaconselhável usar essas versões em um ambiente de produção. Nosso ANS se aplica apenas a versões estáveis da API. Portanto, use apenas versões estáveis no ambiente de produção.

Otimizar o uso da visualização de página

Por que é importante: se você não exibe sempre um Google Map no site, por que pagar por isso? Como prática recomendada para aumentar a eficiência das visualizações de página, sugerimos carregar as Maps APIs de forma assíncrona nas páginas em que você realmente exibe um mapa. Isso reduzirá drasticamente o número de visualizações de página compradas consumidas pelos aplicativos. Lembre-se de que todas as vezes que uma página que carrega a API for atualizada, será cobrada uma nova visualização de página. Por isso, recomendamos que, no projeto do aplicativo, o site que carrega a API inicie atualizações de página apenas quando absolutamente necessário.

Projeto do lado do cliente vs. projeto do lado do servidor: escolha o que for adequado ao caso de uso

Por que é importante: a escolha entre as abordagens do lado do cliente ou do servidor é uma decisão de arquitetura absolutamente essencial para a estabilidade e a escalabilidade dos aplicativos. De modo geral, a abordagem do lado do servidor deve ser usada para processamento off-line prévio e posterior de registros (ou seja, fora do aplicativo). Como alternativa, a abordagem do lado do cliente deve ser usada para partes dos aplicativos que interagem com os usuários (ou seja, processam solicitações enviadas pelos usuários em tempo real).

A implantação da abordagem do lado do servidor em pontos em que a abordagem do lado do cliente deveria ser usada é o principal motivo do esgotamento de cotas e, portanto, de erros nos aplicativos. É altamente recomendado consultar o documento Estratégias de geocodificação antes de projetar ou executar aplicativos que dependem de chamadas do lado do servidor.

Cota e gerenciamento de Web Services

Por que é importante: por padrão, a cota de serviços Web é definida como 100.000 consultas a cada 24 horas. Para obter uma descrição mais detalhada de cotas por API, consulte a documentação de limites de uso. Para confirmar o tamanho da cota disponível para o ID do cliente, registre um caso de suporte. Antes de lançar o serviço, é essencial que você entenda os diferentes erros relacionados a cotas (por exemplo, OVER_QUERY_LIMIT, User Rate Limit Exceeded) e defina a lógica adequada no aplicativo para poder responder a esses erros quando a cota for excedida. Comece lendo o artigo Limites de uso dos Web Services das Google Maps APIs. A compreensão e a implementação desses conceitos reduzirão consideravelmente a probabilidade de o aplicativo exceder a cota permitida, ser bloqueada pelo Google e/ou apresentar erros.

Testes de carregamento

Por que é importante: testes de carregamento em tempo real usando os serviços do Google farão com que o aplicativo exceda a cota permitida e seja bloqueado pelo Google.

As Google Maps APIs podem atender a volumes muito altos. Em 2012, o Siga o Papai Noel atendeu a 1.600.000 solicitações por segundo. Portanto, é desnecessário executar testes de carregamento com os serviços do Google. Em vez disso, faça testes de carregamento com o aplicativo para garantir que ele consiga lidar com altos volumes de solicitações sem exceder as cotas das Maps APIs. Por exemplo, se sua cota da Google Maps Geocoding API for 20 QPS (consultas por segundo), os testes de carregamento do aplicativo deverão garantir que ele possa processar 600 QPS sem enviar mais de 20 QPS para a Google Maps Geocoding API.

Para conseguir fazer isso com segurança, os testes de carregamento devem ser executados usando uma API simulada (falsa), um serviço que possa absorver altas quantidades de solicitações e respondê-las de forma válida, sem envolver as Google Maps APIs. Dessa forma, é possível fazer testes de carregamento com o aplicativo sem correr o risco de bloqueio pelas Google Maps APIs.

Veja este exemplo de uma API simulada, implementada como um pequeno aplicativo do Google App Engine: https://github.com/googlemaps/js-v2-samples/blob/gh-pages/mock_maps_apis/. Você pode fazer upload dessa API simulada para o seu próprio aplicativo do App Engine (depois de registrar um em https://appengine.google.com/) e fazer com que o aplicativo envie as solicitações para lá, em vez de para maps.googleapis.com.

As cotas padrão (gratuitas) do App Engine normalmente são suficientes para testes de carregamento do aplicativo muito além das cotas dos serviços Web das Maps APIs. Verifique se o aplicativo define o cabeçalho User-Agent correto para ativar a compressão de respostas. Isso é essencial para garantir o uso eficiente da largura de banda, o que é particularmente importante para um aplicativo do App Engine atendendo a um alto volume de respostas em texto simples (JSON/XML). Se precisar de uma cota maior para o aplicativo do App Engine, você também poderá ativar a cobrança, embora isso raramente seja necessário.

Migrar APIs de uma licença gratuita para uma licença do Google Maps APIs for Work

Autorização de domínios

Por que é importante: para evitar que sites não autorizados usem seu ID do cliente, nossa Google Maps JavaScript API exige que você entre em contato com a nossa equipe de suporte para autorizar todos os domínios de todos os sites que usam seu ID do cliente. Se um site que tentar usar seu ID do cliente não corresponder aos URLs autorizados para uso desse ID, não conseguirá usar as APIs com esse ID. Você pode autorizar domínios a qualquer momento. Portanto, verifique se todos os seus domínios de todos os seus sites foram autorizados antes do lançamento.

A Google Street View Image API e a Google Static Maps API podem ser usadas no lado do cliente e do servidor e ambas geram visualizações de página. Como resultado, essas APIs exigem que você assine as solicitações usando sua chave criptográfica e também que você autorize todos os domínios que usam essas APIs. Isso garante que os aplicativos sejam cobrados corretamente, de acordo com nossos termos de serviço, com suporte e cobertura de nosso ANS.

Você pode verificar a lista de domínios autorizados no Google Cloud Support Portal selecionando o link Maps: Manage Client ID no menu de navegação à esquerda.

Em caso de problemas de autorização, recomendamos o artigo Resolver problemas de autorização para implementações do Google Maps APIs for Work antes de registrar um caso.

Integrar o ID do cliente (por exemplo, &client=gme-yourclientid)

Por que é importante: uma das coisas mais importantes que você pode fazer em seu aplicativo é não deixar de incluir '&client=gme-yourclientid' nas solicitações. O seu ID do cliente único pode ser encontrado na carta de boas-vindas, enviada aos contatos primários da sua organização. O ID do cliente identifica solicitações como solicitações do Google Maps APIs for Work. Você deve incluir o ID do cliente nos aplicativos para se beneficiar de todos os recursos específicos do Google Maps APIs for Work. A inclusão do ID do cliente também é necessária para receber suporte técnico e assegurar que o aplicativo seja coberto pelo nosso ANS.

Utilizar a chave criptográfica (por exemplo, vNIXE0xscrmjlyV-12Nj_BvUPaw=) para assinar solicitações de Web Services

Por que é importante: sua chave criptográfica privada é usada para gerar assinaturas que informam ao Google que suas solicitações vêm de uma origem confiável. A sua chave criptográfica pode ser encontrada na carta de boas-vindas, enviada aos contatos primários da sua organização. Como cliente do Google Maps APIs for Work, nossos Web Services exigem que você assine as solicitações usando sua chave criptográfica. Isso adiciona uma camada de segurança à solicitação, protegendo melhor a cota associada ao seu ID do cliente.

Observe que a chave criptográfica é usada para gerar assinaturas. Ela não é anexada às solicitações como a própria assinatura. A chave criptográfica é semelhante a uma senha de ATM. Ela é usada como forma de autenticação para acessar sua conta e nunca deve ser compartilhada abertamente com origens não confiáveis nem ficar visível para elas. As solicitações de serviços Web do Google Maps APIs for Work que não estiverem devidamente assinadas serão rejeitadas por nossos servidores. Portanto, é essencial que o aplicativo assine corretamente as solicitações antes do lançamento (no momento, a Google Maps Geocoding API v2 não exige assinaturas). Consulte nossa documentação sobre assinatura de URLs:

https://developers.google.com/maps/premium/previous-licenses/webservices/auth

Rastrear o uso de aplicativos e o parâmetro de canal

Por que é importante: o parâmetro channel é opcional e permite rastrear o uso do ID do cliente atribuindo um canal distinto para cada aplicativo. Os parâmetros de canal não precisam ser registrados no ID do cliente. Basta adicionar o parâmetro de canal à solicitação de API, e eles serão exibidos nos relatórios de suporte de uso do portal em 1 a 2 dias após a implementação. Você decide onde implementar os canais e, portanto, como o uso é agregado. Antes do lançamento, decida se o aplicativo deve integrar parâmetros de canal para rastrear o uso do aplicativo:

https://developers.google.com/maps/premium/previous-licenses/clientside/quota#reporting

O parâmetro channel deve usar o seguinte formato:

  • Deve ser uma string ASCII alfanumérica.
  • Os caracteres ponto (.), sublinhado (_) e hífen (-) são permitidos.
  • O parâmetro channel não diferencia maiúsculas de minúsculas. Parâmetros channel com caracteres maiúsculos, minúsculos e mistos são mesclados em um único parâmetro equivalente em letras minúsculas. Por exemplo, o uso do canal CUSTOMER é combinado com o uso do canal customer.

É possível implementar até 2.000 canais distintos por ID do cliente.

Para usar o parâmetro channel, inclua-o no URL da solicitação, juntamente com o parâmetro client usado para passar o ID do cliente.

Observe que o parâmetro de canal deve ser um valor atribuído estaticamente para cada aplicativo. Ele não deve ser gerado dinamicamente e usado para rastrear usuários individuais.

Remover parâmetros obsoletos das solicitações de API (por exemplo, o parâmetro '&key=ABQIAAAA…')

Por que é importante: para carregar corretamente a Google Maps JavaScript API, é necessário incluir o seu ID do cliente. Além disso, todos os parâmetros key devem ser removidos. Se sua solicitação incluir um ID do cliente e uma chave, falhará.

Siga o guia do Google Maps APIs for Work para obter informações completas sobre a formatação correta de solicitações do Google Maps APIs for Work por API: https://developers.google.com/maps/premium/previous-licenses/