일반적인 문제 해결하기

문제가 발생하면 다음 섹션에서 도움말을 확인하세요.

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 웹 토큰 (JWT)에 올바른 클레임이 없거나 JWT에 서명하는 서비스 계정에 필요한 IAM 역할이 없는 경우 발생합니다. 예를 들어 'JWT에 요청된 이동에 일치하는 범위가 포함되어 있지 않습니다.'
  • 해결 방법: 서비스 계정 권한을 확인하고 JWT 클레임에 액세스하려는 항목의 올바른 범위가 포함되어 있는지 확인합니다.

INVALID_ARGUMENT (HTTP 400)

요청에 전달된 인수 중 하나 이상이 잘못되었습니다.

  • 원인: 범위 외 값 (예: 최대 용량)을 제공하거나 필수 필드 (예: VehicleType)가 누락되거나 픽업 지점에 잘못된 좌표를 제공하는 등 여러 가지 이유로 발생할 수 있습니다.
  • 해결 방법: 잘못된 특정 필드의 오류 메시지를 검토하고 요청이 API 사양을 준수하는지 확인합니다.

FAILED_PRECONDITION (HTTP 400)

시스템이 작업 실행에 필요한 상태가 아니기 때문에 작업이 거부되었습니다.

  • 원인: 일반적인 원인으로는 COMPLETE 또는 CANCELED 이동을 다른 상태로 변경하려고 하거나 CLOSED 작업을 차량에 할당하려고 하는 경우가 있습니다.
  • 해결 방법: 항목의 현재 상태가 시도하는 작업을 허용하는지 확인합니다. 특정 상태 위반에 관한 오류 메시지를 확인합니다.

UNAVAILABLE (HTTP 503)

서비스를 사용할 수 없습니다.

  • 원인: 이는 Fleet Engine 서비스의 일시적인 문제를 나타냅니다.
  • 해결 방법: 지수 백오프로 요청을 안전하게 재시도할 수 있습니다.