Práticas recomendadas para usar os serviços da Web da API Distance Matrix

Os serviços da Web da Plataforma Google Maps são um conjunto de interfaces HTTP para o Google serviços que fornecem dados geográficos para seus aplicativos de mapas.

Este guia descreve algumas práticas comuns úteis para configurar sua serviço da Web solicitações e processamento de respostas de serviço. Consulte o Guia para desenvolvedores para ver a documentação completa da API Distance Matrix.

O que é um serviço Web?

Os serviços da Web da Plataforma Google Maps são uma interface para solicitar dados da API Maps de serviços externos e usar os dados nos aplicativos do Google Maps. Esses serviços são projetada para ser usada em conjunto com um mapa, conforme a Restrições da licença nos Termos de Serviço da Plataforma Google Maps.

Os serviços Web das APIs do Google Maps usam solicitações HTTP(S) para URLs específicos, transmitindo parâmetros de URL e/ou Dados POST no formato JSON como argumentos para os serviços. Geralmente, esses serviços retornam dados na corpo da resposta como JSON ou XML para análise e/ou processamento pelo aplicativo.

Uma solicitação da Distance Matrix API típica geralmente é do seguinte formato:

https://maps.googleapis.com/maps/api/distancematrix/output?parameters

em que output indica o formato da resposta (geralmente json ou xml).

Observação: todos os aplicativos da API Distance Matrix exigem autenticação. Saiba mais sobre as credenciais de autenticação.

Acesso SSL/TLS

O HTTPS é obrigatório para todas as solicitações da Plataforma Google Maps que usam chaves de API ou contêm informações de dados. As solicitações feitas por HTTP que contêm dados sensíveis podem ser rejeitadas.

Criar um URL válido

Você pode achar que um URL "válido" é imediatamente identificável, mas não funciona assim. Um URL inserido em uma barra de endereço de um navegador, por exemplo, pode conter caracteres especiais (por exemplo, "上海+中國"). O navegador precisa converter internamente esses caracteres em uma codificação diferente antes de transmiti-los. Da mesma forma, qualquer código que gere ou aceite entrada UTF-8 pode tratar URLs com caracteres UTF-8 como "válidos", mas também precisa converter esses caracteres antes de enviá-los a um servidor da Web. Esse processo é chamado de codificação de URL ou codificação por cento.

Caracteres especiais

É necessário converter caracteres especiais porque todos os URLs precisam estar em conformidade com a sintaxe especificada pela especificação do localizador uniforme de recursos (URI, na sigla em inglês). Efetivamente, isso significa que os URLs devem conter apenas um subconjunto especial de caracteres ASCII: os familiares símbolos alfanuméricos e alguns caracteres reservados para uso como caracteres de controle em URLs. Esta tabela resume esses caracteres:

Resumo de caracteres válidos para URLs
Conjuntode caracteresUso em URLs
Alfanuméricos a b c d e f g h i j k l m n o p q r s t u v w x y z A B C D E F G H I J K L M N O P Q R S T U V W X Y Z 0 1 2 3 4 5 6 7 8 9 Strings de texto, uso do esquema (http), porta (8080) etc.
Não reservados - _ . ~ Strings de texto
Reservados ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Caracteres de controle e/ou strings de texto

Ao criar um URL válido, você deve se certificar de que ele contenha apenas os caracteres mostrados no tabela. Conformar um URL ao uso desse conjunto de caracteres geralmente causa dois problemas, um de omissão e um de substituição.

  • Caracteres que você quer processar existem fora desse conjunto. Por exemplo, os caracteres de idiomas estrangeiros como 上海+中國 precisam ser codificados como mostrado acima. Por convenção popular, os espaços (que não são permitidos nos URLs) também são geralmente representados pelo caractere do sinal de adição ('+').
  • Caracteres existem no conjunto acima como caracteres reservados, mas precisam ser usados literalmente. Por exemplo, ? é usado em URLs para indicar o início da string de consulta. Se você quiser usar a string "? and the Mysterions", codifique o caractere '?'.

Todos os caracteres que precisam ser codificados para serem adicionados a URLs são codificados por meio do uso de um '%' e um valor hexadecimal de dois caracteres correspondente ao seu caractere UTF-8. Por exemplo, 上海+中國 em UTF-8 seria codificado como %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B para uso em URLs. A string ? and the Mysterians seria codificada em um URL como %3F+and+the+Mysterians ou %3F%20and%20the%20Mysterians.

Caracteres comuns que precisam de codificação

Alguns caracteres comuns que precisam ser codificados:

Caractere inválido Valor codificado
Espaço %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

Converter um URL recebido de uma entrada do usuário pode ser complicado. Por exemplo, um usuário pode inserir um endereço como "5th&Main St". Geralmente, você precisa criar o URL das partes dele, tratando quaisquer entradas do usuário como caracteres literais.

Além disso, os URLs estão limitados a 16.384 caracteres para todos os serviços da Web da Plataforma Google Maps e APIs estáticas da Web. Para a maioria dos serviços, esse limite raramente é atingido. No entanto, alguns serviços têm diversos parâmetros que podem resultar em URLs longos.

Uso adequado das Google APIs

Clientes de API mal projetados podem colocar mais carga do que o necessário na Internet e nos servidores do Google. Esta seção contém algumas das melhores práticas para cliente das APIs. Seguindo estas práticas recomendadas podem ajudar você a evitar que seu aplicativo seja bloqueado por abuso acidental de as APIs.

Retirada exponencial

Em casos raros, algo pode dar errado ao atender à sua solicitação. é possível que você receba uma solicitação HTTP 4XX ou 5XX ou a conexão TCP pode falhar em algum ponto entre o cliente e a rede do servidor. Muitas vezes, vale a pena tentar a solicitação novamente a solicitação de acompanhamento poderá ser bem-sucedida quando o original falhar. No entanto, é importante não simplesmente repetidamente fazendo solicitações aos servidores do Google. Esse comportamento de loop pode sobrecarregar entre o cliente e o Google, o que causa problemas para muitas partes.

Uma melhor abordagem é tentar novamente com intervalos maiores entre as tentativas. Normalmente, o o atraso é aumentado por um fator multiplicativo a cada tentativa, uma abordagem conhecida como Espera exponencial.

Por exemplo, considere um aplicativo que quer fazer a solicitação a API Time Zone:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

O exemplo de Python a seguir mostra como fazer a solicitação com retirada exponencial:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

Você também deve tomar cuidado para que não haja um código de repetição mais alto na chamada do aplicativo que resulta em solicitações repetidas em rápida sucessão.

Solicitações sincronizadas

Um grande número de solicitações sincronizadas para as APIs do Google podem parecer de negação de serviço (DDoS) na infraestrutura do Google e deve ser tratado de forma adequada. Para evite isso, verifique se as solicitações da API não estão entre clientes.

Por exemplo, considere um aplicativo que exibe a hora do fuso horário atual. Este aplicativo provavelmente definirá um alarme no sistema operacional do cliente, despertando-o às início do minuto para que o horário exibido possa ser atualizado. O aplicativo precisa não fará chamadas de API como parte do processamento associado a esse alarme.

Fazer chamadas de API em resposta a um alarme fixo é ruim, porque faz com que essas chamadas sejam sincronizados com o início do minuto, mesmo entre dispositivos diferentes, em vez de serem distribuídos de maneira uniforme ao longo do tempo. Um aplicativo mal projetado que faça isso produzirá um pico de tráfego 60 vezes maior do que o nível normal no início de cada minuto.

Em vez disso, um bom possível design é ter um segundo alarme definido a um horário escolhido aleatoriamente. Quando esse segundo alarme dispara, o aplicativo chama as APIs de que precisa e armazena a resultados. Quando o aplicativo deseja atualizar sua tela no início do minuto, ele usa resultados já armazenados em vez de chamar a API novamente. Com essa abordagem, as chamadas de API são distribuídos uniformemente com o tempo. Além disso, as chamadas de API não atrasam a renderização quando a tela que estão sendo atualizados.

Além do início do minuto, há outros momentos de sincronização comuns com os quais é preciso ter cuidado não segmentar são no início de uma hora e o início de cada dia à meia-noite.

Como processar respostas

Esta seção discute como extrair esses valores das respostas dos serviços web de forma dinâmica.

Os serviços Web do Google Maps fornecem respostas que são fáceis de entender, mas não exatamente fáceis de usar. Ao realizar uma consulta, em vez de exibir um conjunto de dados, você provavelmente quer extrair algumas valores. Geralmente, convém analisar respostas da Web serviço e extrair apenas os valores que lhe interessam.

O esquema de análise usado depende se você está retornando em XML ou JSON. respostas JSON, já na forma de Objetos JavaScript, podem ser processados no próprio JavaScript no cliente. As respostas em XML precisam ser processadas com um processador XML e uma linguagem de consulta XML para abordar elementos dentro do formato XML. Usamos XPath na exemplos a seguir, já que ele normalmente é aceito no processamento de XML, bibliotecas.

Como processar XML com XPath

O XML é um formato de informação estruturado relativamente maduro que é usado para à troca de dados. Embora não seja tão leve quanto JSON, o XML fornece suporte a mais idiomas e ferramentas mais robustas. Código para o processamento de XML em Java, por exemplo, é integrado ao javax.xml pacotes.

Ao processar respostas XML, você deve usar uma classe linguagem de consulta para selecionar nós dentro do documento XML, em vez do que presumir que os elementos residem em posições absolutas dentro do Marcação XML. XPath é uma sintaxe de linguagem para descrever de forma exclusiva nós e elementos em um documento XML. Expressões XPath permitem identificar conteúdo específico no documento de resposta XML.

Expressões XPath

Ter alguma familiaridade com o XPath ajuda muito no desenvolvimento um esquema de análise robusto. Nesta seção, vamos nos concentrar em como os elementos dentro de um documento XML são tratadas com XPath, permitindo que você endereçar vários elementos e criar consultas complexas.

O formato XPath usa expressões para selecionar elementos em um XML. documento, usando uma sintaxe parecida com a usada para caminhos de diretório. Essas expressões identificam elementos em um documento XML que é uma árvore hierárquica semelhante à de um DOM. Geralmente, as expressões XPath são gananciosas, indicando que corresponderá a todos os nós que corresponderem aos critérios fornecidos.

Usaremos o XML abstrato a seguir para ilustrar nossa exemplos:

<WebServiceResponse>
 <status>OK</status>
 <result>
  <type>sample</type>
  <name>Sample XML</name>
  <location>
   <lat>37.4217550</lat>
   <lng>-122.0846330</lng>
  </location>
 </result>
 <result>
  <message>The secret message</message>
 </result>
</WebServiceResponse>

Seleção de nós em expressões

As seleções de XPath selecionam nós. O nó raiz abrange todo o documento. Você seleciona esse nó usando a expressão especial "/". Observe que a raiz não é o nó de nível superior do seu documento XML. na verdade, ele fica um nível acima desse elemento de nível superior e inclui reimplantá-lo.

Os nós de elementos representam os vários elementos dentro do XML árvore de documentos. Um elemento <WebServiceResponse>, por exemplo, representa o elemento de nível superior retornado na nossa exemplo de serviço acima. Você seleciona nós individuais por meio de caminhos absolutos ou relativos, indicados pela presença ou ausência de "/" no início caractere.

  • Caminho absoluto: "/WebServiceResponse/result" seleciona todos os nós <result> que são filhos da <WebServiceResponse> nó. Esses dois elementos descendem da raiz nó "/".)
  • Caminho relativo do contexto atual: a expressão "result" corresponderia a qualquer <result> elementos no contexto atual. Geralmente, você não deve se preocupar com o contexto, já que normalmente processamos usando uma única expressão.

Qualquer uma dessas expressões pode ser aumentada com a adição de um caminho curinga, indicado por uma barra dupla ("//"). Esse curinga indica que zero ou mais elementos podem corresponder à interveniente. A expressão XPath "//formatted_address" por exemplo, corresponderá a todos os nós com esse nome no documento atual. A expressão //viewport//lat corresponderia a todas Elementos <lat> que podem rastrear <viewport> como pai/mãe.

Por padrão, as expressões XPath correspondem a todos os elementos. É possível restringir que a expressão corresponda a um determinado elemento, fornecendo um predicado, que está entre colchetes ([]). O XPath da expressão "/GeocodeResponse/result[2] sempre retorna a segundo resultado, por exemplo.

Tipo de expressão
Nó raiz
Expressão XPath: "/"
Seleção: 
    <WebServiceResponse>
     <status>OK</status>
     <result>
      <type>sample</type>
      <name>Sample XML</name>
      <location>
       <lat>37.4217550</lat>
       <lng>-122.0846330</lng>
      </location>
     </result>
     <result>
      <message>The secret message</message>
     </result>
    </WebServiceResponse>
Caminho absoluto
Expressão XPath: "/WebServiceResponse/result"
Seleção: 
    <result>
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
    </result>
    <result>
     <message>The secret message</message>
    </result>
Caminho com curinga
Expressão XPath: "/WebServiceResponse//location"
Seleção: 
    <location>
     <lat>37.4217550</lat>
     <lng>-122.0846330</lng>
    </location>
Caminho com predicado
Expressão XPath: "/WebServiceResponse/result[2]/message"
Seleção: 
    <message>The secret message</message>
Todos os filhos diretos do primeiro result
Expressão XPath: "/WebServiceResponse/result[1]/*"
Seleção: 
     <type>sample</type>
     <name>Sample XML</name>
     <location>
      <lat>37.4217550</lat>
      <lng>-122.0846330</lng>
     </location>
O name de um result em que o texto type é "sample" (exemplo).
Expressão XPath: "/WebServiceResponse/result[type/text()='sample']/name"
Seleção: 
    Sample XML

Ao selecionar elementos, você seleciona nós, não apenas o texto dentro desses objetos. Geralmente, vai querer iterar em todos os nós correspondentes e extrair o texto. Você também pode corresponder diretamente a nós de texto. consulte Nós de texto abaixo.

Observe que XPath também é compatível com nós de atributo; No entanto, todos os serviços da Web do Google Maps exibem elementos sem atributos, portanto, a correspondência de atributos não é necessária.

Seleção de texto em expressões

O texto em um documento XML é especificado em expressões XPath por meio de um operador text node. O operador "text()" indica a extração de texto do nó indicado. Por exemplo: a expressão XPath "//formatted_address/text()" vão retornar todo o texto em <formatted_address> os elementos.

Tipo de expressão
Todos os nós de texto (incluindo espaços em branco)
Expressão XPath: "//text()"
Seleção: 
    sample
    Sample XML

    37.4217550
    -122.0846330
    The secret message
Seleção de texto
Expressão XPath: "/WebServiceRequest/result[2]/message/text()"
Seleção: 
    The secret message
Seleção com reconhecimento de contexto
Expressão XPath: "/WebServiceRequest/result[type/text() = 'sample']/name/text()"
Seleção: 
    Sample XML

Como alternativa, você pode avaliar uma expressão e retornar um conjunto de nós e, em seguida, iterar nesse "conjunto de nós" ao extrair o o texto de cada nó. Usamos essa abordagem no exemplo abaixo.

Para mais informações sobre o XPath, Especificação W3C de XPath.

Como avaliar XPath em Java

O Java possui um amplo suporte para análise de XML e uso de expressões XPath no pacote javax.xml.xpath.*. Por isso, o exemplo de código nesta seção usa Java para ilustrar como lidar com XML e analisar dados de respostas de serviço XML.

Para usar XPath no seu código Java, primeiro será necessário instanciar uma instância de XPathFactory e chamar newXPath() nessa fábrica para criar um objeto XPath . Esse objeto pode processar os dados XML e expressões XPath usando o método evaluate().

Ao avaliar expressões XPath, não deixe de iterar sobre qualquer "conjunto de nós" possível que podem ser retornados. Como esses resultados são retornados como nós DOM no código Java, você deve capturar esses valores em um objeto NodeList e iterar nesse objeto para extrair qualquer texto ou valor dele nós.

O código a seguir ilustra como criar um XPath. objeto, atribua a ele como XML e uma expressão XPath e avalie o para mostrar o conteúdo relevante.

import org.xml.sax.InputSource;
import org.w3c.dom.*;
import javax.xml.xpath.*;
import java.io.*;

public class SimpleParser {

  public static void main(String[] args) throws IOException {

	XPathFactory factory = XPathFactory.newInstance();

    XPath xpath = factory.newXPath();

    try {
      System.out.print("Web Service Parser 1.0\n");

      // In practice, you'd retrieve your XML via an HTTP request.
      // Here we simply access an existing file.
      File xmlFile = new File("XML_FILE");

      // The xpath evaluator requires the XML be in the format of an InputSource
	  InputSource inputXml = new InputSource(new FileInputStream(xmlFile));

      // Because the evaluator may return multiple entries, we specify that the expression
      // return a NODESET and place the result in a NodeList.
      NodeList nodes = (NodeList) xpath.evaluate("XPATH_EXPRESSION", inputXml, XPathConstants.NODESET);

      // We can then iterate over the NodeList and extract the content via getTextContent().
      // NOTE: this will only return text for element nodes at the returned context.
      for (int i = 0, n = nodes.getLength(); i < n; i++) {
        String nodeString = nodes.item(i).getTextContent();
        System.out.print(nodeString);
        System.out.print("\n");
      }
    } catch (XPathExpressionException ex) {
	  System.out.print("XPath Error");
    } catch (FileNotFoundException ex) {
      System.out.print("File Error");
    }
  }
}