排查常见问题

如果您遇到任何问题，请参阅以下各部分寻求帮助。

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 令牌 (JWT) 缺少正确的声明，或者对 JWT 进行签名的服务账号缺少所需的 IAM 角色。例如，“JWT does not contain a matching scope for requested trip.”
  • 修复：检查您的服务账号权限，并确保您的 JWT 声明包含您尝试访问的实体的正确范围。

INVALID_ARGUMENT (HTTP 400)

请求中传递的一个或多个参数无效。

  • 原因：这可能是由于各种原因造成的，例如提供超出范围的值（例如最大容量）、缺少必填字段（例如 VehicleType）或为上车点提供无效坐标。
  • 补救措施：查看出错提示，了解无效的具体字段，并确保您的请求符合 API 规范。

FAILED_PRECONDITION (HTTP 400)

操作被拒绝，因为系统未处于执行该操作所需的状态。

  • 原因：常见原因包括尝试将 COMPLETE 或 CANCELED 行程更改为其他状态，或尝试将 CLOSED 任务分配给车辆。
  • 修复：确保实体的当前状态允许您尝试执行的操作。请查看出错提示，了解具体的状态违规情况。

UNAVAILABLE (HTTP 503)

服务不可用。

  • 原因：这表示 Fleet Engine 服务存在暂时性问题。
  • 修复：可以使用指数退避算法安全地重试请求。