選擇要傳回的資訊
呼叫方法來計算路線或路線矩陣時,您必須列出回應中要傳回的欄位,藉此指定所需資訊。系統不會傳回預設欄位清單。如果省略這個清單,方法會傳回錯誤。
您可以建立回應欄位遮罩來指定欄位清單。接著,您可以使用網址參數 $fields
或 fields
,或使用 HTTP 或 gRPC 標頭 X-Goog-FieldMask
,將回應欄位遮罩傳遞至任一方法。
使用欄位遮罩是良好的設計做法,可確保您不會要求不必要的資料,進而避免不必要的處理時間和帳單費用。
如要進一步瞭解網址參數,請參閱「系統參數」。
定義回應欄位遮罩
回應欄位遮罩是以逗號分隔的路徑清單,其中每個路徑會指定回應訊息中的專屬欄位。路徑會從頂層回應訊息開始,並使用以點號分隔的路徑指向指定欄位。
建構並指定欄位路徑,如下所示:
- 在 Routes API 中找出包含所需資訊的欄位。詳情請參閱「欄位參照」。
- 判斷所需欄位的路徑,並為這些欄位建構欄位遮罩:詳情請參閱「決定要使用的欄位遮罩」。
將所有需要的欄位結合成欄位遮罩,並以半形逗號分隔欄位遮罩。舉例來說,如要要求路線路段的
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 參考資料。請按照參考資料所示,以駝峰式大小寫指定欄位。例如 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 呼叫
在第一個範例中,您會使用對 computeRoutes
方法的 REST 呼叫來計算路線。在本範例中,您會在標頭中指定欄位遮罩,以便在回應中傳回路線 distanceMeters
和 duration
欄位。請記得在欄位名稱前方加上 routes
。
X-Goog-FieldMask: routes.distanceMeters,routes.duration
對 computeRouteMatrix
的 REST 呼叫
針對用於計算路線矩陣的 REST computeRouteMatrix
方法,請在標頭中指定針對每個起點和目的地組合,傳回 originIndex
、destinationIndex
和 duration
:
X-Goog-FieldMask: originIndex,destinationIndex,duration
gRPC 呼叫
針對 gRPC,請設定包含回應欄位遮罩的變數。接著,您可以將該變數傳遞至要求。
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
欄位路徑注意事項
請只在回應中加入所需欄位,以便只傳回所需欄位:
- 縮短處理時間,讓結果的回傳延遲時間縮短。
- 確保穩定的延遲效能。如果您選取所有欄位,或選取頂層的所有欄位,當系統新增欄位並自動納入回應時,您可能會遇到效能下降的情形。
- 產生較小的回應大小,進而提高網路處理量。
- 確保您不會要求不必要的資料,以免產生不必要的處理時間和帳單費用。
如要進一步瞭解如何建構欄位遮罩,請參閱 field_mask.proto。
要求路線權杖
如要要求 Routes API 傳回產生路線的路線權杖,請按照下列步驟操作:
- 設定下列參數,以便傳回路徑權杖:
- 將
travelMode
設為DRIVE
。 - 將
routingPreference
設為TRAFFIC_AWARE
或TRAFFIC_AWARE_OPTIMAL
。
- 將
- 確認路線的所有路標都不是
via
路標。 - 指定
routes.routeToken
欄位遮罩,以便傳回路徑權杖:X-Goog-FieldMask: routes.routeToken
您可以在 Navigation SDK 中使用路線憑證,為所規劃的路線進行規劃。詳情請參閱「規劃路線 (Android)」或「規劃路線 (iOS)」。
路徑符記範例
以下是單一起點、單一目的地路線的 cURL 要求主體範例,使用欄位遮罩來要求路線符記,以及路線時間、距離和路線多邊形:
curl -X POST -d {"origin":{ "location": { "latLng":{ "latitude": -37.8167, "longitude": 144.9619 } } }, "destination":{ "location": { "latLng":{ "latitude":-37.8155, "longitude": 144.9663 } } }, "routingPreference":"TRAFFIC_AWARE", "travelMode":"DRIVE" } -H 'X-Goog-Api-Key: YOUR_API_KEY' \ -H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
詳情請參閱 Compute Routes API 參考資料。