Scegliere le informazioni da restituire

Quando chiami un metodo per calcolare una route o una matrice di route, devi specificare le informazioni desiderate specificando i campi che vuoi restituire nella risposta. Non esiste un elenco predefinito di campi restituiti. Se ometti questo elenco, i metodi restituiscono un errore.

L'elenco dei campi viene specificato creando una maschera del campo di risposta. Successivamente, passi la maschera del campo della risposta a entrambi i metodi utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP o gRPC X-Goog-FieldMask.

Il mascheramento dei campi è una buona pratica di progettazione per garantire di non richiedere dati non necessari, il che contribuisce a evitare tempi di elaborazione e addebiti fatturati inutili.

Per ulteriori informazioni sui parametri URL, consulta Parametri di sistema.

Definisci una maschera per il campo della risposta

La maschera del campo della risposta è un elenco di percorsi separati da virgole, in cui ogni percorso specifica un campo univoco nel messaggio di risposta. Il percorso inizia dal messaggio di risposta di primo livello e utilizza un percorso separato da punti per il campo specificato.

Crea un percorso di campo nel seguente modo:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Maschera del campo della route Compute
    • REST: specifica i campi dell'oggetto Route nella risposta da restituire, con il prefisso routes., ad esempio routes.distanceMeters.
    • gRPC: specifica i campi dell'oggetto Route nella risposta da restituire.
  • Mascherine del campo della matrice di route Compute

Per ulteriori informazioni su come creare le maschere dei campi, consulta field_mask.proto.

Stabilire quali maschere di campo utilizzare

Per determinare quali maschere per i campi vuoi utilizzare:

  1. Richiedi tutti i campi utilizzando una maschera di campo *.
  2. Osserva la gerarchia dei campi nella risposta e determina quali campi vuoi.
  3. Crea la maschera del campo utilizzando la gerarchia dei campi.

Ad esempio, per questa risposta parziale da una linea di trasporto pubblico:

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

Se vuoi restituire solo il campo distanceMeters, la maschera del campo è:

routes.legs.distanceMeters

Un altro esempio: per restituire tutto il contenuto in legs nella risposta, la maschera del campo è:

routes.legs

Specifica il percorso di un campo

Questa sezione contiene esempi su come specificare un percorso di campo come parte di una maschera di campo di risposta.

Chiamata REST a computeRoutes

Nel primo esempio, utilizzerai una chiamata REST al metodo computeRoutes per calcolare una route. In questo esempio, nell'intestazione, specifichi le maschere dei campi per restituire i campi Route.distanceMeters e Route.duration nella risposta. Ricorda di far precedere il nome del campo da routes. 

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

Chiamata REST a computeRouteMatrix

Per il metodo REST computeRouteMatrix utilizzato per calcolare una matrice di route, nell'intestazione, specifica di restituire originIndex, destinationIndex e duration per ogni combinazione di origine e destinazione:

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

Chiamata gRPC

Per gRPC, imposta una variabile contenente la maschera del campo di risposta. Puoi quindi passare questa variabile alla richiesta.

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

Considerazioni sui percorsi dei campi

Includi nella risposta solo i campi obbligatori. Per restituire solo i campi che ti servono:

  • Riduce i tempi di elaborazione, in modo che i risultati vengano restituiti con una latenza inferiore.
  • Garantisce prestazioni di latenza stabili se l'API aggiunge altri campi di risposta in futuro e questi nuovi campi richiedono tempo di calcolo aggiuntivo. Se selezioni tutti i campi o tutti i campi al livello superiore, potresti riscontrare un peggioramento delle prestazioni quando tutti i nuovi campi vengono inclusi automaticamente nella risposta.
  • Genera una risposta di dimensioni inferiori, che si traduce in una velocità effettiva di rete maggiore.
  • Garantisce di non richiedere dati inutili, il che contribuisce a evitare tempi di elaborazione e addebiti fatturati inutili.

Richiedere un token di route

Per richiedere che l'API Routes restituisca i token di route per le route generate, segui i requisiti per restituire un token di route, quindi utilizza la maschera del campo routes.route_token per richiedere il token:

  1. Imposta travel_mode su DRIVING.
  2. Imposta routing_preference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
  3. Controlla che nessuno dei waypoint del percorso sia via waypoint.
  4. Specifica la maschera per il campo del token di route: 
    -H X-Goog-FieldMask: routes.route_token

Puoi utilizzare il percorso pianificato nell'SDK di navigazione. Per maggiori dettagli, consulta Pianificare un percorso (Android) o Pianificare un percorso (iOS).

Esempio di token di route

Ecco un esempio di corpo di richiesta cURL per una singola route di origine, a destinazione singola, in cui vengono utilizzate maschere di campo per richiedere un token di route, insieme a durata, distanza e polilinea della route:

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'

Per maggiori dettagli, consulta il riferimento per l'API Compute Routes.