Scegli i campi da restituire

Sviluppatori dello Spazio economico europeo (SEE)

Introduzione

Quando chiami i metodi Place Details (New), Nearby Search (New) o Text Search (New), devi specificare i campi che vuoi vengano restituiti nella risposta. Non esiste un elenco predefinito di campi restituiti. Se ometti questo elenco, i metodi restituiscono un errore.

Un elenco completo dei campi di dati supportati e dei relativi SKU è disponibile in Campi di dati sui luoghi (nuovo). Per informazioni sui campi specifici di ciascuna API, consulta quanto segue:

  • Parametri FieldMask di Place Details (New)
  • Parametri FieldMask di Ricerca nelle vicinanze (nuova)
  • Parametri FieldMask di Text Search (New)

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

Il mascheramento dei campi è una buona pratica di progettazione per assicurarsi di non richiedere dati non necessari, il che contribuisce a evitare tempi di elaborazione e addebiti non necessari.

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 corpo della risposta. Il percorso inizia dal messaggio di risposta di primo livello e utilizza un percorso separato da punti al campo specificato.

Crea un percorso del campo nel seguente modo:

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

Puoi richiedere tutti i campi utilizzando una maschera di campo *.

Per saperne di più su come creare maschere di campo, consulta field_mask.proto.

Determinare quali maschere di campo utilizzare

Ecco come determinare quali maschere di campo vuoi utilizzare:

  1. Richiedi tutti i campi utilizzando una maschera di campo *.
  2. Esamina la gerarchia dei campi nella risposta e determina quali campi ti interessano.
  3. Crea la maschera del campo utilizzando la gerarchia dei campi.

Definisci una maschera del campo di risposta per Ricerca nelle vicinanze (nuova) e Ricerca di testo (nuova)

Ricerca nelle vicinanze (nuova) e Ricerca di testo (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 visualizzare l'oggetto di risposta completo di una ricerca di testo (nuova):

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 risposta completo di una chiamata Text Search (New) ha il seguente 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, devi specificare una maschera di campo 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

La specifica di displayName include sia i campi text sia 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 (New)

Place Details (New) 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 di 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 questa variabile alla richiesta.

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

Considerazioni sul percorso del campo

Includi solo i campi necessari nella risposta. Restituzione solo dei campi necessari:

  • Riduce i tempi di elaborazione, in modo che i risultati vengano restituiti con una latenza inferiore.
  • Garantisce prestazioni di latenza stabili se in futuro l'API aggiunge altri campi di risposta e questi nuovi campi richiedono tempi di calcolo aggiuntivi. Se selezioni tutti i campi o tutti i campi a livello principale, potresti notare un calo delle prestazioni quando tutti i nuovi campi vengono inclusi automaticamente nella risposta.
  • Produce una risposta di dimensioni più ridotte, il che si traduce in un throughput di rete più elevato.
  • Assicura di non richiedere dati non necessari, il che aiuta a evitare tempi di elaborazione e addebiti non necessari.