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 inoltre che non vengano richiesti dati non necessari, il che a sua volta contribuisce alla latenza della risposta ed evita di restituire informazioni non necessarie al sistema.

Specifica l'elenco dei campi necessari in una maschera dei campi di risposta. Quindi, passi la maschera dei campi di risposta a uno dei due metodi utilizzando il parametro URL $fields o fields oppure l'intestazione HTTP o gRPC X-Goog-FieldMask.

Per saperne di più 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 per il campo specificato.

Crea e specifica un percorso del campo come segue:

  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 necessari e crea le maschere di campo corrispondenti: per maggiori dettagli, consulta Determina la maschera di campo da utilizzare.

  3. Combina le maschere di campo per tutti i campi necessari, separandole con virgole. Ad esempio, per richiedere distanceMeters per la tappa del percorso, più la durata di ogni passaggio della tappa del percorso, inserisci entrambi i valori, 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 di 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 ai campi

Per visualizzare i campi che puoi richiedere in una risposta tramite maschere di campo, consulta i riferimenti di Compute Routes o Compute Route Matrix dell'API Routes collegati nel seguente elenco. Specifica i campi in notazione a cammello, 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 informazioni dettagliate su come ottenere la gerarchia dei campi, consulta Determina la maschera di campo che vuoi utilizzare.

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

Determina quali maschere di campo utilizzare

Ecco come puoi determinare i campi da utilizzare e creare le relative maschere:

  1. Richiedi tutti i campi utilizzando una maschera di campo di *.
  2. Osserva 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 di 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 riportato sopra, la maschera di campo è la seguente:

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

Esempi di percorsi della maschera di campo

Questa sezione contiene altri esempi su come specificare un percorso di campo come parte di una maschera di 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 del percorso nella risposta. Ricorda di anteporre 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 a computeRoutes

Per il metodo gRPC computeRoutes utilizzato per calcolare un percorso, imposta una variabile contenente la maschera di campo della risposta per restituire i campi distanceMeters, duration e della polilinea codificata del percorso nella risposta. Puoi quindi passare la variabile alla richiesta:

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Chiamata gRPC a computeRouteMatrix

Per il metodo gRPC computeRouteMatrix utilizzato per calcolare una matrice di percorsi, imposta una variabile contenente la maschera di campo della risposta per specificare la restituzione di originIndex, destinationIndex e duration per ogni combinazione di origine e destinazione. Puoi quindi passare la variabile alla richiesta:

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

Considerazioni sul percorso del campo

Includi nella risposta solo i campi che ti servono 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 se selezioni 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.
  • Genera una risposta di dimensioni inferiori, il che si traduce in una maggiore velocità effettiva di rete.
  • Assicura che non vengano richiesti dati non necessari, il che aiuta a evitare tempi di elaborazione e addebiti di fatturazione non necessari.

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