Escolher quais informações serão retornadas

Ao chamar um método para calcular uma rota ou matriz de rotas, especifique as informações que 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 vão retornar 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 método usando o parâmetro de URL $fields ou fields ou usando 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 tempo de processamento desnecessário e cobranças.

Para mais informações sobre os 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:

  1. 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.
  2. Determine os caminhos dos campos necessários e crie as máscaras de campo para eles: para saber mais, consulte Determinar qual máscara de campo você quer usar.

  3. Combine as máscaras de campo para todos os campos necessários, separando-as por vírgulas. Por exemplo, para solicitar o distanceMeters do trecho da rota e a duração de cada etapa do trecho, insira ambos, separados por vírgula, sem espaços:

    routes.legs.distanceMeters,routes.legs.steps.duration

  4. 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 -H e X-Goog-FieldMask:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Para conferir exemplos e mais detalhes, consulte as próximas seções.

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 na lista a seguir. Especifique os campos em letras maiúsculas e minúsculas, conforme mostrado na referência. Por exemplo, routePreference.

Essas referências incluem os campos disponíveis. No entanto, você precisa consultar a hierarquia dos campos para determinar o caminho completo da máscara de campo. Para saber 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
    • 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.
  • Compute as máscaras de campo da matriz de rotas

Determinar quais máscaras de campo usar

Veja como determinar quais campos você quer usar e criar as máscaras de campo para eles:

  1. Solicitar todos os campos usando uma máscara de campo de *.
  2. Observe a hierarquia dos campos na resposta para os campos que você quer.

  3. Crie as máscaras de campo usando a hierarquia dos campos mostrados na etapa anterior, usando 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 da rota, ou seja, o último distanceMeters no exemplo anterior, a máscara de campo será a seguinte:

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, a máscara de campo será a seguinte:

routes.legs.steps.distanceMeters

Se você quiser retornar os dois, com o resultado acima, a 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. Adicione 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 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. Em seguida, é 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 para retornar apenas os campos necessários:

  • 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 eles no nível superior, poderá haver uma queda no desempenho quando novos campos forem adicionados e incluídos automaticamente na resposta.
  • Resulta em um tamanho de resposta menor, o que se traduz em maior capacidade de processamento da 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 construir uma máscara de campo, consulte o field_mask.proto.

Solicitar um token de trajeto

Para solicitar que a API Routes retorne tokens de rota para rotas geradas, siga estas etapas:

  1. Defina os seguintes parâmetros necessários para retornar um token de rota:
    • Defina travelMode como DRIVE.
    • Defina routingPreference para TRAFFIC_AWARE ou TRAFFIC_AWARE_OPTIMAL.
  2. Verifique se nenhum dos seus pontos de passagem da rota são pontos de passagem via.
  3. Especifique a máscara de campo routes.routeToken para retornar um token de rota: 
    X-Goog-FieldMask: routes.routeToken

Você pode usar o token de rota para sua rota planejada no SDK de navegação. Para mais detalhes, consulte Planejar uma rota (Android) ou Planejar uma rota (iOS).

Exemplo de token de rota

Confira um exemplo de corpo de solicitação cURL para uma rota de origem e destino únicos, usando máscaras de campo para solicitar um token de rota, além da duração, distância e 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.