選擇要傳回的欄位

要求路徑或路徑矩陣時，您必須使用欄位遮罩指定回應應傳回的資訊。系統不會預設傳回任何欄位。如未指定欄位遮罩，方法會傳回錯誤。

使用欄位遮罩也能確保您不會要求不必要的資料，進而縮短回應延遲時間，並避免傳回系統不需要的資訊。

您可以在回應欄位遮罩中指定所需欄位清單。接著，使用網址參數 $fields 或 fields，或使用 HTTP 或 gRPC 標頭 X-Goog-FieldMask，將回應欄位遮罩傳遞至任一方法。

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

定義回應欄位遮罩

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

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

1. 找出含有所需資訊的欄位。詳情請參閱「欄位參照」。
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 Compute Routes 或 Compute Route Matrix 參考資料。以駝峰式大小寫指定欄位，如參考資料所示。例如 routePreference。

這些參照包括可用的欄位，但您需要參照欄位階層，才能判斷完整的欄位遮罩路徑。如要瞭解如何取得欄位階層，請參閱「決定要使用的欄位遮罩」。

• 計算路徑欄位遮罩
  • REST：指定要傳回的回應中 Route 物件的欄位，並以 routes. 為前置字元，例如 routes.distanceMeters。
  • gRPC：指定要傳回的回應中 Route 物件的欄位。
• 計算路線矩陣欄位遮罩
  • REST：指定要傳回的回應主體欄位。
  • gRPC：指定要傳回的回應中 RouteMatrixElement 物件的欄位。

決定要使用的欄位遮罩

以下說明如何判斷要使用的欄位，並為這些欄位建構欄位遮罩：

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。