Sviluppatori dello Spazio economico europeo (SEE)

Scegli i campi da restituire

Quando richiedi un percorso o una matrice di percorsi, devi utilizzare una maschera di campo per specificare le informazioni che la risposta deve restituire. Non esiste un elenco predefinito di campi restituiti. Se non specifichi una maschera di campo, i metodi restituiscono un errore.

L'utilizzo di una maschera di campo garantisce inoltre di non richiedere dati non necessari, il che a sua volta contribuisce alla latenza della risposta ed evita di restituire informazioni che il sistema non richiede.

Specifichi l'elenco dei campi di cui hai bisogno in una maschera dei campi di risposta. Quindi, trasmetti la maschera del campo di risposta a uno dei due metodi utilizzando il parametro URL $fields o fields oppure utilizzando l'intestazione HTTP o gRPC X-Goog-FieldMask.

Per ulteriori informazioni sui parametri URL, vedi 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 nel seguente modo:

  1. Trova i campi che contengono le informazioni che ti servono. Per maggiori dettagli, vedi Riferimenti ai campi.
  2. Determina i percorsi per i campi che ti servono e crea le maschere di campo: per maggiori dettagli, consulta Determinare la maschera di campo da utilizzare.

  3. Combina le maschere di campo per tutti i campi che ti servono, separandole con virgole. Ad esempio, per richiedere distanceMeters per la tratta dell'itinerario, più la 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, specificheresti la maschera del campo con -H e X-Goog-FieldMask:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Per esempi e maggiori 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 di Compute Routes o Compute Route Matrix dell'API Routes collegati nel seguente elenco. Specifica i campi in formato camel case come mostrato nel riferimento. Ad esempio, routePreference.

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

  • Maschera del campo Calcola percorso
    • REST: specifica i campi dell'oggetto Route nella risposta da restituire, con il prefisso routes., ad esempio, routes.distanceMeters.
    • gRPC: specifica i campi dell'oggetto Route nella risposta da restituire.
  • Maschere dei campi di Compute Route Matrix

Determinare quali maschere di campo utilizzare

Ecco come puoi determinare quali campi utilizzare e creare le maschere dei campi:

  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. Crea le maschere dei campi utilizzando la gerarchia dei campi mostrata nel passaggio precedente, utilizzando questo formato:

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

Ad esempio, per questa risposta parziale di un percorso:

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

Se vuoi restituire solo il campo distanceMeters per la tappa dell'itinerario, 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 dell'itinerario, ovvero il campo distanceMeters in steps nell'esempio precedente, la maschera del campo è la seguente:

routes.legs.steps.distanceMeters

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

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

Esempi di percorsi della maschera del campo

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

Chiamata REST a computeRoutes

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

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

Chiamata REST a computeRouteMatrix

Per il metodo REST computeRouteMatrix utilizzato per calcolare una matrice di itinerari, specifica nell'intestazione 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:

  • Riduce 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 a livello principale, potresti notare un peggioramento del rendimento quando vengono aggiunti nuovi campi e poi inclusi automaticamente nella risposta.
  • Produce una dimensione della risposta più piccola, il che si traduce in una velocità effettiva di rete più elevata.
  • Assicura di non richiedere dati non necessari, il che contribuisce a evitare tempi di elaborazione e addebiti non necessari.

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