选择要返回的字段

当您调用地点详情 (新) 附近搜索 (新) 文本搜索 (新)方法,您必须 指定您希望在响应中返回的字段。没有默认列表 所有返回的字段。如果省略此列表,这些方法会返回错误。

您可以通过创建响应字段掩码来指定字段列表。然后,您将传递 使用参数 $fieldsfields,或者使用 HTTP 或 gRPC 标头 X-Goog-FieldMask

字段遮盖是一种很好的设计做法,可确保您 不必要的数据,这有助于避免不必要的处理时间和费用 费用。

定义响应字段掩码

响应字段掩码是以英文逗号分隔的路径列表,其中每个路径 用于指定响应消息中的唯一字段。路径从 顶级响应消息,并使用以英文句点分隔的路径,指向指定字段。

按如下所示构造字段路径:

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

您可以使用字段掩码 * 请求所有字段。

如需详细了解如何构建字段掩码,请参阅 field_mask.proto.

确定要使用的字段掩码

下面介绍了如何确定要使用的字段掩码:

  1. 使用字段掩码“*”请求所有字段。
  2. 查看响应中字段的层次结构,并确定 字段。
  3. 使用字段层次结构构建字段掩码。

为附近搜索(新)和文本搜索(新)定义响应字段掩码

附近搜索(新)和 文本搜索(新)会在以下位置返回一组地点对象: 响应的 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][...]

如果您只想返回 formattedAddressdisplayName 字段,请将 字段掩码设为:

places.formattedAddress,places.displayName

指定 displayName 包括 textlanguage 字段 displayName。如果您只需要 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 对象:

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 添加更多响应字段时,确保稳定的延迟时间性能 这些新字段需要额外的计算时间。如果您 也可以选择所有字段;如果您选择顶级的所有字段, 所有新字段都会出现性能下降 自动包含在回复中
  • 减小响应大小,从而增加网络容量 吞吐量。
  • 确保您不会请求不必要的数据,这有助于避免 不必要的处理时间和已出账单费用。