排查常见问题

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

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 不包含所请求行程的匹配范围”。
  • 补救措施：检查您的服务账号权限，并确保您的 JWT 声明包含您尝试访问的实体的正确范围。

INVALID_ARGUMENT (HTTP 400)

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

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

FAILED_PRECONDITION (HTTP 400)

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

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

UNAVAILABLE (HTTP 503)

服务不可用，

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