選擇要傳回的欄位

歐洲經濟區 (EEA) 開發人員

提出地理編碼要求時，您可以使用欄位遮罩指定要在回應中傳回的欄位清單。對於「對地址進行地理編碼」、「對地點進行地理編碼」和「地點地理編碼」端點，系統預設會傳回回應物件中的所有欄位。如要使用搜尋目的地端點，您必須在 API 要求中指定欄位遮罩。

使用欄位遮罩，確保您不會要求不必要的資料，進而縮短回應延遲時間。

定義回應欄位遮罩

回應欄位遮罩是以逗號分隔的路徑清單，不得包含空格，每個路徑都會指定回應物件中的專屬欄位。路徑從頂層回應欄位開始，並使用以半形句號分隔的路徑，指向指定欄位。

使用網址參數 $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。