選擇要傳回的資訊
呼叫計算路徑或計算路徑矩陣的方法時,您必須指定要在回應中傳回的欄位以指定需要的資訊。沒有傳回欄位的預設清單。如果省略這份清單,方法會傳回錯誤。
您可以建立「回應欄位遮罩」來指定欄位清單。接著,請使用網址參數 $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)。
路徑權杖範例
以下是單一起點、單一目的地路徑的要求主體,並使用欄位遮罩要求路徑符記,以及路線持續時間、距離和路線折線:
terminal 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-FieldMask: routes.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline 'https://routes.googleapis.com/directions/v2:computeRoutes'
詳情請參閱 Compute Routes API 參考資料。