選擇要傳回的欄位

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

簡介

呼叫 Place Details (新版)、Nearby Search (新版) 或 Text Search (新版) 方法時，您必須指定要在回應中傳回的欄位。系統不會預設傳回任何欄位。如果省略這份清單，方法會傳回錯誤。

如需支援的資料欄位完整清單和對應的 SKU，請參閱「地點資料欄位 (新版)」。如要瞭解各 API 的專屬欄位，請參閱下列文章：

建立回應欄位遮罩即可指定欄位清單。接著，使用 $fields 或 fields 參數，或使用 HTTP 或 gRPC 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至任一方法。

欄位遮蓋是良好的設計做法，可確保您不會要求不必要的資料，有助於避免不必要的處理時間和帳單費用。

定義回應欄位遮罩

回應欄位遮罩是以逗號分隔的路徑清單，每個路徑都會指定回應主體中的專屬欄位。路徑會從頂層回應訊息開始，並使用以半形句號分隔的路徑，指向指定欄位。

建構欄位路徑，如下所示：

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

如要要求所有欄位，請使用 * 的欄位遮罩。

如要進一步瞭解如何建構欄位遮罩，請參閱 field_mask.proto。

決定要使用的欄位遮罩

以下說明如何判斷要使用的欄位遮罩：

  1. 使用 * 的欄位遮罩要求所有欄位。
  2. 查看回應中的欄位階層，然後決定要哪些欄位。
  3. 使用欄位階層建構欄位遮罩。

為 Nearby Search (新版) 和 Text Search (新版) 定義回應欄位遮罩

Nearby Search (新版) 和 Text Search (新版) 會在回應的 places 欄位中傳回 Place 物件的陣列。對於這些 API，places 是回應的頂層欄位。

舉例來說，如要查看 Text Search (新版) 的完整回應物件：

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'

Text Search (新版) 呼叫的完整回應物件格式如下：

{
  "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 Details (新版) 的回應欄位遮罩

Place Details (New) 會以以下形式傳回單一 Place 物件：

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

因此，您要指定這個 API 的欄位遮罩，方法是指定要傳回的 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 日後新增更多回應欄位，且這些新欄位需要額外的運算時間，可確保延遲效能穩定。如果您選取所有欄位，或選取頂層的所有欄位，系統可能會自動將所有新欄位納入回應，導致效能降低。
  • 縮減回應大小，進而提高網路輸送量。
  • 確保您不會要求不必要的資料，有助於避免不必要的處理時間和計費費用。