Scegli le informazioni da restituire
Quando chiami un metodo per calcolare una route o matrice di route, devi specificare le informazioni desiderate mediante l'elenco dei campi da restituire nella risposta. Non esiste un elenco predefinito dei campi restituiti. Se ometti questo elenco, i metodi restituiscono un errore.
Puoi specificare l'elenco dei campi creando una maschera del campo di risposta. Devi quindi passare
la maschera del campo di risposta a entrambi i metodi utilizzando il parametro URL $fields
o
fields
oppure tramite l'intestazione HTTP o gRPC X-Goog-FieldMask
.
L'utilizzo di una maschera di campo è una buona prassi di progettazione per evitare di richiedere dati non necessari, il che a sua volta consente di evitare tempi di elaborazione non necessari e addebiti fatturati.
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 parte dal messaggio di risposta di primo livello e utilizza un percorso separato da punti per il campo specificato.
Crea e specifica un percorso campo come segue:
- Trova i campi che contengono le informazioni necessarie dall'API Routes. Per maggiori dettagli, consulta la sezione Riferimenti dei campi.
- 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.
Combina le maschere dei campi per tutti i campi necessari, separando le maschere dei campi con le virgole. Ad esempio, per richiedere il valore
distanceMeters
per la tratta di percorso, oltre alla durata di ogni tappa del percorso, inseriscili entrambi, separati da una virgola e senza spazi:routes.legs.distanceMeters,routes.legs.steps.duration
Invia la maschera del campo con la richiesta API. Ad esempio, in una richiesta cURL, devi specificare la maschera del campo con
-H
eX-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Riferimenti dei campi
Per visualizzare i campi che puoi richiedere in una risposta tramite le maschere dei campi, fai riferimento ai riferimenti dell'API Routes collegati nell'elenco seguente. Specifica i campi in camel case come mostrato nel riferimento. Ad esempio, routePreference
.
Questi riferimenti includono i campi disponibili; tuttavia, devi fare riferimento alla gerarchia dei campi per determinare il percorso della maschera per l'intero campo. Per informazioni dettagliate su come ottenere la gerarchia dei campi, consulta Definire la maschera dei campi da utilizzare.
- Maschera del campo del percorso di calcolo
- Calcola maschere dei campi della matrice delle 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
Di seguito viene spiegato come determinare quali campi vuoi utilizzare e creare le relative maschere:
- Richiedi tutti i campi utilizzando la maschera dei campi
*
. - Esamina la gerarchia dei campi nella risposta per i campi che ti interessano.
Costruire le maschere dei campi utilizzando la gerarchia dei campi mostrata nel passaggio precedente, utilizzando il seguente formato:
topLevelField[.secondLevelField][.thirdLevelField][...]
Ad esempio, per questa risposta parziale da una route:
"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 del campo è la seguente:
routes.legs.distanceMeters
Se invece vuoi restituire il campo distanceMeters
per ogni passaggio della tratta del percorso, ovvero distanceMeters
in steps
nell'esempio precedente, la maschera del campo è il seguente:
routes.legs.steps.distanceMeters
Se vuoi restituire entrambi i valori, con il risultato riportato sopra, la maschera del campo è il seguente:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
Esempi di percorsi maschera dei campi
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 dei campi 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 questa variabile alla richiesta.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
Considerazioni sui percorsi dei campi
Includi nella risposta solo i campi di cui hai bisogno per restituire solo quelli necessari:
- Riduce i tempi di elaborazione, in modo che i risultati vengano restituiti con una latenza più bassa.
- Garantisce prestazioni di latenza stabili. Se selezioni tutti i campi o tutti i campi al livello più alto, potresti riscontrare un peggioramento delle prestazioni quando vengono aggiunti nuovi campi che vengono poi inclusi automaticamente nella risposta.
- Risultati con risposte di dimensioni inferiori, che si traducono in una maggiore velocità effettiva di rete.
- Assicura che non vengano richiesti dati non necessari, evitando così tempi di elaborazione e addebiti fatturati inutili.
Per ulteriori dettagli sulla creazione di una maschera di campo, consulta field_mask.proto.
Richiedi un token di route
Per richiedere che l'API Routes restituisca token di route per le route generate, segui questi passaggi:
- Imposta i seguenti parametri necessari per restituire un token di route:
- Imposta
travelMode
suDRIVE
. - Imposta
routingPreference
suTRAFFIC_AWARE
oTRAFFIC_AWARE_OPTIMAL
.
- Imposta
- Verifica che nessuna delle tappe del percorso sia
via
. - Specifica la maschera del campo
routes.routeToken
per restituire un token di route:X-Goog-FieldMask: routes.routeToken
Puoi utilizzare il token del percorso per il percorso pianificato nell'SDK di navigazione. Per ulteriori dettagli, vedi 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 origine, percorso di destinazione singola, che utilizza le maschere dei campi per richiedere un token di percorso, insieme alla durata, alla distanza e alla 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 Riferimento API Compute Routes.