選擇要傳回的資訊

呼叫計算路徑或計算路徑矩陣的方法時,您必須指定要在回應中傳回的欄位以指定需要的資訊。沒有傳回欄位的預設清單。如果省略這份清單,方法會傳回錯誤。

您可以建立「回應欄位遮罩」來指定欄位清單。接著,請使用網址參數 $fieldsfields,或使用 HTTP 或 gRPC 標頭 X-Goog-FieldMask,將回應欄位遮罩傳送至任一方法。

欄位遮蓋是不錯的設計做法,可確保您不會要求不必要的資料,以避免不必要的處理時間及產生費用。

如要進一步瞭解網址參數,請參閱系統參數一文。

定義回應欄位遮罩

回應欄位遮罩是以半形逗號分隔的路徑清單,其中每個路徑都會在回應訊息中指定不重複的欄位。路徑會從頂層回應訊息開始,並使用以點分隔的路徑指向指定欄位。

依照下列方式建構欄位路徑:

topLevelField[.secondLevelField][.thirdLevelField][...]
  • 運算路徑欄位遮罩
    • REST:在要傳回的回應中指定 Route 物件的欄位,前面加上 routes.,例如 routes.distanceMeters
    • gRPC:在要傳回的回應中指定 Route 物件的欄位。
  • 計算路徑矩陣欄位遮罩

如要進一步瞭解如何建構欄位遮罩,請參閱 field_mask.proto

決定要使用的欄位遮罩

以下說明如何決定要使用的欄位遮罩:

  1. 使用 * 欄位遮罩要求所有欄位。
  2. 請查看回應中的欄位階層,並決定您需要的欄位。
  3. 使用欄位階層結構建構欄位遮罩。

舉例來說,如果是來自大眾運輸路線的部分回應:

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

如果您只想傳回 distanceMeters 欄位,欄位遮罩如下:

routes.legs.distanceMeters

另一個範例:如要在回應中傳回 legs 底下的所有內容,您的欄位遮罩如下:

routes.legs

指定欄位路徑

本節舉例說明如何將欄位路徑指定為回應欄位遮罩的一部分。

向「computeRoutes」發出 REST 呼叫

在第一個範例中,您會對 computeRoutes 方法使用 REST 呼叫來計算路徑。在本範例中,您在標頭中指定欄位遮罩,以便在回應中傳回 Route.distanceMetersRoute.duration 欄位。記得在欄位名稱前方加上 routes

-H X-Goog-FieldMask: routes.distanceMeters,routes.duration

向「computeRouteMatrix」發出 REST 呼叫

針對用於計算路徑矩陣的 REST computeRouteMatrix 方法,指定在標頭中為每個起點和目的地組合傳回 originIndexdestinationIndexduration

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC 呼叫

如果是 gRPC,請設定包含回應欄位遮罩的變數。然後將這個變數傳遞至要求。

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

欄位路徑注意事項

僅加入回應中所需的欄位。僅傳回您需要的欄位:

  • 減少處理時間,因此傳回結果的延遲時間較短。
  • 如果 API 日後會新增更多回應欄位,且這些新欄位需要更多運算時間,請確保延遲時間穩定。如果您選取所有欄位,或是選取頂層的所有欄位,則當所有新欄位自動加入回應時,效能可能會降低。
  • 產出的回應大小會較小,因此網路處理量會提高。
  • 確保您不會要求不必要的資料,以免產生不必要的處理時間和計費費用。

要求路徑權杖

如要要求 Routes API 針對產生的路徑傳迴路徑權杖,請遵循傳迴路徑符記的要求,然後使用 routes.route_token 欄位遮罩來要求權杖:

  1. travel_mode 設為 DRIVING
  2. routing_preference 設為 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL
  3. 確認所有路線的路線控點皆不是 via 路線控點。
  4. 指定路徑權杖欄位遮罩:
    -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 參考資料