選擇要傳回的資訊
當您呼叫方法來計算路徑或計算路徑矩陣時,必須指定要在回應中傳回的欄位,以指定您所需的資訊。沒有任何傳回欄位的預設清單。如果省略這份清單,方法會傳回錯誤。
如要指定欄位清單,請建立回應欄位遮罩。接著,您可以使用網址參數 $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 參考資料。