选择要返回的字段

欧洲经济区 (EEA) 开发者

简介

调用 “地点详情（新）”、 “附近搜索（新）”、 或“文本搜索（新）” 方法时，您必须指定要在响应中返回的字段。没有返回字段的默认列表。如果您省略此列表，这些方法会返回错误。

如需查看支持的数据字段及其相应 SKU 的完整列表，请参阅 地点数据字段 （新）。如需了解特定于每个 API 的字段，请参阅以下内容：

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

使用字段掩码是一种良好的设计做法，可确保您不会请求不必要的数据，这有助于避免产生不必要的处理时间和结算费用。

定义响应字段掩码

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

按如下方式构建字段路径：

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

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

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

确定要使用的字段掩码

您可以按如下方式确定要使用的字段掩码：

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

为“附近搜索（新）”和“文本搜索（新）”定义响应字段掩码

“附近搜索（新）”和“文本搜索（新）”会在响应的 places 字段中返回 Place 对象数组。对于这些 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

为“地点详情（新）”定义响应字段掩码

“地点详情（新）”会返回单个 Place 对象，其形式如下：

{
  "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 将来添加更多响应字段，并且这些新字段需要额外的计算时间）。如果您选择所有字段，或者在顶级选择所有字段，则当所有新字段自动包含在响应中时，您可能会遇到性能下降的情况。
  • 缩小响应大小，从而提高网络 吞吐量。
  • 确保您不会请求不必要的数据，这有助于避免 不必要的处理时间和结算费用。