疑難排解常見問題

如果遇到任何問題，請參閱下列章節尋求協助。

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)

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

  • 原因：使用已在使用的 ID 呼叫建立方法 (例如 CreateVehicle 或 CreateTrip) 所致。
  • 修正方式：更新現有實體，或在建立要求中使用新的專屬 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 服務發生暫時性問題。
  • 補救措施：可以安全地以指數輪詢方式重試要求。