调用地点详情(新)、 附近搜索(新)或 文本搜索(新)方法时,您必须指定要在响应中返回哪些字段。没有默认的已返回字段列表。如果省略此列表,这些方法会返回错误。
您可以通过创建响应字段掩码来指定字段列表。然后,您可以使用参数 $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 将来会添加更多响应字段,并且这些新字段需要额外的计算时间,则可以确保稳定的延迟性能。如果您选择所有字段,或者选择顶级所有字段,那么当所有新字段都自动包含在响应中时,性能可能会降低。
- 响应大小更小,这意味着网络吞吐量更高。
- 确保您不会请求不必要的数据,这有助于避免不必要的处理时间和计费费用。