選擇要傳回的資訊

呼叫方法來計算路徑或路徑矩陣時， 您必須先列出要填入資訊的欄位 傳回的字串。沒有預設的傳回欄位清單。如果省略這份清單，方法會傳回錯誤。

如要指定欄位清單，請建立回應欄位遮罩。接著您 使用網址參數 $fields 或 fields，或是 HTTP 或 gRPC 標頭 X-Goog-FieldMask。

使用欄位遮罩是不錯的設計做法，可確保您不會在要求的情況下要求 不需要資料，進而避免不必要的處理時間並產生帳單費用。

如要進一步瞭解網址參數，請參閱： 系統參數：

定義回應欄位遮罩

回應欄位遮罩是以半形逗號分隔的路徑清單，其中每個路徑 path 會指定回應訊息中的唯一欄位。 路徑從頂層回應訊息開始，並使用 以半形句號分隔的指定欄位路徑。

建構並指定欄位路徑，如下所示：

  1. 從 Routes API 找出包含所需資訊的欄位。詳情請參閱欄位參照一節。
  2. 決定所需欄位的路徑，並為其建構欄位遮罩：詳情請參閱「決定您要使用的欄位遮罩」一文。

  3. 將需要的所有欄位遮罩合併成欄位遮罩，並以半形逗號分隔欄位遮罩。舉例來說，如要要求路線路段的 distanceMeters，以及每個路線路段的所需時間，請輸入這兩個路段，並以半形逗號分隔，中間不留空格：

    routes.legs.distanceMeters,routes.legs.steps.duration

  4. 使用 API 要求傳送欄位遮罩。例如，在 cURL 要求中，您會使用 -H 和 X-Goog-FieldMask 指定欄位遮罩：

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

欄位參照

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

這些參照包含可用欄位；然而，如要判斷完整欄位遮罩路徑，請參閱欄位階層。如要進一步瞭解如何取得欄位階層，請參閱「決定您要使用的欄位遮罩」一文。

  • 運算路徑欄位遮罩
    • REST：指定 Route 物件位於 傳回的回應，並在前面加上 routes.，例如 routes.distanceMeters。
    • gRPC：指定 Route 物件位於 回應。
  • 運算路徑矩陣欄位遮罩

決定要使用的欄位遮罩

以下說明如何決定要使用哪些欄位，以及如何為這些欄位建構欄位遮罩：

  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 呼叫

在第一個範例中，您可使用 REST 呼叫，對 computeRoutes 方法，計算費用 特定路徑在這個範例中，您在標頭中指定欄位遮罩，以在回應中傳迴路徑 distanceMeters 和 duration 欄位。請記得在欄位名稱前面加上 routes。

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

對 computeRouteMatrix 發出的 REST 呼叫

針對 REST computeRouteMatrix 計算路徑矩陣的方法，在 標頭中指定要傳回 originIndex、destinationIndex 和 duration 每個來源組合 以及目的地：

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_AWARE 或 TRAFFIC_AWARE_OPTIMAL。
  2. 檢查您的路線控點是否不是 via 個路線控點。
  3. 指定 routes.routeToken 欄位遮罩以傳迴路徑權杖： 
    X-Goog-FieldMask: routes.routeToken

您可以在 Navigation SDK 中使用規劃路徑的路徑權杖。詳情請參閱 規劃路線 (Android) 或規劃路線 (iOS)。

路徑權杖範例

下方是單一來源 (單一目的地) 的 cURL 要求主體 route，使用欄位遮罩要求路線符記和路徑 所需時間、距離和路線折線：

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 參考資料。