排查常见问题

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

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 令牌 (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 服务存在暂时性问题。
  • 补救措施：可以使用指数退避算法安全地重试请求。