選擇要傳回的資訊
呼叫方法計算路徑或計算路徑矩陣時,您必須指定要在回應中傳回的欄位,藉此指定所需的資訊。沒有傳回欄位的預設清單。如果省略這份清單,這些方法會傳回錯誤。
您可以藉由建立回應欄位遮罩來指定欄位清單。然後使用網址參數 $fields
或 fields
,或使用 HTTP 或 gRPC 標頭 X-Goog-FieldMask
,將回應欄位遮罩傳遞至任一方法。
欄位遮蓋是不錯的設計做法,可確保您不會要求不必要的資料,避免不必要的處理時間和計費費用。
如要進一步瞭解網址參數,請參閱系統參數一文。
定義回應欄位遮罩
回應欄位遮罩是以半形逗號分隔的路徑清單,每個路徑都會在回應訊息中指定不重複欄位。路徑會從頂層回應訊息開始,並使用以點分隔的路徑指向指定欄位。
按照下列方式建構欄位路徑:
topLevelField[.secondLevelField][.thirdLevelField][...]
- 運算路徑欄位遮罩
- 運算路徑矩陣欄位遮罩
- REST:指定要傳回的回應主體欄位。
- gRPC:指定要傳回的回應中 RouteMatrixElement 物件的欄位。
如要進一步瞭解如何建構欄位遮罩,請參閱 field_mask.proto。
決定要使用的欄位遮罩
以下說明如何判斷要使用的欄位遮罩:
- 使用
*
的欄位遮罩要求所有欄位。 - 查看回應中欄位的階層,判斷所需的欄位。
- 使用欄位階層建構欄位遮罩。
以大眾運輸路線中的這類部分回應為例:
"routes": [ { "legs": [ { "distanceMeters": 12886, } ... ]}]
如果只要傳回 distanceMeters
欄位,欄位遮罩會是:
routes.legs.distanceMeters
另一個範例:如要傳回回應中 legs
下的所有內容,欄位遮罩如下:
routes.legs
指定欄位路徑
本節舉例說明如何將欄位路徑指定為回應欄位遮罩的一部分。
對 computeRoutes
發出的 REST 呼叫
在第一個範例中,您針對 computeRoutes
方法使用 REST 呼叫來計算路徑。在這個範例中,您會在標頭中指定欄位遮罩,以在回應中傳回 Route.distanceMeters
和 Route.duration
欄位。請記得在欄位名稱前面加上 routes
。
-H X-Goog-FieldMask: routes.distanceMeters,routes.duration
對 computeRouteMatrix
發出的 REST 呼叫
針對用於計算路徑矩陣的 REST computeRouteMatrix
方法,請在標頭中指定為各個起點和目的地的組合傳回 originIndex
、destinationIndex
和 duration
:
-H X-Goog-FieldMask: originIndex,destinationIndex,duration
gRPC 呼叫
針對 gRPC,設定包含回應欄位遮罩的變數。然後再將變數傳送至要求。
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
欄位路徑注意事項
只在回應中加入需要的欄位。只傳回所需欄位:
- 縮短處理時間,縮短傳回結果的延遲時間。
- 如果 API 日後新增更多回應欄位,且這些新欄位需要額外的運算時間,請確保維持穩定的延遲效能。如果您選取所有欄位,或是選取頂層的所有欄位,當所有新欄位自動納入回應中時,效能可能會降低。
- 以較小的回應大小產生結果,這樣會轉譯成較高的網路處理量。
- 確保不要要求不必要的資料,避免不必要的處理時間和計費費用。
要求路徑權杖
如要要求 Routes API 傳回所產生路線的路徑權杖,請遵循傳迴路線權杖的相關規定,然後使用 routes.route_token
欄位遮罩要求權杖:
- 將
travel_mode
設為DRIVING
。 - 將
routing_preference
設為TRAFFIC_AWARE
或TRAFFIC_AWARE_OPTIMAL
。 - 確認所有路線的路線控點皆為
via
路線控點。 - 指定路徑權杖欄位遮罩:
-H X-Goog-FieldMask: routes.route_token
你可以在 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.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
詳情請參閱 Compute Routes API 參考資料。