Questa pagina è stata tradotta dall'API Cloud Translation.

Scegli le informazioni da restituire

Quando chiami un metodo per calcolare una matrice di route o percorsi, devi specificare le informazioni che vuoi mediante l'elenco dei campi 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. 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 assicurarsi di non richiedere di dati non necessari, il che a sua volta contribuisce a evitare inutili tempi di elaborazione 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 path specifica un campo univoco nel messaggio di risposta. Il percorso parte dal messaggio di risposta di primo livello e utilizza un'etichetta separato da punti al 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 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 modalità camel 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 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
- REST: specifica i campi del Route nel risposta da restituire, preceduta da routes., ad esempio, routes.distanceMeters.
- gRPC: specifica i campi del Route nel da restituire.
Calcolare le maschere dei campi della matrice delle route
- REST: specifica i campi del Corpo della risposta da restituire.
- gRPC: specifica i campi del 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 *.
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ù alti e tempi di risposta più lunghi. Il costo potrebbe anche aumentare in modo imprevisto con l'aggiunta di funzionalità più avanzate, dato che questa maschera del campo le include automaticamente. Puoi invece richiedere solo i campi che ti servono per ridurre al minimo i costi e il tempo di risposta.
Esamina la gerarchia dei campi nella risposta alla richiesta campi desiderati.
Costruire le maschere dei campi utilizzando la gerarchia dei campi mostrata nel passaggio precedente, utilizzando il seguente formato:
```
topLevelField[.secondLevelField][.thirdLevelField][...]
```
Nota: non utilizzare spazi in nessun punto dell'elenco dei percorsi dei campi.

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 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 Metodo computeRoutes da calcolare un percorso. 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 RESTO computeRouteMatrix utilizzato per calcolare una matrice di route, specifica nell'intestazione 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 il valore campi necessari:

Riduce i tempi di elaborazione, in modo che i risultati vengano restituiti con una latenza più bassa.
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.
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.

Nota: quando viene analizzato un messaggio di risposta e un campo nella messaggio di risposta contiene il suo valore predefinito, il campo può essere omesso dalla risposta anche se specificata nella maschera del campo di risposta. Per ulteriori informazioni, consulta Guida alle lingue (proto3). Ad esempio, quando calcoli una matrice di route, Il campo distanceMeters della risposta può contenere un valore pari a 0, i relativi predefinito. Poiché 0 è il valore predefinito di distanceMeters, omesso dalla risposta.

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 su DRIVE.
- Imposta routingPreference su TRAFFIC_AWARE o TRAFFIC_AWARE_OPTIMAL.
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) oppure Pianifica un percorso (iOS).

Esempio di token di route

Ecco un esempio di corpo di richiesta cURL per una singola origine, singola destinazione 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.

Scegli le informazioni da restituire

Definisci una maschera del campo di risposta

Riferimenti dei campi

Determinare quali maschere dei campi utilizzare

Esempi di percorsi maschera dei campi

Chiamata REST a computeRoutes

Chiamata REST a computeRouteMatrix

Chiamata gRPC

Considerazioni sui percorsi dei campi

Richiedi un token di route

Esempio di token di route

Chiamata REST a `computeRoutes`

Chiamata REST a `computeRouteMatrix`