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
- Mascherine del campo della matrice di route Compute
- REST: specifica i campi del corpo della risposta da restituire.
- gRPC: specifica i campi dell'oggetto RouteMatrixElement nella risposta da restituire.
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:
- Richiedi tutti i campi utilizzando una maschera di campo
*
. - Osserva la gerarchia dei campi nella risposta e determina quali campi vuoi.
- 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:
- Imposta
travel_mode
suDRIVING
. - Imposta
routing_preference
suTRAFFIC_AWARE
oTRAFFIC_AWARE_OPTIMAL
. - Controlla che nessuno dei waypoint del percorso sia
via
waypoint. - 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.