選擇要傳回的資訊

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

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

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

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

定義回應欄位遮罩

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

按照下列方式建構欄位路徑：

topLevelField[.secondLevelField][.thirdLevelField][...]

注意：請勿在欄位路徑清單的任何位置使用空格。

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

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

決定要使用的欄位遮罩

以下說明如何判斷要使用的欄位遮罩：

1. 使用 * 的欄位遮罩要求所有欄位。
   注意：雖然這個萬用字元欄位遮罩可用於開發中，但請勿在實際工作環境中使用萬用字元 (*) 回應欄位遮罩。費用可能高於預期，因為透過這個欄位遮罩要求更多進階功能，且會增加回應延遲時間。請確保您只要求所需的欄位，可以降低成本並要求回應時間。
2. 查看回應中欄位的階層，判斷所需的欄位。
3. 使用欄位階層建構欄位遮罩。

以大眾運輸路線中的這類部分回應為例：

 "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 日後新增更多回應欄位，且這些新欄位需要額外的運算時間，請確保維持穩定的延遲效能。如果您選取所有欄位，或是選取頂層的所有欄位，當所有新欄位自動納入回應中時，效能可能會降低。
• 以較小的回應大小產生結果，這樣會轉譯成較高的網路處理量。
• 確保不要要求不必要的資料，避免不必要的處理時間和計費費用。

注意：當回應訊息經過剖析，且回應訊息中的欄位包含其預設值時，即使您在回應欄位遮罩中指定該欄位，回應中仍可能省略該欄位。詳情請參閱語言指南 (proto3)。舉例來說，在您計算路徑矩陣時，回應的 distanceMeters 欄位可包含 0 值，也就是預設值。由於 0 是 distanceMeters 的預設值，因此回應中會省略該值。

要求路徑權杖

如要要求 Routes API 傳回所產生路線的路徑權杖，請遵循傳迴路線權杖的相關規定，然後使用 routes.route_token 欄位遮罩要求權杖：

1. 將 travel_mode 設為 DRIVING。
2. 將 routing_preference 設為 TRAFFIC_AWARE 或 TRAFFIC_AWARE_OPTIMAL。
3. 確認所有路線的路線控點皆為 via 路線控點。
4. 指定路徑權杖欄位遮罩：

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