Escolha quais informações retornar
Ao chamar um método para calcular uma rota ou matriz de rotas, especifique quais informações você quer listando os campos a serem 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
.
Usar uma máscara de campo é uma boa prática de design para garantir que você não solicite dados desnecessários, o que, por sua vez, ajuda a evitar cobranças desnecessárias e tempo de processamento.
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 e especifique um caminho de campo da seguinte maneira:
- Encontre os campos que contêm as informações necessárias na API Routes. Para mais detalhes, consulte a seção Referências de campo.
- Determine os caminhos para os campos necessários e construa as máscaras de campo para eles: para detalhes, consulte Determinar qual máscara de campo você quer usar.
Combine as máscaras de campo para todos os campos necessários, separando-as por vírgulas. Por exemplo, para solicitar
distanceMeters
para o trecho do trajeto, mais a duração de cada etapa do trecho do trajeto, insira os dois, separados por vírgula e sem espaços:routes.legs.distanceMeters,routes.legs.steps.duration
Envie a máscara de campo com sua solicitação de API. Por exemplo, em uma solicitação cURL, especifique a máscara de campo com
-H
eX-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Referências de campos
Para conferir os campos que você pode solicitar em uma resposta usando máscaras de campo, consulte as referências da API Routes na lista a seguir. Especifique os campos com letras concatenadas, conforme mostrado na referência. Por exemplo, routePreference
.
Essas referências incluem os campos disponíveis. No entanto, é preciso consultar a hierarquia dos campos para determinar o caminho completo da máscara de campo. Para detalhes sobre a hierarquia dos campos, consulte Determinar qual máscara de campo você quer usar.
- Máscara de campo da rota do Compute
- Calcular máscaras de campo da matriz de rota
- REST: especifica os campos do Corpo da resposta a serem retornados.
- gRPC: especifica os campos do objeto RouteMatrixElement na resposta a ser retornada.
Determinar as máscaras de campo a serem usadas
Veja como determinar quais campos você quer usar e criar as máscaras de campo para eles:
- Solicite todos os campos usando uma máscara de campo de
*
. - Observe a hierarquia dos campos na resposta para os campos que você quer.
Crie suas máscaras de campo usando a hierarquia dos campos mostrados na etapa anterior, com este formato:
topLevelField[.secondLevelField][.thirdLevelField][...]
Por exemplo, para esta resposta parcial de uma rota:
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
Se você quiser retornar apenas o campo distanceMeters
para o trecho do trajeto, ou seja, o último distanceMeters
no exemplo anterior, sua máscara de campo será a seguinte:
routes.legs.distanceMeters
Se, em vez disso, você quiser retornar o campo distanceMeters
para cada etapa do trecho do trajeto, ou seja, distanceMeters
em steps
no exemplo anterior, sua máscara de campo será assim:
routes.legs.steps.distanceMeters
Se você quiser retornar ambos, com o resultado acima, sua máscara de campo será a seguinte:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
Exemplos de caminhos de máscara de campo
Esta seção contém mais exemplos sobre como especificar um caminho de campo como parte de uma máscara de campo de resposta em chamadas REST e gRPC.
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 distanceMeters
e duration
da rota na resposta. Lembre-se de prefixar o nome do campo com routes
.
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:
X-Goog-FieldMask: originIndex,destinationIndex,duration
Chamada gRPC
Para gRPC, defina uma variável contendo a máscara do campo de resposta. Você pode 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 para retornar somente 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 você selecionar todos os campos ou todos eles no nível superior, poderá haver uma queda no desempenho quando novos campos forem adicionados e 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.
Para mais detalhes sobre como criar uma máscara de campo, consulte field_mask.proto.
Solicitar um token de rota
Para solicitar que a API Routes retorne tokens de rota gerados, siga estas etapas:
- Defina os seguintes parâmetros necessários para retornar um token de rota:
- Defina
travelMode
comoDRIVE
. - Defina
routingPreference
paraTRAFFIC_AWARE
ouTRAFFIC_AWARE_OPTIMAL
.
- Defina
- Verifique se nenhum dos waypoints do seu trajeto é
via
. - Especifique a máscara de campo
routes.routeToken
para retornar um token de rota:X-Goog-FieldMask: routes.routeToken
Você pode usar o token do seu 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.routeToken,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.