일반적인 문제 해결하기

문제가 발생하면 다음 섹션을 확인하세요.

Fleet Engine의 분실 상태

Fleet Engine으로 작업할 때는 장애를 예상하여 구현을 설계하세요. 예를 들어 Fleet Engine에 차량을 업데이트하라는 요청을 발행하면 차량이 존재하지 않는다는 오류로 응답할 수 있습니다. 그러면 구현에서 새 상태로 차량을 다시 만들어야 합니다.

Fleet Engine에 심각한 장애가 발생할 가능성은 매우 낮지만, 이 경우 대부분 또는 모든 차량과 작업을 다시 만들어야 할 수 있습니다. 생성률이 너무 높아지면 서비스 거부 (DOS) 공격을 방지하기 위해 할당량 검사가 진행되므로 할당량 문제로 인해 일부 요청이 다시 실패할 수 있습니다. 이 경우 재시도 백오프 전략을 사용하여 재생성 속도를 늦춥니다.

재시도

가끔 실패할 수 있으므로 시스템에서 Fleet Engine에 대한 요청을 재시도하도록 구현해야 합니다. Fleet Engine 클라이언트 라이브러리는 기본적으로 재시도를 실행합니다.

운전자 앱에서 상태가 손실됨

드라이버 앱이 비정상 종료되면 앱은 드라이버 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 서비스에 일시적인 문제가 있음을 나타냅니다.
  • 해결 방법: 지수 백오프로 요청을 안전하게 다시 시도할 수 있습니다.