Scegliere le informazioni da restituire

Quando chiami un metodo per calcolare un percorso o una matrice di percorsi, devi specificare le informazioni che ti interessano elencando i campi da ritornare nella risposta. Non esiste un elenco predefinito dei campi restituiti. Se ometti questo elenco, i metodi restituiscono un errore.

Specifica l'elenco di campi creando una maschera di campo di risposta. Poi passi la maschera del campo di risposta a uno dei metodi utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP o gRPC X-Goog-FieldMask.

L'utilizzo di una maschera di campo è una buona prassi di progettazione per assicurarti di non richiedere dati non necessari, il che a sua volta contribuisce a evitare tempi di elaborazione e addebiti inutilmente lunghi.

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

Definisci una maschera del campo di risposta

La maschera del campo di 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 al campo specificato.

Costruisci e specifica un percorso del campo come segue:

1. Trova i campi che contengono le informazioni necessarie nell'API Routes. Per maggiori dettagli, consulta Riferimenti ai campi.
2. Determina i percorsi per i campi necessari e crea le rispettive maschere di campo: per maggiori dettagli, vedi Determinare la maschera di campo da utilizzare.

3. Combina le maschere di campo per tutti i campi di cui hai bisogno, separando le maschere di campo con virgole. Ad esempio, per richiedere il distanceMeters per la tratta del percorso, oltre alla durata di ogni passaggio della tratta, inseriscili entrambi, separati da una virgola, senza spazi:

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

4. Invia la maschera di campo con la richiesta API. Ad esempio, in una richiesta cURL, devi specificare la maschera del campo con -H e X-Goog-FieldMask:

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

Per esempi e ulteriori dettagli, consulta le sezioni seguenti.

Riferimenti ai campi

Per visualizzare i campi che puoi richiedere in una risposta tramite le maschere di campo, consulta i riferimenti all'API Routes collegati nell'elenco seguente. Specifica i campi in lettere maiuscole iniziali come mostrato nel riferimento. Ad esempio, routePreference.

Al contrario, devi inserire i valori dei parametri come mostrato. Ad esempio, per routingPreference devi inserire TRAFFIC_AWARE.

Questi riferimenti includono i campi disponibili; tuttavia, devi fare riferimento alla gerarchia dei campi per determinare il percorso completo della maschera di campo. Per informazioni dettagliate su come ottenere la gerarchia dei campi, vedi Determinare la maschera di campo da utilizzare.

• Maschera del campo del percorso di calcolo
  • REST: specifica i campi dell'oggetto Route nella risposta da restituire, premessi da routes., ad esempio routes.distanceMeters.
  • gRPC: specifica i campi dell'oggetto Route nella risposta da restituire.
• Calcolo delle maschere dei campi della matrice di route
  • REST: specifica i campi del corpo della risposta da restituire.
  • gRPC: specifica i campi dell'oggetto RouteMatrixElement nella risposta da restituire.

Determinare quali maschere dei campi utilizzare

Ecco come determinare i campi da utilizzare e come creare le relative maschere di campo:

1. Richiedi tutti i campi utilizzando la maschera dei campi *.
   Attenzione:anche se puoi utilizzare questa maschera per i campi con caratteri jolly in fase di sviluppo, per determinare quali campi sono necessari, non utilizzarla in produzione. La richiesta di tutti i campi in produzione comporta costi più elevati e tempi di risposta più lunghi. Il costo potrebbe anche aumentare in modo imprevisto con l'aggiunta di funzionalità più avanzate, poiché questa maschera di campo le includerà automaticamente. Richiedi invece solo i campi necessari per ridurre al minimo i costi e il tempo di risposta della richiesta.
2. Esamina la gerarchia dei campi nella risposta per i campi che ti interessano.

3. Costruisci le maschere dei campi utilizzando la gerarchia dei campi mostrata nel passaggio precedente, con questo formato:

   topLevelField[.secondLevelField][.thirdLevelField][...]

   Nota: non utilizzare spazi nell'elenco dei percorsi dei campi.

Ad esempio, per questa risposta parziale da un percorso:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

Se vuoi restituire solo il campo distanceMeters per la tratta del percorso, ovvero l'ultimo distanceMeters nell'esempio precedente, la maschera di campo è la seguente:

routes.legs.distanceMeters

Se invece vuoi restituire il campo distanceMeters per ogni passaggio del tratto del percorso, ovvero distanceMeters in steps nell'esempio precedente, la maschera del campo è il seguente:

routes.legs.steps.distanceMeters

Se vuoi restituire entrambi, con il risultato riportato sopra, la maschera di campo è la seguente:

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

Esempi di percorsi delle maschere di campo

Questa sezione contiene altri esempi su come specificare un percorso di campo come parte di una maschera del campo di risposta nelle chiamate REST e gRPC.

Chiamata REST a computeRoutes

Nel primo esempio, viene utilizzata una chiamata REST al metodo computeRoutes per calcolare una route. In questo esempio, nell'intestazione specifichi le maschere di campo per restituire i campi distanceMeters e duration della route nella risposta. Ricorda di aggiungere il prefisso routes al nome del campo.

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

Chiamata REST a computeRouteMatrix

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

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 solo i campi necessari nella risposta per restituire solo i campi di cui hai bisogno:

• Riduci i tempi di elaborazione, in modo che i risultati vengano restituiti con una latenza inferiore.
• Garantisce prestazioni di latenza stabili. Se selezioni tutti i campi o tutti i campi di primo livello, potresti riscontrare un calo del rendimento quando vengono aggiunti nuovi campi che poi vengono inclusi automaticamente nella risposta.
• Risulta in una dimensione della risposta più piccola, che si traduce in una maggiore velocità effettiva di rete.
• Ti assicura di non richiedere dati non necessari, il che contribuisce a evitare tempi di elaborazione e addebiti non necessari.

Nota: quando viene analizzato un messaggio di risposta e un campo al suo interno contiene il valore predefinito, il campo potrebbe essere omesso dalla risposta anche se lo hai specificato nella maschera dei campi di risposta. Per ulteriori informazioni, consulta la Guida al linguaggio (proto3). Ad esempio, quando calcoli una matrice di percorsi, il campo distanceMeters della risposta può contenere un valore pari a 0, il valore predefinito. Poiché 0 è il valore predefinito di distanceMeters, viene omesso dalla risposta.

Per ulteriori dettagli sulla creazione di una maschera di campo, consulta field_mask.proto.

Richiedi un token percorso

Per richiedere che l'API Routes restituisca i token percorso per i percorsi generati:

1. Imposta i seguenti parametri necessari per restituire un token di route:
   • Imposta travelMode su DRIVE.
   • Imposta routingPreference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
2. Verifica che nessuna delle tappe del percorso sia via.
3. Specifica la maschera di campo routes.routeToken per restituire un token di percorso:

   X-Goog-FieldMask: routes.routeToken

Nota: a causa delle condizioni stradali dinamiche, i percorsi generati con un determinato token potrebbero essere diversi dal percorso pianificato. Per ridurre al minimo le differenze, utilizza il token entro pochi minuti dalla sua generazione.

Puoi utilizzare il token percorso per il percorso pianificato nell'SDK Navigation. Per ulteriori dettagli, vedi Pianificare un percorso (Android) o Pianificare un percorso (iOS).

Esempio di token route

Di seguito è riportato un esempio di corpo della richiesta cURL per un percorso con una sola origine e una sola destinazione, che utilizza le maschere di campo per richiedere un token percorso, oltre alla durata, alla distanza e al polilinea del percorso:

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'

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