疑難排解常見問題

如果遇到任何問題，請參閱下列各節。

Fleet Engine 中的遺失狀態

使用 Fleet Engine 時，請預先考量可能發生的失敗情況，並設計相應的實作方式。舉例來說，如果您向 Fleet Engine 發出更新車輛的要求，系統可能會傳回錯誤，指出車輛不存在。接著，您的實作項目應以新狀態重新建立車輛。

在極不可能發生的情況下，如果 Fleet Engine 發生災難性故障，您可能需要重新建立大部分或所有車輛和任務。如果建立速率過高，系統會進行配額檢查，避免阻斷攻擊 (DOS) 攻擊，因此部分要求可能會再次因配額問題而失敗。在這種情況下，請使用輪詢策略降低重新建立速率，再重新嘗試。

重試次數

請務必在系統中實作 Fleet Engine 要求重試機制，因為要求有時可能會失敗。Fleet Engine 用戶端程式庫預設會發出重試。

司機應用程式中的遺失狀態

如果司機應用程式當機，應用程式必須在 Driver SDK 中重新建立目前狀態。應用程式應嘗試重新建立工作，確保工作存在並還原目前狀態。應用程式也應重新建立並明確設定 Driver SDK 的停靠站清單。

注意：這些還原作業必須自主完成，不得依賴 Fleet Engine 的資訊，但指出資料庫中是否已存在實體及存在時間的錯誤除外。如果實體已存在，則可吸收該錯誤，並使用其 ID 更新實體。

超過期限錯誤

呼叫 Fleet Engine 時，如果收到 DEADLINE_EXCEEDED 錯誤，表示要求耗費的時間超過設定的逾時時間。Fleet Engine 用戶端程式庫有預設逾時時間，但您可能需要調整。

如需 gRPC 期限的一般資訊，請參閱「gRPC 和期限」。

如要在使用 Fleet Engine Java 用戶端程式庫時設定期限，可以調整 RPC 重試設定。以下範例說明如何在設定 VehicleService 時，自訂逾時時間：

VehicleServiceSettings.Builder settingsBuilder = VehicleServiceSettings.newBuilder();

// Set the timeout to 10 seconds.
settingsBuilder
    .getVehicleSettings()
    .setRetrySettings(
        settingsBuilder.getVehicleSettings().getRetrySettings().toBuilder()
            .setTotalTimeout(java.time.Duration.ofSeconds(10))
            .build());

VehicleServiceClient client = VehicleServiceClient.create(settingsBuilder.build());

常見 API 錯誤

本節列出您可能遇到的常見 API 錯誤、原因和解決方法。

NOT_FOUND (HTTP 404)

找不到要求的實體 (例如車輛、行程或工作)。

  • 原因：通常是因為嘗試使用資料庫中不存在的 ID 取得、更新或刪除實體。
  • 修復方式：確認實體 ID 正確無誤，且實體已成功建立，再嘗試存取。

ALREADY_EXISTS (HTTP 409)

您嘗試建立的實體已存在。

  • 原因：呼叫建立方法 (例如 CreateVehicle 或 CreateTrip) 時，使用了已在使用的 ID。
  • 補救措施：請改為更新現有實體，或在建立要求中使用新的專屬 ID。

PERMISSION_DENIED (HTTP 403)

您沒有必要權限，無法完成要求。

  • 原因：這通常是因為 JSON Web Token (JWT) 缺少正確的宣告，或是簽署 JWT 的服務帳戶缺少必要的 IAM 角色。例如：「JWT does not contain a matching scope for requested trip.」(JWT 未包含與所要求行程相符的範圍)。
  • 補救措施：檢查服務帳戶權限，並確認 JWT 宣告包含您嘗試存取的實體正確範圍。

INVALID_ARGUMENT (HTTP 400)

要求中傳遞的一或多個引數無效。

  • 原因：造成這種情況的原因有很多，例如提供超出範圍的值 (例如最大容量)、缺少必要欄位 (例如 VehicleType)，或提供無效的上車地點座標。
  • 修復：查看錯誤訊息，找出無效的特定欄位，並確保要求符合 API 規格。

FAILED_PRECONDITION (HTTP 400)

系統未處於執行作業所需的狀態，因此作業遭拒。

  • 原因：常見原因包括嘗試將 COMPLETE 或 CANCELED 行程變更為其他狀態，或嘗試將 CLOSED 工作指派給車輛。
  • 修復：確認實體目前的狀態允許您嘗試執行的作業。請查看錯誤訊息，瞭解具體違反狀態。

UNAVAILABLE (HTTP 503)

服務無法使用。

  • 原因：這表示 Fleet Engine 服務發生暫時性問題。
  • 補救措施：您可以安全地以指數輪詢方式重試要求。