Escolher campos para retornar
Ao solicitar um trajeto ou uma matriz de trajetos, use uma máscara de campo para especificar quais informações a resposta deve retornar. Não há uma lista padrão de campos retornados. Se você não especificar uma máscara de campo, os métodos vão retornar um erro.
O uso de uma máscara de campo também garante que você não solicite dados desnecessários, o que ajuda na latência de resposta e evita o retorno de informações que seu sistema não precisa.
Especifique a lista dos campos necessários em 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.
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 para o campo especificado.
Crie e especifique um caminho de campo da seguinte maneira:
- Encontre os campos que contêm as informações necessárias. Para mais detalhes, consulte a seção Referências de campo.
- Determine os caminhos para os campos necessários e crie as máscaras de campo para eles: para mais detalhes, consulte Determinar qual máscara de campo você quer usar.
Combine as máscaras de todos os campos necessários, separando-as com vírgulas. Por exemplo, para solicitar o
distanceMetersdo trecho do trajeto, além da duração de cada etapa do trecho, insira os dois, separados por uma vírgula, 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, você especificaria a máscara de campo com
-HeX-Goog-FieldMask:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Referências de campo
Para conferir os campos que podem ser solicitados em uma resposta usando máscaras de campo, consulte as referências da API Routes Compute Routes ou Compute Route Matrix vinculadas na lista a seguir. Especifique os campos em letras concatenadas, conforme mostrado na referência. Por exemplo, routePreference.
Essas referências incluem os campos disponíveis. No entanto, é necessário consultar a hierarquia dos campos para determinar o caminho completo da máscara de campo. Para detalhes sobre como acessar a hierarquia dos campos, consulte Determinar qual máscara de campo você quer usar.
- Máscara de campo de rota de computação
- Máscaras de campo da Compute Route Matrix
- REST: especifica os campos do corpo da resposta a serem retornados.
- gRPC: especifica os campos do objeto RouteMatrixElement na resposta a ser retornada.
Determinar quais máscaras de campo usar
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, neste formato:
topLevelField[.secondLevelField][.thirdLevelField][...]
Por exemplo, para esta resposta parcial de um trajeto:
"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á:
routes.legs.distanceMeters
Se você quiser retornar o campo distanceMeters para cada etapa do trecho do trajeto, ou seja, o distanceMeters em steps no exemplo anterior, sua máscara de campo será:
routes.legs.steps.distanceMeters
Se você quiser retornar os dois, 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 de 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 para calcular uma rota. Neste exemplo, no cabeçalho, você especifica máscaras de campo para retornar os campos de rota distanceMeters e duration na resposta. Não se esqueça de adicionar o prefixo routes ao nome do campo.
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 o retorno de originIndex, destinationIndex e duration para cada combinação de origem e destino:
X-Goog-FieldMask: originIndex,destinationIndex,duration
Chamada gRPC para computeRoutes
Para o método gRPC computeRoutes usado para calcular um trajeto, defina uma variável que contenha a máscara de campo de resposta para retornar os campos de trajeto distanceMeters, duration e polilinha codificada na resposta. Em seguida, transmita essa variável para a solicitação:
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
Chamada gRPC para computeRouteMatrix
Para o método gRPC computeRouteMatrix usado para calcular uma matriz de rotas, defina uma variável que contenha a máscara de campo de resposta para especificar o retorno de originIndex, destinationIndex e duration para cada combinação de origem e destino. Em seguida, transmita essa variável para a solicitação:
const ( fieldMask = "originIndex,destinationIndex,duration" )
Considerações sobre o caminho do campo
Inclua apenas os campos necessários na resposta para retornar apenas os campos de que você precisa:
- Diminui os tempos 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 os campos no nível superior, poderá ocorrer uma degradação do desempenho quando novos campos forem adicionados e, em seguida, incluídos automaticamente na resposta.
- Resulta em um tamanho de resposta menor, o que se traduz em maior capacidade de processamento de rede.
- Garante que você não solicite dados desnecessários, o que ajuda a evitar tempo de processamento e cobranças desnecessárias.
Para mais detalhes sobre como criar uma máscara de campo, consulte field_mask.proto.