Escolher quais informações retornar
Ao chamar um método para calcular uma rota ou uma matriz de rota, é preciso definir quais informações serão retornadas 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 usando o cabeçalho HTTP ou gRPC X-Goog-FieldMask
.
O mascaramento de campo é uma boa prática 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 do 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 para o campo especificado.
Crie um caminho de campo da seguinte maneira:
topLevelField[.secondLevelField][.thirdLevelField][...]
- Máscara do campo de rota do Compute
- Máscaras de campo da matriz de rota do Compute
- REST: especifica os campos do Corpo da resposta a ser retornado.
- gRPC: especifica os campos do objeto RouteMatrixElement na resposta a ser retornada.
Para mais informações sobre como criar máscaras de campo, consulte field_mask.proto.
Determinar quais máscaras de campo usar
Veja como determinar quais máscaras de campo você quer usar:
- Solicite todos os campos usando uma máscara de campo de
*
. - Veja a hierarquia dos campos na resposta e determine quais deles você quer.
- Crie a 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 em legs
na resposta, a 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
para 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 rota, especifique no cabeçalho
o retorno de 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 de campo de resposta. Você pode então passar essa variável para a solicitação.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
Considerações sobre o caminho do campo
Inclua somente os campos necessários na resposta. Retornar apenas os campos necessários:
- Diminui o tempo de processamento, para que seus resultados sejam retornados com uma latência menor.
- Garante o desempenho de latência estável caso a API adicione mais campos de resposta no futuro e esses novos campos exigirem mais tempo de computação. Se você selecionar todos os campos ou todos no nível superior, poderá notar uma degradação no desempenho quando todos os novos campos forem incluídos automaticamente na resposta.
- Resulta em um tamanho de resposta menor, que se traduz em maior capacidade de rede.
- Garante que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento desnecessário 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:
- Defina
travel_mode
comoDRIVING
. - Defina
routing_preference
paraTRAFFIC_AWARE
ouTRAFFIC_AWARE_OPTIMAL
. - Verifique se nenhum dos seus waypoints do trajeto são waypoints do
via
. - 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 um trajeto (Android) ou Planejar um trajeto (iOS).
Exemplo de token de rota
Confira um exemplo de corpo de solicitação cURL para uma rota de origem única e destino usando máscaras de campo para solicitar um token, além de duração, distância e polilinha:
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.