呼叫 Place Details 時 (新增)、 搜尋附近 (新增)，或 文字搜尋 (新版) 方法，您就必須 指定要在回應中傳回的欄位。系統沒有傳回欄位的預設清單。如果省略這份清單，方法會傳回錯誤。
如要指定欄位清單，請建立回應欄位遮罩。接著，您可以使用參數 $fields 或 fields，或使用 HTTP 或 gRPC 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至任一方法。
欄位遮蓋是不錯的設計做法，可確保您不要要求這些要求 不必要的資料，以避免產生不必要的處理時間和計費 費用。
定義回應欄位遮罩
回應欄位遮罩是以逗號分隔的路徑清單，每個路徑會指定回應訊息中的專屬欄位。路徑會從頂層回應訊息開始，並使用以點分隔的路徑指向指定欄位。
建構欄位路徑如下：
topLevelField[.secondLevelField][.thirdLevelField][...]
您可以使用 * 的欄位遮罩來要求所有欄位。
如要進一步瞭解如何建構欄位遮罩，請參閱 field_mask.proto。
決定要使用的欄位遮罩
以下說明如何決定要使用的欄位遮罩：
- 使用 `*` 的欄位遮罩要求所有欄位。
- 查看回應中各欄位的階層 選取需要的欄位
- 使用欄位階層建立欄位遮罩。
為 Nearby Search (新版) 和 Text Search (新版) 定義回應欄位遮罩
Nearby Search (新版) 和
Text Search (新版) 會傳回
回應的 places 欄位。針對這些 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 會包含以下項目的 text 和 language 欄位：
displayName。如果只想使用 text 欄位，請將欄位遮罩設為：
places.formattedAddress,places.displayName.text
定義 Place Details (新版) 的回應欄位遮罩
Place Details 會以下列形式傳回單一 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 日後新增更多回應欄位，且這些新欄位需要額外的運算時間，則可確保穩定的延遲效能。如果您選取所有欄位，或選取頂層的所有欄位，當所有新欄位自動納入回應時，您可能會遇到效能降低的情形。
- 產生較小的回應大小，進而提高網路處理量。
- 確保未要求不必要的資料，避免 不必要的處理時間及計費