Lorsque vous appelez les méthodes Place Details (New), Nearby Search (New) ou Text Search (New), vous devez spécifier les champs que vous souhaitez renvoyer dans la réponse. Il n'existe pas de liste par défaut des champs renvoyés. Si vous omettez cette liste, les méthodes renvoient une erreur.
Pour spécifier la liste des champs, créez un masque de champ de réponse. Vous transmettez ensuite le masque de champ de réponse à l'une ou l'autre méthode à l'aide du paramètre $fields ou fields, ou de l'en-tête HTTP ou gRPC X-Goog-FieldMask.
Le masquage de champ est une bonne pratique de conception pour vous assurer de ne pas demander de données inutiles. Vous pourrez ainsi réduire le temps de traitement et les frais facturés.
Définir un masque de champ de réponse
Le masque de champ de réponse est une liste de chemins d'accès séparés par une virgule, où chaque chemin spécifie un champ unique dans le message de réponse. Le chemin d'accès commence à partir du message de réponse de premier niveau et utilise un chemin d'accès séparé par un point au champ spécifié.
Pour construire un chemin d'accès de champ, procédez comme suit:
topLevelField[.secondLevelField][.thirdLevelField][...]
Vous pouvez demander tous les champs en utilisant un masque de champ de *.
Pour en savoir plus sur la construction de masques de champ, consultez le fichier field_mask.proto.
Déterminer les masques de champ à utiliser
Voici comment déterminer les masques de champ que vous souhaitez utiliser:
- Demandez tous les champs en utilisant un masque de champ "*".
- Examinez la hiérarchie des champs dans la réponse et déterminez les champs qui vous intéressent.
- Créez votre masque de champ à l'aide de la hiérarchie des champs.
Définir un masque de champ de réponse pour Nearby Search (nouveau) et Text Search (nouveau)
Nearby Search (New) et Text Search (New) renvoient un tableau d'objets Place dans le champ places de la réponse. Pour ces API, places est le champ de premier niveau de la réponse.
Par exemple, pour afficher l'objet de réponse complet à partir d'une recherche de texte (New):
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'objet de réponse complet d'un appel Text Search (New) se présente sous la forme suivante:
{
"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"
}, ...
},
...
]
}
Par conséquent, vous spécifiez un masque de champ pour ces API au format suivant:
places[.secondLevelField][.thirdLevelField][...]
Si vous ne souhaitez renvoyer que les champs formattedAddress et displayName, définissez votre masque de champ sur:
places.formattedAddress,places.displayName
Spécifier displayName inclut les champs text et language de displayName. Si vous ne voulez que le champ text, définissez le masque de champ comme suit:
places.formattedAddress,places.displayName.text
Définir un masque de champ de réponse pour Place Details (nouveau)
Place Details renvoie un seul objet Place au format suivant:
{
"name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
"id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
"types": [
"locality",
"political"
],
"formattedAddress": "Trinidad, CA 95570, USA",
"displayName": {
"text": "Trinidad",
"languageCode": "en"
}
...
}
Par conséquent, vous spécifiez un masque de champ pour cette API en indiquant les champs de l'objet Place que vous souhaitez renvoyer:
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
appel gRPC
Pour gRPC, définissez une variable contenant le masque de champ de réponse. Vous pouvez ensuite transmettre cette variable à la requête.
const ( fieldMask = "places.formattedAddress,places.displayName" )
Remarques concernant les chemins d'accès aux champs
Incluez uniquement les champs dont vous avez besoin dans la réponse. Renvoyez uniquement les champs dont vous avez besoin:
- Diminue les temps de traitement pour que vos résultats soient renvoyés avec une latence plus faible.
- Garantit des performances de latence stables si l'API ajoute des champs de réponse supplémentaires à l'avenir, et que ces nouveaux champs nécessitent du temps de calcul supplémentaire. Si vous sélectionnez tous les champs ou tous les champs au niveau supérieur, vous risquez de constater une dégradation des performances lorsque tous les nouveaux champs sont automatiquement inclus dans votre réponse.
- La taille des réponses est réduite, ce qui se traduit par un débit réseau plus élevé.
- Elle garantit que vous ne demandez pas de données inutiles, ce qui permet d'éviter des temps de traitement inutiles et des frais facturés.