Quando effettui una richiesta di geocodifica, puoi utilizzare una maschera di campo per specificare l'elenco dei campi da restituire nella risposta. Per gli endpoint Geocodifica di un indirizzo, Geocodifica di una località e Geocodifica di un luogo, tutti i campi dell'oggetto risposta vengono restituiti per impostazione predefinita. Per l'endpoint Cerca destinazioni, devi specificare una maschera di campo nella richiesta API.
Utilizza una maschera di campo per assicurarti di non richiedere dati non necessari, il che a sua volta contribuisce alla latenza della risposta.
Definisci una maschera del campo di risposta
La maschera del campo di risposta è un elenco di percorsi separati da virgole senza spazi, in cui ogni percorso specifica un campo univoco nell'oggetto risposta. Il percorso inizia dal campo di risposta di primo livello e utilizza un percorso separato da punti a un campo specificato.
Trasmetti la maschera del campo di risposta a una richiesta utilizzando il parametro URL $fields
o fields oppure utilizzando l'intestazione HTTP o gRPC X-Goog-FieldMask.
Maschere di campo di esempio
Di seguito è riportata la risposta completa a una richiesta di geocodifica diretta:
{ "results": [ { "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE", "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "location": { "latitude": 37.422010799999995, "longitude": -122.08474779999999 }, "granularity": "ROOFTOP", "viewport": { "low": { "latitude": 37.420656719708511, "longitude": -122.08547523029148 }, "high": { "latitude": 37.4233546802915, "longitude": -122.0827772697085 } }, "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", ... }
Costruisci le maschere dei campi utilizzando la gerarchia dei campi di risposta nel modulo:
topLevelField[.secondLevelField][.thirdLevelField][...]
Ad esempio, per restituire solo il campo placeId nella risposta, utilizza una maschera
di campo:
curl -X GET -H 'Content-Type: application/json' \ -H 'X-Goog-FieldMask: results.placeId' \ -H "X-Goog-Api-Key: API_KEY" \ "https://"geocode.googleapis.com/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"
La risposta ora è:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE" } ] }
Per restituire il campo viewport, la maschera del campo è:
-H 'X-Goog-FieldMask: results.viewport'
La risposta ora è:
{ "results": [ { "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Per restituire entrambi:
-H 'X-Goog-FieldMask: results.placeId,results.viewport'
La risposta ora è:
{ "results": [ { "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE", "viewport": { "low": { "latitude": 37.420654569708496, "longitude": -122.08547618029148 }, "high": { "latitude": 37.423352530291496, "longitude": -122.0827782197085 } } } ] }
Maschere del campo gRPC
Per gRPC, imposta una variabile contenente la maschera del campo di risposta. Puoi quindi passare questa variabile alla richiesta.
const ( fieldMask = "results.placeId,results.viewport" )
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 delle prestazioni quando vengono aggiunti nuovi campi e poi inclusi automaticamente nella risposta.
- Produce una risposta di dimensioni più ridotte, il che si traduce in un throughput di rete più elevato.
Per maggiori dettagli sulla creazione di una maschera di campo, consulta field_mask.proto.