解讀回應

歐洲經濟區 (EEA) 開發人員

如果您的帳單地址位於歐洲經濟區，自 2025 年 7 月 8 日起，使用服務時將適用《 Google 地圖平台歐洲經濟區服務條款》。功能會因區域而異。 瞭解詳情。

Route Optimization API 會傳回相應要求中車輛的路線。系統會將貨件指派給車輛，或視要求屬性而定，可能會略過這項步驟。

OptimizeToursResponse 訊息 (REST、gRPC) 有兩個主要頂層屬性：

• routes[] 是指每輛車輛的路線，以及指派給該車輛的貨運。每個 Route 都包含反映該路線屬性的指標。
• metrics 是整個回應的匯總指標，涵蓋所有車輛和路線規劃。頂層指標包含與每條路線指標相同的屬性，但值是所有路線的匯總值。

系統可能會根據最佳化結果，決定是否填入某些屬性：

1. skippedShipments[] 列出未由任何車輛執行的出貨作業。 如果無法在指定限制內完成出貨，或出貨成本超過違規費用，則可以略過出貨。舉例來說，如果出貨的取貨或送達時間範圍非常狹窄 timeWindow，車輛可能無法在指定時間範圍內完成拜訪，或不符合成本效益。
2. validationErrors[] 會指定錯誤，導致要求無效或無法解決 (當要求的 solvingMode 設為 VALIDATE_ONLY 時)。在正常 DEFAULT_SOLVE 模式下，驗證錯誤會顯示在錯誤訊息中，而不是回應內文中。請注意，VALIDATE_ONLY解決模式可一次回報多個錯誤，有助於快速偵錯要求。

注意： 如要解讀回應，必須有對應的要求。回應包含對要求中實體的參照，因此難以單獨解讀。部分訊息 (例如 Shipment 和 Vehicle) 具有標籤屬性，可讓您更輕鬆地比對要求和回應資料。

路線屬性

每個 routes[] 項目都是 ShipmentRoute 訊息 (REST、gRPC)。每個 ShipmentRoute 代表要求中特定車輛的路線指派。與對應 Vehicle 相關的重要 ShipmentRoute 屬性包括：

• vehicleIndex 是對應要求訊息中 Vehicle 的索引，從零開始。如果值為零，REST 回應會省略這個屬性。
• vehicleStartTime 是車輛必須開始行駛路線的時間。
• vehicleEndTime 是車輛預計完成路線的時間。

在回覆中，routes 會顯示為：

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        ...
      ],
      "transitions": [
        ...
      ],
      "metrics": {
        ...
      },
      ...
    }
  ],
  ...
}

注意： REST 回應會使用通訊協定緩衝區的 JSON 表示法，省略具有各自類型預設值且不支援欄位存在的欄位。也就是說，如果整數屬性 (例如 vehicleIndex) 的值為零，就會遭到省略。另請參閱官方的通訊協定緩衝區 JSON 對應說明文件。

每個 ShipmentRoute 都包含車輛將完成的 visits 排序清單。每個 Visit (REST、gRPC) 都代表對應要求的 VisitRequest (REST、gRPC)。重要Visit 屬性包括：

• shipmentIndex 是這項造訪所屬出貨項目的索引，從零開始。
• 如果拜訪是取貨，則 isPickup 為 true；如果拜訪是送貨，則為 false。如果值為 false，REST 回應會省略這個屬性。
• visitRequestIndex 是 VisitRequest 的索引，從零開始，來自 Shipment.pickups 或 Shipment.deliveries 中 Visit 所代表的對應要求。如果值為零，REST 回應會省略這個屬性。
• startTime 是預計開始時間。
• loadDemands 會將地圖載入類型對應至完成 Visit 所需的載入量。送貨行程的裝載量為負數，表示從車輛卸下的裝載量。

Visit 範例如下：

{
  "routes": [
    {
      ...
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        ...
      ],
    },
    ...
  ],
  ...
}

每個 ShipmentRoute 都包含 transitions 的排序清單，代表特定車輛在 visits 之間的行程。重要的 Transition 訊息 (REST、gRPC) 屬性包括：

• startTime 是車輛開始執行轉換的時間。
• travelDuration 是車輛完成轉換所需的時間。
• travelDistanceMeters 是車輛必須行駛的距離 (以公尺為單位)，才能完成轉換。
• trafficInfoUnavailable：指出轉換是否有可用的流量資料。
• waitDuration 代表車輛等待的時間，之後才能開始下一個 Visit。這可能是因為start_time下列Visit。
• totalDuration 是指轉換的總時間長度，包括交通、等待、休息和延誤時間。
• vehicleLoads 將地圖載入類型對應至車輛在轉換期間的載入量。

Transition 範例如下：

{
  "routes": [
    {
      ...
      "transitions": [
        ...
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        ...
      ],
      ...
    }
  ],
  ...
}

如要進一步瞭解 vists 和 transitions 之間的關係，請參閱「取貨和送貨停靠點順序最佳化」和 ShipmentRoute 參考說明文件 (REST、gRPC)。如要進一步瞭解 Transition 訊息的 routePolyline 和 routeToken 屬性，請參閱「轉換折線和路線權杖」。

指標屬性

Metrics 訊息 (REST、gRPC) 總結了整個解決方案。重要 Metrics 屬性包括：

• totalCost 是完成路線所產生的總費用。如要進一步瞭解費用，請參閱「費用模型參數」。
• usedVehicleCount 是解決方案中使用的車輛總數。 如果最佳化工具判斷車輛不需要使用路線，車輛可能會沒有路線。
• skippedMandatoryShipmentCount 是「必要」的略過貨運次數。強制出貨未指定如果出貨遭略過，則會產生的 penaltyCost。如果無法在指定限制下完成強制出貨，仍可略過。如要進一步瞭解費用，請參閱「費用模型參數」。

其他指標會以 AggregatedMetrics 訊息 (REST、gRPC) 回報。AggregatedMetrics 訊息類型用於 Metrics.aggregatedRouteMetrics 屬性和 ShipmentRoute.metrics 屬性，Metrics.aggregatedRouteMetrics 包含在 OptimizeToursResponse 中所有 ShipmentRoute 匯總的指標。每個 ShipmentRoute.metrics 屬性都包含該特定 ShipmentRoute 的指標。

重要 AggregatedMetrics 屬性包括：

• performedShipmentCount 是指車輛在整個路線上執行的出貨次數。
• travelDuration 是車輛完成路線時的總行車時間。
• waitDuration 是車輛完成路線時的總等待時間。
• delayDuration 是車輛的總延遲時間。除非請求中使用 TransitionAttributes，否則這通常為零。
• breakDuration 是車輛在完成路線時的休息總時間。
• visitDuration 是車輛在完成路線時，執行拜訪作業的總時間。這實際上是所有 VisitRequest.duration值加總，這些值對應至指派給適用車輛的VisitRequests Visits。
• totalDuration 是車輛完成路線所需的總時間。
• travelDistanceMeters 是指車輛完成路線時行駛的總距離。
• maxLoads 會將負載類型對應至車輛在路線上任何一點所能承載的最大負載量。

Metrics 訊息範例如下：

{
  "routes": [
    ...
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}

重要事項： 如果 Metrics 或 ShipmentRoute 訊息中的所有費用都是零，最佳化工具可能找不到完成 Visit 的最佳順序。至少須指定一項費用參數，例如 Vehicle.costPerKilometer 或 globalDurationCostPerHour，否則最佳化工具可能會傳回任何符合指定限制的解決方案。

完整範例

建構要求的完整範例回應如下所示：

{
  "routes": [
    {
      "vehicleStartTime": "2024-02-13T00:00:00Z",
      "vehicleEndTime": "2024-02-13T00:38:42Z",
      "visits": [
        {
          "isPickup": true,
          "startTime": "2024-02-13T00:00:00Z",
          "detour": "0s"
        },
        {
          "startTime": "2024-02-13T00:19:31Z",
          "detour": "0s"
        }
      ],
      "transitions": [
        {
          "travelDuration": "0s",
          "waitDuration": "0s",
          "totalDuration": "0s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1171s",
          "travelDistanceMeters": 9004,
          "waitDuration": "0s",
          "totalDuration": "1171s",
          "startTime": "2024-02-13T00:00:00Z"
        },
        {
          "travelDuration": "1151s",
          "travelDistanceMeters": 9599,
          "waitDuration": "0s",
          "totalDuration": "1151s",
          "startTime": "2024-02-13T00:19:31Z"
        }
      ],
      "metrics": {
        "performedShipmentCount": 1,
        "travelDuration": "2322s",
        "waitDuration": "0s",
        "delayDuration": "0s",
        "breakDuration": "0s",
        "visitDuration": "0s",
        "totalDuration": "2322s",
        "travelDistanceMeters": 18603
      },
      "routeCosts": {
        "model.vehicles.cost_per_kilometer": 18.603
      },
      "routeTotalCost": 18.603
    }
  ],
  "metrics": {
    "aggregatedRouteMetrics": {
      "performedShipmentCount": 1,
      "travelDuration": "2322s",
      "waitDuration": "0s",
      "delayDuration": "0s",
      "breakDuration": "0s",
      "visitDuration": "0s",
      "totalDuration": "2322s",
      "travelDistanceMeters": 18603
    },
    "usedVehicleCount": 1,
    "earliestVehicleStartTime": "2024-02-13T00:00:00Z",
    "latestVehicleEndTime": "2024-02-13T00:38:42Z",
    "totalCost": 18.603,
    "costs": {
      "model.vehicles.cost_per_kilometer": 18.603
    }
  }
}