呼叫 Place Details (New)、 Nearby Search (New) 或 Text Search (New) 方法時,必須指定要在回應中傳回的欄位。沒有傳回欄位的預設清單。如果省略這份清單,這些方法會傳回錯誤。
您可以藉由建立回應欄位遮罩來指定欄位清單。然後使用 $fields
或 fields
參數或使用 HTTP 或 gRPC 標頭 X-Goog-FieldMask
,將回應欄位遮罩傳遞至任一方法。
欄位遮蓋是不錯的設計做法,可確保您不會要求不必要的資料,避免不必要的處理時間和帳單費用。
定義回應欄位遮罩
回應欄位遮罩是以半形逗號分隔的路徑清單,其中每個路徑都會指定回應訊息中的不重複欄位。這個路徑會從頂層回應訊息開始,並使用以點分隔的路徑指向指定欄位。
按照下列方式建構欄位路徑:
topLevelField[.secondLevelField][.thirdLevelField][...]
您可以使用 *
欄位遮罩來要求所有欄位。
如要進一步瞭解如何建構欄位遮罩,請參閱 field_mask.proto。
決定要使用的欄位遮罩
以下說明如何判斷要使用的欄位遮罩:
- 要求使用「*」欄位遮罩的所有欄位。
- 查看回應中欄位的階層,判斷所需的欄位。
- 使用欄位階層建構欄位遮罩。
定義 Nearby Search (新版) 和 Text Search (新版) 的回應欄位遮罩
Nearby Search (New) 和 Text Search (New) 會在回應的 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 (New) 呼叫的完整回應物件格式如下:
{ "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 會以下列格式傳回單一 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 日後新增更多回應欄位,且這些新欄位需要額外的運算時間,請確保維持穩定的延遲效能。如果您選取所有欄位,或是選取頂層的所有欄位,當所有新欄位自動納入回應中時,效能可能會降低。
- 以較小的回應大小產生結果,這樣會轉譯成較高的網路處理量。
- 確保不要要求不必要的資料,避免不必要的處理時間和計費費用。