Scegli quali informazioni restituire

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

Per specificare l'elenco dei campi, crea 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, il che contribuisce a evitare tempi di elaborazione e addebiti fatturati.

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

Definisci una maschera per il campo di 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 al campo specificato.

Per creare il percorso di un campo:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • Maschera del campo della route Compute
    • REST: specifica i campi dell'oggetto Route nella risposta da restituire, preceduti da 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 su come creare maschere di campo, consulta field_mask.proto.

Determinare quali maschere di campo utilizzare

Per determinare quali maschere di campo 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 dei campi utilizzando la gerarchia dei campi.

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

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

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

routes.legs.distanceMeters

Un altro esempio: per restituire tutto ciò che si trova in legs nella risposta, la maschera del campo è:

routes.legs

Specifica il percorso di un campo

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

Chiamata REST a computeRoutes

Nel primo esempio, utilizzi 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. Ricordati di anteporre routes al nome del campo. 

-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 la variabile alla richiesta.

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

Considerazioni sui percorsi dei campi

Includi nella risposta solo i campi obbligatori. 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 più tempo di calcolo. 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 risposte di dimensioni inferiori, che si traduce in una velocità effettiva di rete più elevata.
  • Garantisce di non richiedere dati superflui, per 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 la restituzione di 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 tuo 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, consulta Pianificare un percorso (Android) o Pianificare un percorso (iOS).

Esempio di token di route

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

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.