일반적인 문제 해결하기

문제가 발생하면 다음 섹션을 확인하여 도움을 받으세요.

플릿 엔진의 분실 상태

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