Scegli 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. Quindi passi la maschera del campo di risposta a entrambi i metodi utilizzando il parametro URL $fields oppure fields oppure utilizzando 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 non necessari.

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.

Crea e specifica un percorso campo come segue:

  1. Trova i campi che contengono le informazioni necessarie dall'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 dei campi per tutti i campi necessari, separando le maschere dei campi con le 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 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 lettere maiuscole iniziali 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, 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 del Route nel da restituire.
  • Calcolo delle maschere dei campi della matrice di route

Determina quali maschere di campo utilizzare

Di seguito viene spiegato come determinare quali campi vuoi utilizzare e creare le relative maschere:

  1. Richiedi tutti i campi utilizzando una maschera di campo *.
  2. Esamina la gerarchia dei campi nella risposta per i campi che ti interessano.

  3. 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 le ultime 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, 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 del campo all'interno di una maschera di campo della risposta nelle chiamate REST e gRPC.

Chiamata REST a computeRoutes

Nel primo esempio, utilizzi una chiamata REST al metodo computeRoutes per calcolare un itinerario. In questo esempio, nell'intestazione specifichi le maschere di campo per restituire i campi distanceMeters e duration della route nella risposta. Ricordati di anteporre il nome del campo con routes.

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

Chiamata REST a computeRouteMatrix

Per il metodo REST computeRouteMatrix utilizzato per calcolare una matrice di percorsi, nell'intestazione specifica di 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 sul percorso del campo

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 selezionare tutti i campi oppure tutti i campi del livello superiore, un peggioramento delle prestazioni quando vengono aggiunti nuovi campi incluso automaticamente nella risposta.
  • Risulta in una dimensione della risposta più piccola, che si traduce 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 maggiori dettagli sulla creazione di una maschera di campo, consulta field_mask.proto.

Richiedi un token di route

Per richiedere che l'API Routes restituisca i token di 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 nessuno dei waypoint del percorso sia un waypoint via.
  3. Specifica la maschera di campo routes.routeToken per restituire un token di percorso: 
    X-Goog-FieldMask: routes.routeToken

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

Esempio di token di route

Ecco un esempio di corpo di richiesta cURL per una singola origine, destinazione singola utilizzando le maschere di campo per richiedere un token di route, insieme alla route durata, distanza e 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 ulteriori dettagli, consulta Riferimento API Compute Routes.