当您调用地点详情(新)、 附近搜索(新)或 文本搜索(新)方法时,必须指定您希望在响应中返回的字段。没有默认的返回字段列表。如果省略此列表,这些方法会返回错误。
您可以通过创建响应字段掩码来指定字段列表。然后,您可以使用参数 $fields
或 fields
或者使用 HTTP 或 gRPC 标头 X-Goog-FieldMask
将响应字段掩码传递给任一方法。
字段遮盖是一种很好的设计做法,可确保您不会请求不必要的数据,这有助于避免不必要的处理时间和结算费用。
定义响应字段掩码
响应字段掩码是以英文逗号分隔的路径列表,其中每个路径都指定了响应消息中的唯一字段。该路径从顶级响应消息开始,并使用以英文句点分隔的路径到指定字段。
按如下所示构造字段路径:
topLevelField[.secondLevelField][.thirdLevelField][...]
您可以使用字段掩码 *
请求所有字段。
如需详细了解如何构建字段掩码,请参阅 field_mask.proto。
确定要使用的字段掩码
下面介绍了如何确定要使用的字段掩码:
- 使用字段掩码“*”请求所有字段。
- 查看响应中字段的层次结构并确定所需的字段。
- 使用字段层次结构构建字段掩码。
为附近搜索(新)和文本搜索(新)定义响应字段掩码
附近搜索(新)和文本搜索(新)会在响应的 places
字段中返回一组地点对象。对于这些 API,places
是响应的顶级字段。
例如,如需查看文本搜索(新)的完整响应对象,请使用以下代码:
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'
“文本搜索(新)”调用的完整响应对象采用以下格式:
{ "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" }, ... }, ... ] }
因此,您应为这些 API 指定字段掩码,形式如下:
places[.secondLevelField][.thirdLevelField][...]
如果您只想返回 formattedAddress
和 displayName
字段,请将字段掩码设置为:
places.formattedAddress,places.displayName
指定 displayName
会同时包含 displayName
的 text
和 language
字段。如果您只需要 text
字段,请将字段掩码设置为:
places.formattedAddress,places.displayName.text
定义地点详情的响应字段掩码(新)
地点详情以如下形式返回单个地点对象:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "types": [ "locality", "political" ], "formattedAddress": "Trinidad, CA 95570, USA", "displayName": { "text": "Trinidad", "languageCode": "en" } ... }
因此,您可以通过指定要返回的 Place 对象的字段来为此 API 指定字段掩码:
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
gRPC 调用
对于 gRPC,请设置包含响应字段掩码的变量。然后,您可以将该变量传递给请求。
const ( fieldMask = "places.formattedAddress,places.displayName" )
字段路径注意事项
在响应中仅添加所需的字段。仅返回所需的字段:
- 缩短处理时间,从而以更低的延迟返回结果。
- 如果 API 在将来添加更多响应字段,并且这些新字段需要额外的计算时间,则可以确保稳定的延迟时间性能。如果您选择所有字段,或选择顶层的所有字段,则所有新字段都自动包含在响应中时,您可能会遇到性能下降的情况。
- 减小响应大小,从而提高网络吞吐量。
- 确保您不会请求不必要的数据,这有助于避免不必要的处理时间和已结算费用。