Scegli 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 da 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 mediante la creazione di una maschera per il campo di risposta. Puoi quindi passare la maschera del campo di risposta a uno dei due 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, in modo da evitare tempi di elaborazione e addebiti fatturati.

Per ulteriori informazioni sui parametri URL, consulta la sezione 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 parte dal messaggio di risposta di primo livello e utilizza un percorso separato da punti per il campo specificato.

Costruisci il percorso di un campo nel seguente modo:

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

Per ulteriori informazioni sulla creazione delle maschere dei campi, consulta field_mask.proto.

Stabilire quali maschere dei campi utilizzare

Per determinare le maschere per i campi da utilizzare, procedi nel seguente modo:

  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 un percorso di trasporto pubblico:

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

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

routes.legs.distanceMeters

Un altro esempio: per restituire tutto ciò che è presente in legs nella risposta, la maschera di campo è:

routes.legs

Specifica il percorso di un campo

Questa sezione contiene esempi di 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 richiesti. Tornando solo ai 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 tempi di calcolo aggiuntivi. 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 più elevata.
  • Garantisce di non richiedere dati non necessari, il che contribuisce a evitare tempi di elaborazione e addebiti fatturati.

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 tappe del percorso sia via tappe.
  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, vedi Pianificare un percorso (Android) o Pianificare un percorso (iOS).

Esempio di token di route

Ecco un corpo della richiesta di esempio per una singola route di origine con destinazione singola e l'utilizzo di maschere di campo per richiedere un token di route, insieme a durata, distanza e polilinea della route:

terminal
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-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.