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 quali informazioni deve restituire la risposta. 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 anche di non richiedere dati non necessari, il che a sua volta contribuisce alla latenza della risposta ed evita di restituire informazioni di cui il sistema non ha bisogno.

Specifica l'elenco dei campi di cui hai bisogno in una maschera di campo della risposta. Poi passa la maschera di campo della 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, consulta Parametri di sistema.

Definisci una maschera di campo della risposta

La maschera di 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 al campo specificato.

Crea e specifica un percorso di campo nel modo seguente:

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

  3. Combina le maschere di campo per tutti i campi di cui hai bisogno, separando le maschere di campo con virgole. Ad esempio, per richiedere distanceMeters per la tappa del percorso, oltre alla durata di ogni passaggio della tappa del percorso, 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 di 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 all'API Routes Compute Routes o Compute Route Matrix collegati nell'elenco seguente. 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 di campo. Per maggiori dettagli su come ottenere la gerarchia dei campi, consulta Determinare la maschera di campo da utilizzare.

  • Maschera di campo per il calcolo del 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 di campo per il calcolo della matrice di percorsi

Determina le maschere di campo da utilizzare

Ecco come puoi determinare i campi che vuoi utilizzare e creare le maschere di campo per questi 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 di campo utilizzando la gerarchia dei campi mostrata nel passaggio precedente, utilizzando questo formato:

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

Ad esempio, per questa risposta parziale da un percorso:

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

Se vuoi restituire solo il campo distanceMeters per la tappa del percorso, ovvero l'ultimo distanceMeters nell'esempio precedente, la maschera di campo è la seguente:

routes.legs.distanceMeters

Se invece vuoi restituire il campo distanceMeters per ogni passaggio della tappa del percorso, ovvero distanceMeters in steps nell'esempio precedente, la maschera di campo è la seguente:

routes.legs.steps.distanceMeters

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

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

Esempi di percorsi di maschere di campo

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

Chiamata REST a computeRoutes

Nel primo esempio, utilizzi una chiamata REST al computeRoutes metodo per calcolare un percorso. In questo esempio, nell'intestazione, specifichi le maschere di campo per restituire i campi distanceMeters e duration del percorso 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 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 di campo della 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, quindi i risultati vengono restituiti con una latenza inferiore.
  • Garantisce prestazioni di latenza stabili. Se selezioni tutti i campi o tutti i campi di primo livello, potresti riscontrare un peggioramento delle prestazioni quando vengono aggiunti nuovi campi e poi inclusi automaticamente nella risposta.
  • Comporta una dimensione della risposta inferiore, che si traduce in una maggiore velocità di trasmissione della rete.
  • Garantisce di non richiedere dati non necessari, il che aiuta a evitare tempi di elaborazione e addebiti fatturati non necessari.

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