選擇要傳回的欄位
要求路線或路線矩陣時,您必須使用欄位遮罩,指定回應應傳回哪些資訊。系統沒有預設的傳回欄位清單。如未指定欄位遮罩,方法會傳回錯誤。
使用欄位遮罩也能確保您不會要求不必要的資料,進而縮短回應延遲時間,並避免傳回系統不需要的資訊。
您可以在回應欄位遮罩中指定所需欄位清單。接著,您可以使用網址參數 $fields 或 fields,或使用 HTTP 或 gRPC 標頭 X-Goog-FieldMask,將回應欄位遮罩傳遞至任一方法。
如要進一步瞭解網址參數,請參閱「系統參數」。
定義回應欄位遮罩
回應欄位遮罩是以逗號分隔的清單,每個路徑都會指定回應訊息中的專屬欄位。路徑從頂層回應訊息開始,並使用以點分隔的路徑指向指定欄位。
建構並指定欄位路徑,如下所示:
- 找出含有所需資訊的欄位。詳情請參閱「欄位參考資料」。
- 判斷所需欄位的路徑,並為這些欄位建構欄位遮罩:詳情請參閱「判斷要使用的欄位遮罩」。
合併所需欄位的欄位遮罩,並以半形逗號分隔。舉例來說,如要要求路線路段的
distanceMeters,以及每個路線路段步驟的持續時間,請輸入這兩項資訊,並以半形逗號分隔,不加空格:routes.legs.distanceMeters,routes.legs.steps.duration
將欄位遮罩與 API 要求一併傳送。舉例來說,在 curl 要求中,您可以使用
-H和X-Goog-FieldMask指定欄位遮罩:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
欄位參考資料
如要查看可透過欄位遮罩在回應中要求的欄位,請參閱下列清單中連結的 Routes API Compute Routes 或 Compute Route Matrix 參考資料。請按照參考資料所示,以駝峰式大小寫指定欄位。例如 routePreference。
這些參考資料包含可用欄位,但您必須參考欄位階層,才能判斷完整的欄位遮罩路徑。如要進一步瞭解如何取得欄位階層,請參閱「決定要使用的欄位遮罩」。
- 計算路線欄位遮罩
- Compute Route Matrix 欄位遮罩
- REST:指定要傳回的回應主體欄位。
- gRPC:指定要在回應中傳回的 RouteMatrixElement 物件欄位。
決定要使用的欄位遮罩
以下說明如何判斷要使用的欄位,並為這些欄位建構欄位遮罩:
- 使用
*欄位遮罩要求所有欄位。 - 查看回應中的欄位階層,找出所需欄位。
使用上一步顯示的欄位階層,按照下列格式建構欄位遮罩:
topLevelField[.secondLevelField][.thirdLevelField][...]
舉例來說,以下是路線的部分回應:
"routes": [ { "legs": [ { "steps": [ {"distanceMeters": 119}, {"distanceMeters": 41} ] } ], "distanceMeters": 160 } ]
如果只想傳回路線路段的 distanceMeters 欄位 (即上述範例中的最後一個 distanceMeters),欄位遮罩如下:
routes.legs.distanceMeters
如果想改為傳回路線路段中每個步驟的 distanceMeters 欄位,也就是上述範例中 steps 下方的 distanceMeters,則欄位遮罩如下:
routes.legs.steps.distanceMeters
如要同時傳回這兩項資訊,並取得上述結果,請使用下列欄位遮罩:
routes.legs.distanceMeters,routes.legs.steps.distanceMeters
欄位遮罩路徑範例
本節提供更多範例,說明如何在 REST 和 gRPC 呼叫中,指定欄位路徑做為回應欄位遮罩的一部分。
對 computeRoutes 的 REST 呼叫
在第一個範例中,您會使用 REST 呼叫 computeRoutes 方法來計算路線。在本例中,您在標頭中指定欄位遮罩,在回應中傳回路線 distanceMeters 和 duration 欄位。請記得在欄位名稱前加上 routes。
X-Goog-FieldMask: routes.distanceMeters,routes.duration
對 computeRouteMatrix 的 REST 呼叫
如果是用於計算路徑矩陣的 REST computeRouteMatrix 方法,請在標頭中指定為每個起點和目的地組合傳回 originIndex、destinationIndex 和 duration:
X-Goog-FieldMask: originIndex,destinationIndex,duration
對 computeRoutes 的 gRPC 呼叫
針對用於計算路線的 gRPC computeRoutes 方法,請設定包含回應欄位遮罩的變數,在回應中傳回路線 distanceMeters、duration 和編碼折線欄位。接著,您可以將該變數傳遞至要求:
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
對 computeRouteMatrix 的 gRPC 呼叫
針對用於計算路徑矩陣的 gRPC computeRouteMatrix 方法,設定包含回應欄位遮罩的變數,指定為每個起點和目的地組合傳回 originIndex、destinationIndex 和 duration。接著,您可以將該變數傳遞至要求:
const ( fieldMask = "originIndex,destinationIndex,duration" )
欄位路徑注意事項
在回應中只加入您需要的欄位,這樣就只會傳回您需要的欄位:
- 縮短處理時間,以更低的延遲時間傳回結果。
- 確保延遲時間效能穩定。如果選取所有欄位,或選取頂層的所有欄位,當系統新增欄位並自動納入回應時,效能可能會降低。
- 回應大小較小,因此網路處理量較高。
- 確保您不會要求不必要的資料,避免不必要的處理時間和計費費用。
如要進一步瞭解如何建構欄位遮罩,請參閱 field_mask.proto。