選擇要傳回的資訊

呼叫方法來計算路線或路線矩陣時,您必須列出回應中要傳回的欄位,藉此指定所需資訊。系統不會傳回預設欄位清單。如果省略這個清單,方法會傳回錯誤。

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

使用欄位遮罩是良好的設計做法,可確保您不會要求不必要的資料,進而避免不必要的處理時間和帳單費用。

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

定義回應欄位遮罩

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

建構並指定欄位路徑,如下所示:

  1. 在 Routes API 中找出包含所需資訊的欄位。詳情請參閱「欄位參照」。
  2. 判斷所需欄位的路徑,並為這些欄位建構欄位遮罩:詳情請參閱「決定要使用的欄位遮罩」。
  3. 將所有需要的欄位結合成欄位遮罩,並以半形逗號分隔欄位遮罩。舉例來說,如要要求路線路段的 distanceMeters,以及每個路線路段步驟的時間長度,請輸入這兩項資訊,並以半形逗號分隔,且不要加入空格:

    routes.legs.distanceMeters,routes.legs.steps.duration
  4. 透過 API 要求傳送欄位遮罩。例如,在 cURL 要求中,您可以使用 -HX-Goog-FieldMask 指定欄位遮罩:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
如需示例和更多詳細資訊,請參閱下列各節。

欄位參照

如要查看可透過欄位遮罩在回應中要求的欄位,請參閱下列清單中連結的 Routes API 參考資料。請按照參考資料所示,以駝峰式大小寫指定欄位。例如 routePreference

這些參照資料包含可用的欄位,但您必須參照欄位的階層,才能判斷完整的欄位遮罩路徑。如要進一步瞭解如何取得欄位階層,請參閱「決定要使用的欄位遮罩」一文。

  • 計算路徑欄位遮罩
    • REST:指定要傳回的回應中 Route 物件的欄位,前面加上 routes.,例如 routes.distanceMeters
    • gRPC:指定要傳回的回應中 Route 物件的欄位。
  • Compute Route Matrix 欄位遮罩

決定要使用的欄位遮罩

以下說明如何判斷要使用哪些欄位,並為這些欄位建構欄位遮罩:

  1. 使用 * 欄位遮罩要求所有欄位
  2. 查看所需欄位的回應中欄位的層級
  3. 使用上一個步驟顯示的欄位階層,以以下格式建構欄位遮罩

    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 呼叫來計算路線。在本範例中,您會在標頭中指定欄位遮罩,以便在回應中傳回路線 distanceMetersduration 欄位。請記得在欄位名稱前方加上 routes

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

computeRouteMatrix 的 REST 呼叫

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

X-Goog-FieldMask: originIndex,destinationIndex,duration

gRPC 呼叫

針對 gRPC,請設定包含回應欄位遮罩的變數。接著,您可以將該變數傳遞至要求。

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

欄位路徑注意事項

請只在回應中加入所需欄位,以便只傳回所需欄位:

  • 縮短處理時間,讓結果的回傳延遲時間縮短。
  • 確保穩定的延遲效能。如果您選取所有欄位,或選取頂層的所有欄位,當系統新增欄位並自動納入回應時,您可能會遇到效能下降的情形。
  • 產生較小的回應大小,進而提高網路處理量。
  • 確保您不會要求不必要的資料,以免產生不必要的處理時間和帳單費用。

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

要求路線權杖

如要要求 Routes API 傳回產生路線的路線權杖,請按照下列步驟操作:

  1. 設定下列參數,以便傳回路徑權杖:
    • travelMode 設為 DRIVE
    • routingPreference 設為 TRAFFIC_AWARETRAFFIC_AWARE_OPTIMAL
  2. 確認路線的所有路標都不是 via 路標。
  3. 指定 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 參考資料