Escolha quais informações retornar

Ao chamar um método para calcular uma rota ou calcular uma matriz de rotas, é preciso especificar quais informações você quer determinar os campos que serão retornados na resposta. Não há uma lista padrão de campos retornados. Se você omitir essa lista, os métodos retornarão um erro.

Para especificar a lista de campos, crie uma máscara de campo de resposta. Em seguida, transmita a máscara de campo de resposta para qualquer um dos métodos usando o parâmetro de URL $fields ou fields ou o cabeçalho HTTP ou gRPC X-Goog-FieldMask.

O mascaramento de campo é uma prática recomendada de design para garantir que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário e cobranças faturadas.

Para mais informações sobre parâmetros de URL, consulte Parâmetros do sistema.

Definir uma máscara de campo de resposta

A máscara de campo de resposta é uma lista de caminhos separados por vírgulas, em que cada caminho especifica um campo exclusivo na mensagem de resposta. O caminho começa na mensagem de resposta de nível superior e usa um caminho separado por pontos até o campo especificado.

Crie um caminho de campo da seguinte maneira:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Máscara de campo da rota do Compute
    • REST: especifica os campos do objeto Route na resposta a ser retornada, com o prefixo routes., por exemplo, routes.distanceMeters.
    • gRPC: especifica os campos do objeto Route na resposta a ser retornada.
  • Calcular máscaras de campo da matriz de rota

Para mais informações sobre como construir máscaras de campo, consulte field_mask.proto.

Determinar as máscaras de campo a serem usadas

Confira como determinar quais máscaras de campo você quer usar:

  1. Solicite todos os campos usando uma máscara de campo de *.
  2. Observe a hierarquia dos campos na resposta e determine quais você quer.
  3. Criar sua máscara de campo usando a hierarquia de campos.

Por exemplo, para esta resposta parcial de um trajeto de transporte público:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

Se você quiser retornar apenas o campo distanceMeters, sua máscara de campo será:

routes.legs.distanceMeters

Outro exemplo: para retornar tudo de legs na resposta, sua máscara de campo será:

routes.legs

Especificar um caminho de campo

Esta seção contém exemplos de como especificar um caminho de campo como parte de uma máscara de campo de resposta.

Chamada REST para computeRoutes

No primeiro exemplo, você usa uma chamada REST para o método computeRoutes a fim de calcular uma rota. Neste exemplo, no cabeçalho, você especifica máscaras de campo para retornar os campos Route.distanceMeters e Route.duration na resposta. Lembre-se de prefixar o nome do campo com routes. 

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

Chamada REST para computeRouteMatrix

Para o método REST computeRouteMatrix usado para calcular uma matriz de rotas, no cabeçalho, especifique para retornar originIndex, destinationIndex e duration para cada combinação de origem e destino:

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

Chamada gRPC

Para gRPC, defina uma variável contendo a máscara do campo de resposta. É possível transmitir essa variável para a solicitação.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Considerações sobre o caminho do campo

Inclua apenas os campos necessários na resposta. Retornar apenas os campos necessários:

  • Diminui o tempo de processamento, para que os resultados sejam retornados com uma latência menor.
  • Garante um desempenho de latência estável se a API adicionar mais campos de resposta no futuro e esses novos campos exigirem tempo de computação extra. Se você selecionar todos os campos ou todos os campos no nível superior, poderá haver uma queda no desempenho quando todos os campos novos forem incluídos automaticamente na resposta.
  • Resultados em uma resposta menor, o que resulta em maior capacidade de rede.
  • Garante que você não solicite dados desnecessários, o que ajuda a evitar tempos de processamento desnecessários e cobranças faturadas.

Solicitar um token de rota

Para solicitar que a API Routes retorne tokens de rota gerados, siga os requisitos para retornar um token de rota e use a máscara de campo routes.route_token para solicitar o token:

  1. Defina travel_mode como DRIVING.
  2. Defina routing_preference para TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.
  3. Verifique se nenhum dos waypoints do seu trajeto é via.
  4. Especifique a máscara de campo do token de rota: 
    -H X-Goog-FieldMask: routes.route_token

Você pode usar o trajeto planejado no SDK do Navigation. Para mais detalhes, consulte Planejar uma rota (Android) ou Planejar uma rota (iOS).

Exemplo de token de rota

Veja um exemplo de corpo de solicitação de cURL para uma rota de destino único e origem única, usando máscaras de campo para solicitar um token de rota, junto com a duração, a distância e a polilinha da rota:

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Para mais detalhes, consulte a referência da API Compute Routes.