Quando chiami i metodi Dettagli luogo (nuova), Ricerca nelle vicinanze (Nuova) o Ricerca testuale (Nuova), devi specificare quali campi vuoi che vengano restituiti 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. Devi quindi passare
la maschera del campo di risposta a entrambi i metodi utilizzando il parametro $fields
o
fields
oppure tramite l'intestazione HTTP o gRPC X-Goog-FieldMask
.
Il mascheramento dei campi è una buona pratica di progettazione per evitare di richiedere dati non necessari, evitando così tempi di elaborazione e addebiti inutili.
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 parte dal messaggio di risposta di primo livello e utilizza un percorso separato da punti per il campo specificato.
Crea un percorso campo nel seguente modo:
topLevelField[.secondLevelField][.thirdLevelField][...]
Puoi richiedere tutti i campi utilizzando la maschera dei campi *
.
Per ulteriori informazioni su come creare maschere di campo, consulta field_mask.proto.
Determinare quali maschere dei campi utilizzare
Ecco come puoi determinare quali maschere di campi vuoi utilizzare:
- Richiedi tutti i campi utilizzando una maschera di campo "*".
- Esamina la gerarchia dei campi della risposta e stabilisci quali campi ti interessa.
- Crea la maschera dei campi utilizzando la gerarchia dei campi.
Definisci una maschera del campo di risposta per Ricerca nelle vicinanze (nuova) e Ricerca testuale (nuova)
La ricerca nelle vicinanze (nuova) e la ricerca testuale (nuova) restituiscono un array di oggetti Place nel campo places
della risposta. Per queste API, places
è il campo
di primo livello della risposta.
Ad esempio, per vedere l'oggetto risposta completa da una ricerca testuale (novità):
curl -X POST -d '{ "textQuery" : "Spicy Vegetarian Food in Sydney, Australia" }' \ -H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: *' \ 'https://places.googleapis.com/v1/places:searchText'
L'oggetto di risposta completa di una chiamata Ricerca testuale (Nuova) è nel formato:
{ "places": [ { "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0", "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0", "types": [ "vegetarian_restaurant", "vegan_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "nationalPhoneNumber": "0433 479 794", "internationalPhoneNumber": "+61 433 479 794", "formattedAddress": "29 King St, Sydney NSW 2000, Australia", "displayName": { "text": "Spiced @ Barangaroo", "languageCode": "en" }, ... }, ... ] }
Pertanto, specifichi una maschera dei campi per queste API nel formato:
places[.secondLevelField][.thirdLevelField][...]
Se vuoi restituire solo i campi formattedAddress
e displayName
, imposta la maschera del campo su:
places.formattedAddress,places.displayName
Se specifichi displayName
, vengono inclusi entrambi i campi text
e language
di displayName
. Se vuoi solo il campo text
, imposta la maschera del campo come segue:
places.formattedAddress,places.displayName.text
Definisci una maschera del campo di risposta per Place Details (novità)
Place Details restituisce un singolo oggetto Place nel formato:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "types": [ "locality", "political" ], "formattedAddress": "Trinidad, CA 95570, USA", "displayName": { "text": "Trinidad", "languageCode": "en" } ... }
Pertanto, devi specificare una maschera del campo per questa API specificando i campi dell'oggetto Place che vuoi restituire:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: formattedAddress,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
Chiamata gRPC
Per gRPC, imposta una variabile contenente la maschera del campo di risposta. Puoi quindi passare la variabile alla richiesta.
const ( fieldMask = "places.formattedAddress,places.displayName" )
Considerazioni sui percorsi dei campi
Includi nella risposta solo i campi di cui hai bisogno. Vengono restituiti solo i campi necessari:
- Riduce i tempi di elaborazione, in modo che i risultati vengano restituiti con una latenza minore.
- Garantisce prestazioni di latenza stabili se l'API aggiunge più campi di risposta in futuro e questi nuovi campi richiedono tempi di calcolo aggiuntivi. Se selezioni tutti i campi o tutti i campi al livello più alto, potresti riscontrare un peggioramento delle prestazioni quando tutti i nuovi campi vengono inclusi automaticamente nella risposta.
- Risultati con risposte di dimensioni inferiori, che si traducono in una maggiore velocità effettiva di rete.
- Assicura di non richiedere dati non necessari, evitando così tempi di elaborazione non necessari e addebiti fatturati.