选择要返回的字段

欧洲经济区 (EEA) 开发者

发出地理编码请求时，您可以使用字段掩码来指定要在响应中返回的字段列表。默认情况下，请求会在响应对象中返回所有字段。

使用字段掩码可确保您不会请求不必要的数据，这有助于缩短响应延迟时间。

定义响应字段掩码

响应字段掩码是以英文逗号分隔的路径列表，不含空格，其中每个路径都指定了响应对象中的一个唯一字段。路径从顶级响应字段开始，并使用以点分隔的路径指向指定字段。

使用网址参数 $fields 或 fields，或者使用 HTTP 或 gRPC 标头 X-Goog-FieldMask，将响应字段掩码传递给请求。

字段掩码示例

下面显示了正向地理编码请求的完整响应：

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    ...
}

使用响应字段的层次结构构建字段掩码，格式如下：

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

例如，如需仅返回响应中的 placeId 字段，请使用以下字段掩码：

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://"geocode.googleapis.com/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

现在的回答是：

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE"
    }
  ]
}

如需返回 viewport 字段，您的字段掩码应为：

-H 'X-Goog-FieldMask: results.viewport'

现在的回答是：

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

退回两者：

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

现在的回答是：

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

gRPC 字段掩码

对于 gRPC，请设置一个包含响应字段掩码的变量。然后，您可以将该变量传递给请求。

const (
  fieldMask = "results.placeId,results.viewport"
)

字段路径注意事项

仅在响应中包含您需要的字段，以便仅返回您需要的字段：

  • 缩短处理时间，从而以更低的延迟时间返回结果。
  • 确保稳定的延迟性能。如果您选择所有字段，或者选择顶级的所有字段，那么在添加新字段并自动将其纳入响应中时，您可能会遇到性能下降的问题。
  • 可缩小响应大小，从而提高网络吞吐量。

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