주문형 차량 공유 및 배송 솔루션은 현재 일부 파트너만 이용할 수 있습니다.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

Fleet Engine 시작하기

Fleet Engine 주문형 차량 공유 및 배송 API를 사용하면 이동 및 주문 진행률 애플리케이션의 이동 및 차량 상태를 관리할 수 있습니다. 드라이버 SDK, 소비자 SDK, 백엔드 서비스 간의 트랜잭션을 처리하며 gRPC 또는 REST 호출을 통해 Fleet Engine과 통신할 수 있습니다.

기본 요건

개발의 경우 Cloud SDK (gcloud)를 설치하고 프로젝트에 대해 인증을 받아야 합니다.

shell

gcloud auth login

다음과 같은 성공 메시지가 표시됩니다.

You are now logged in as [my-user@example.com].
Your current project is [project-id].  You ...

주문형 차량 공유 및 배송 솔루션 Fleet Engine API가 적절하게 구성되었는지 확인합니다.

shell

gcloud --project=project-id services enable fleetengine.googleapis.com

이 명령어에서 오류가 발생하면 프로젝트 관리자 및 Google 지원 담당자에게 문의하여 액세스 권한을 받으세요.

로깅

Fleet Engine은 수신하는 API 호출에 대한 로그 메시지를 Google Cloud Platform 로그에 쓸 수 있습니다. 로그를 읽고 분석하는 방법에 대한 개요는 Cloud Logging 문서를 참조하세요.

2022년 2월 10일 이전에 생성된 프로젝트의 경우 로깅이 기본적으로 사용 설정되지 않을 수 있습니다. 자세한 내용은 로깅 문서를 참조하세요.

클라이언트 라이브러리

Google은 여러 가지 공통 프로그래밍 언어로 클라이언트 라이브러리를 게시합니다. 이러한 라이브러리는 원시 REST 또는 gRPC에 비해 더 나은 개발자 환경을 제공하는 데 도움이 됩니다. 서버 애플리케이션에 클라이언트 라이브러리를 가져오는 방법은 클라이언트 라이브러리를 참조하세요.

이 문서의 Java 예시에서는 gRPC를 잘 알고 있어야 합니다.

인증 및 승인

Google Cloud 콘솔을 통해 이동 및 주문 진행률에서 제공하는 기능을 구성할 수 있습니다. 이러한 API 및 SDK를 사용하려면 Cloud 콘솔에서 만든 서비스 계정을 사용하여 서명된 JSON 웹 토큰을 사용해야 합니다.

Cloud 프로젝트 설정

클라우드 프로젝트를 설정하려면 먼저 프로젝트를 만든 다음 서비스 계정을 만듭니다.

Google Cloud 프로젝트를 만들려면 다음 안내를 따르세요.

Google Cloud 콘솔을 사용하여 Google Cloud 프로젝트를 만듭니다.
API 및 서비스 대시보드를 사용하여 Local Rides and Deliveries API를 사용 설정합니다.

서비스 계정은 하나 이상의 역할과 연결됩니다. 이 역할은 역할에 따라 다른 권한 집합을 부여하는 JSON 웹 토큰을 만드는 데 사용됩니다. 일반적으로 악용 가능성을 줄이기 위해 최소한의 역할 집합만 있는 서비스 계정을 여러 개 만들 수 있습니다.

이동 및 주문 진행 상황은 다음 역할을 사용합니다.

역할	설명
Fleet Engine Consumer SDK 사용자 `roles/fleetengine.consumerSdkUser`	차량을 검색하고 차량 및 이동에 대한 정보를 가져올 수 있는 권한을 부여합니다. 이 역할을 가진 서비스 계정에서 생성한 토큰은 일반적으로 차량 공유 또는 배달 소비자 앱 휴대기기에서 사용됩니다.
Fleet Engine Driver SDK 사용자 `roles/fleetengine.driverSdkUser`	차량 위치 및 경로를 업데이트하고 차량 및 이동에 대한 정보를 가져올 수 있는 권한을 부여합니다. 이 역할을 가진 서비스 계정에서 생성한 토큰은 일반적으로 차량 공유 또는 배달 기사 앱 휴대기기에서 사용됩니다.
Fleet Engine 주문형 관리자 `roles/fleetengine.ondemandAdmin`	모든 차량 및 여행 리소스에 대한 읽기 및 쓰기 권한을 부여합니다. 이 역할이 있는 주 구성원은 JWT를 사용할 필요가 없으며 대신 애플리케이션 기본 사용자 인증 정보를 사용해야 합니다. 커스텀 JWT 클레임은 무시됩니다. 이 역할은 신뢰할 수 있는 환경 (고객 백엔드)으로 제한해야 합니다.
~~FleetEngine 서비스 수퍼유저~~ (지원 중단됨) `roles/fleetengine.serviceSuperUser`	모든 차량 및 여정 API에 대한 권한을 부여합니다. 이 역할을 가진 서비스 계정에서 발급된 토큰은 일반적으로 백엔드 서버에서 사용됩니다. 이 역할은 지원 중단되었습니다. 대신 `roles/fleetengine.ondemandAdmin`를 사용하는 것이 좋습니다.

예를 들어 3가지 역할 각각에 대한 서비스 계정을 만들어 각각의 역할을 할당합니다.

gcloud --project=project-id iam service-accounts create fleet-engine-consumer-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-consumer-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.consumerSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-driver-sdk
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-driver-sdk@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.driverSdkUser

gcloud --project=project-id iam service-accounts create fleet-engine-su
gcloud projects add-iam-policy-binding project-id \
       --member=serviceAccount:fleet-engine-su@project-id.iam.gserviceaccount.com \
       --role=roles/fleetengine.serviceSuperUser

드라이버 및 소비자 SDK는 이러한 표준 역할을 중심으로 빌드됩니다.

또는 임의의 권한 집합을 번들로 묶을 수 있는 커스텀 역할을 만들 수도 있습니다. 드라이버 및 소비자 SDK는 필수 권한이 누락될 때마다 오류 메시지를 표시합니다. 따라서 커스텀 역할 대신 위에 나온 표준 역할 집합을 사용할 것을 적극 권장합니다.

편의를 위해 신뢰할 수 없는 클라이언트에 대해 JWT 토큰을 만들어야 하는 경우 서비스 계정 토큰 생성자 역할에 사용자를 추가하면 해당 사용자가 gcloud 명령줄 도구로 토큰을 만들 수 있습니다.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

여기서 my-user@example.com은 gcloud (gcloud auth list --format='value(account)') 인증에 사용되는 이메일입니다.

Fleet Engine 인증 라이브러리

Fleet Engine은 JSON 웹 토큰 (JWT)을 사용하여 Fleet Engine API에 대한 액세스를 제한합니다. 새로운 Fleet Engine 인증 라이브러리는 GitHub에서 제공되며 Fleet Engine JWT의 구성을 간소화하고 안전하게 서명합니다.

라이브러리의 이점은 다음과 같습니다.

Fleet Engine 토큰을 만드는 프로세스를 간소화합니다.
사용자 인증 정보 파일 사용 이외의 토큰 서명 메커니즘 (예: 서비스 계정 가장)을 제공합니다.
서명된 토큰을 gRPC 스텁 또는 GAPIC 클라이언트에서 전송한 아웃바운드 요청에 연결합니다.

승인을 위한 JSON 웹 토큰 (JWT) 만들기

Fleet Engine 인증 라이브러리를 사용하지 않는 경우 코드베이스 내에서 직접 JSON 웹 토큰 (JWT)을 만들어야 합니다. 이를 위해서는 JWT와 Fleet Engine과의 관계에 대한 이해가 필요합니다. 따라서 Fleet Engine 인증 라이브러리를 활용할 것을 적극 권장합니다.

Fleet Engine 내에서 JSON 웹 토큰 (JWT)은 단기 인증을 제공하고 기기는 승인된 차량, 이동 또는 작업만 수정할 수 있도록 합니다. JWT는 헤더와 클레임 섹션을 포함합니다. 헤더 섹션에는 사용할 비공개 키 (서비스 계정에서 가져옴) 및 암호화 알고리즘과 같은 정보가 포함됩니다. 클레임 섹션에는 토큰의 생성 시간, 토큰 TTL(수명), 액세스 권한을 요청하는 서비스, 액세스 범위를 좁히기 위한 기타 승인 정보(예: 차량 ID)와 같은 정보가 포함됩니다.

JWT 헤더 섹션에는 다음 필드가 포함됩니다.

필드	설명
alg	사용할 알고리즘입니다. `RS256`
typ	토큰 유형입니다. `JWT`입니다.
어린이	서비스 계정의 비공개 키 ID입니다. 이 값은 서비스 계정 JSON 파일의 `private_key_id` 필드에서 찾을 수 있습니다. 올바른 수준의 권한을 가진 서비스 계정의 키를 사용해야 합니다.

JWT 클레임 섹션에는 다음 필드가 포함됩니다.

필드	설명
iss	서비스 계정의 이메일 주소입니다.
Pub/Sub이 있습니다	서비스 계정의 이메일 주소입니다.
aud	서비스 계정의 SERVICE_NAME(이 경우 https://fleetengine.googleapis.com/)
iat	토큰이 생성된 타임스탬프로 1970년 1월 1일 00:00:00 UTC 이후의 경과된 초 단위로 지정됩니다. 편향은 10분 동안 허용합니다. 타임스탬프가 너무 먼 과거이거나 미래인 경우 서버에서 오류를 보고할 수 있습니다.
exp	토큰이 만료되는 타임스탬프로, 1970년 1월 1일 00:00:00(UTC) 이후 경과된 시간(초)으로 지정됩니다. 타임스탬프가 1시간을 넘으면 요청이 실패합니다.
승인	사용 사례에 따라 `vehicleid` 또는 `tripid`를 포함할 수 있습니다.

JWT 토큰을 만드는 것은 토큰을 서명하는 것을 의미합니다. JWT를 만들고 서명하는 방법에 대한 안내와 코드 샘플은 OAuth를 사용하지 않는 서비스 계정 승인을 참조하세요. 그런 다음 서명된 토큰을 gRPC 호출 또는 Fleet Engine에 액세스하는 데 사용되는 다른 메서드에 연결할 수 있습니다.

JWT 클레임

JWT 페이로드를 만들 때는 호출 대상 차량 ID 또는 이동 ID 값으로 설정된 vehicleid 또는 tripid 키와 함께 승인 섹션에 추가 클레임을 추가합니다.

Driver SDK는 여행 중이든 차량에서 작동하든 항상 vehicleid 클레임을 사용합니다. Fleet Engine 백엔드는 수정하기 전에 차량이 요청된 이동과 연결되어 있는지 확인합니다.

소비자 SDK는 항상 tripid 클레임을 사용합니다.

차량 공유 또는 배달 제공업체는 모든 차량 및 이동과 일치하도록 '*'가 있는 vehicleid 또는 tripid를 사용해야 합니다. 필요하지 않은 경우에도 JWT에 두 개의 토큰이 모두 포함될 수 있으므로 토큰 서명 구현이 간소화될 수 있습니다.

JWT 사용 사례

다음은 제공업체 서버의 토큰 예를 보여줍니다.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_provider_service_account"
}
.
{
  "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
  "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

다음은 소비자 앱의 토큰 예입니다.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

다음은 드라이버 앱의 토큰 예시입니다.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

헤더의 kid 필드에 서비스 계정의 비공개 키 ID를 지정합니다. 이 값은 서비스 계정 JSON 파일의 private_key_id 필드에서 찾을 수 있습니다.
iss 및 sub 필드에 서비스 계정의 이메일 주소를 지정합니다. 이 값은 서비스 계정 JSON 파일의 client_email 필드에서 찾을 수 있습니다.
aud 필드에 https://SERVICE_NAME/을 지정합니다.
iat 필드에는 토큰이 생성된 타임스탬프를 사용합니다. 이 타임스탬프는 1970년 1월 1일 00:00:00(UTC) 이후 경과된 시간(초)으로 지정됩니다. 편향은 10분 동안 허용합니다. 타임스탬프가 너무 먼 과거이거나 미래인 경우 서버에서 오류를 보고할 수 있습니다.
exp 필드에는 토큰이 만료되는 타임스탬프를 사용합니다. 이 타임스탬프는 1970년 1월 1일 00:00:00 UTC 이후의 초로 지정됩니다. 최대 허용 값은 iat + 3600입니다.

휴대기기에 전달할 JWT에 서명할 때는 드라이버 또는 소비자 SDK 역할에 서비스 계정을 사용해야 합니다. 그러지 않으면 휴대기기는 있어서는 안 되는 상태를 변경할 수 있습니다.

마찬가지로 권한 있는 호출에 사용할 JWT에 서명할 때는 수퍼유저 역할이 있는 서비스 계정을 사용해야 합니다. 그렇지 않으면 작업이 실패합니다.

테스트용 JWT 생성

터미널에서 토큰을 생성하면 테스트 시 도움이 될 수 있습니다.

다음 단계를 따르려면 사용자 계정에 서비스 계정 토큰 생성자 역할이 있어야 합니다.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

아래 콘텐츠로 unsigned_token.json라는 새 파일을 만듭니다. iat 속성은 에포크 이후의 현재 시간(초 단위)으로, 터미널에서 date +%s를 실행하여 검색할 수 있습니다. exp 속성은 에포크 이후의 만료 시간(초 단위)으로, iat에 3600을 추가하여 계산할 수 있습니다. 만료 시간은 앞으로 1시간을 초과할 수 없습니다.

{
  "aud": "https://fleetengine.googleapis.com/",
  "iss": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "sub": "super-user-service-account@project-id.iam.gserviceaccount.com",
  "iat": iat,
  "exp": exp,
  "authorization": {
     "vehicleid": "*",
     "tripid": "*"
   }
}

그런 다음 다음 gcloud 명령어를 실행하여 수퍼 사용자 서비스 계정 대신 토큰에 서명합니다.

gcloud beta iam service-accounts sign-jwt --iam-account=super-user-service-account@project-id.iam.gserviceaccount.com unsigned_token.json signed_token.jwt

서명된 Base64로 인코딩된 JWT가 이제 signed_token.jwt 파일에 저장됩니다. 토큰은 다음 1시간 동안 유효합니다.

이제 차량 나열 REST 엔드포인트에 대해 curl 명령어를 실행하여 토큰을 테스트할 수 있습니다.

curl -X GET "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles" -H "Authorization: Bearer $(cat signed_token.jwt)"

차량 및 수명 주기

차량은 운전자와 차량 쌍을 나타내는 항목입니다. 현재 운전자와 차량은 별도로 추적할 수 없습니다. 차량 공유 또는 배송 제공업체는 제공업체 ID (Fleet Engine API를 호출하는 데 사용되는 서비스 계정이 포함된 Google Cloud 프로젝트의 프로젝트 ID와 동일해야 함) 및 차량 공유 또는 배송 제공업체가 소유한 차량 ID를 사용하여 차량을 만듭니다.

7일이 지나도 UpdateVehicle를 통해 업데이트되지 않은 차량은 자동으로 삭제됩니다. Fleet Engine에서 차량을 계속 사용할 수 있도록 하려면 정기적으로 위치를 업데이트하는 것이 좋습니다. 새 필드 값이 기존 값과 다르다면 Vehicle 항목의 다른 필드 대부분을 업데이트하면 수명이 연장됩니다.

참고: device_settings와 같은 Vehicle 항목의 일부 필드는 Fleet Engine에서 유지하지 않는 디버그 정보입니다. 이 객체를 업데이트해도 Vehicle 항목의 수명이 연장되지는 않습니다.

이미 존재하는 제공업체 ID/차량 ID 쌍으로 CreateVehicle를 호출하면 오류입니다. 자주 업데이트되지 않는 차량의 경우는 두 가지 방법으로 처리할 수 있습니다. 예상 제공자 ID/차량 ID 쌍으로 CreateVehicle를 자주 호출하고 차량이 이미 존재하는 경우 오류를 삭제하거나 UpdateVehicle가 NOT_FOUND 오류와 함께 반환된 후 CreateVehicle를 호출하는 것입니다.

차량 위치 업데이트

Fleet Engine으로 최상의 성능을 얻으려면 차량 위치 업데이트 스트림을 제공하세요. 이러한 업데이트를 제공하려면 다음 방법 중 하나를 사용하세요.

드라이버 SDK(Android, iOS)를 사용합니다(가장 간단한 옵션).
맞춤 코드 사용 -- 위치가 백엔드를 통해 릴레이되거나 Android 또는 iOS 이외의 기기를 사용하는 경우에 유용합니다.

차량 유형

차량 항목에는 AUTO, TAXI, TRUCK, TWO_WHEELER, BICYCLE, PEDESTRIAN 중 하나로 지정할 수 있는 Category enum이 포함된 VehicleType의 필수 필드가 포함됩니다. 차량 유형은 SearchVehicles 및 ListVehicles에서 필터 기준으로 사용할 수 있습니다.

차량의 모든 경로 지정은 카테고리가 AUTO, TWO_WHEELER, BICYCLE 또는 PEDESTRIAN로 설정된 경우 상응하는 RouteTravelMode를 사용합니다. 카테고리가 TAXI 또는 TRUCK로 설정된 경우 라우팅은 AUTO 모드와 동일하게 처리됩니다.

차량 속성

차량 항목에 VehicleAttribute의 반복되는 필드가 포함되어 있습니다. 이러한 속성은 Fleet Engine에서 해석되지 않습니다. SearchVehicles API에는 일치하는 Vehicles에 지정된 값으로 설정된 포함된 모든 속성이 포함되어야 한다는 필드가 포함되어 있습니다.

속성 필드는 Vehicle 메시지에서 지원되는 다른 여러 필드(예: vehicle_type 및 supported_trip_types)에 추가됩니다.

차량 남은 경유지

차량 항목에는 waypoints (RPC | REST)라고 하는 TripWaypoint(RPC | REST)의 반복 필드가 포함되어 있습니다. 이 필드에는 차량이 도달하는 순서대로 이동의 나머지 경유지가 포함됩니다. Fleet Engine은 이동이 차량에 할당될 때 이 필드를 계산하고 이동 상태가 변경되면 이 필드를 업데이트합니다. 이러한 경유지는 TripId 필드와 WaypointType 필드로 식별할 수 있습니다.

차량의 일치 자격요건 확장

일반적으로 차량 공유 또는 배송 제공업체의 서비스는 이동 요청을 차량에 일치시킬 책임이 있습니다. 이 서비스는 차량 속성을 사용하여 더 많은 검색에 차량을 포함할 수 있습니다. 예를 들어 제공업체는 차량에서 제공하는 혜택 또는 기능 수준에 상응하는 속성으로 집합을 구현할 수 있습니다. 예를 들어 불리언 값이 있는 속성 집합(is_bronze_level, is_silver_level, is_gold_level)이 3개 수준일 수 있습니다. 차량은 세 가지 모두에 적합할 수 있습니다. Fleet Engine이 실버 수준의 기능이 필요한 이동 요청을 수신하면 해당 차량이 검색에 포함됩니다. 이 방식으로 속성을 사용하면 다양한 기능을 제공하는 차량이 포함됩니다.

차량 속성을 업데이트하는 방법에는 두 가지가 있습니다. 하나는 UpdateVehicle API입니다. 이 API를 사용하면 전체 차량 속성 세트가 이 값으로 설정됩니다. 하나의 속성만 업데이트할 수는 없습니다. 다른 메서드는 UpdateVehicleAttributes API입니다. 이 메서드는 업데이트할 속성만 사용합니다. 요청에 포함된 속성은 새 값 또는 추가된 값으로 설정됩니다. 지정되지 않은 속성은 변경되지 않습니다.

방법: 차량 만들기

Fleet에서 추적할 각 차량에 대해 Vehicle 항목을 만들어야 합니다.

CreateVehicle 엔드포인트를 CreateVehicleRequest와 함께 사용하여 차량을 만듭니다.

Vehicle의 provider_id는 Fleet Engine을 호출하는 데 사용할 서비스 계정이 포함된 Google Cloud 프로젝트의 프로젝트 ID(예: my-on-demand-project)여야 합니다. 여러 서비스 계정이 동일한 차량 공유 또는 배송 제공업체의 Fleet Engine에 액세스할 수 있지만 Fleet Engine은 현재 동일한 Vehicles에 액세스하는 여러 Google Cloud 프로젝트의 서비스 계정을 지원하지 않습니다.

Vehicle는 OFFLINE 또는 ONLINE 상태로 만들 수 있습니다. ONLINE를 만들면 SearchVehicles 쿼리에 대한 응답으로 즉시 반환될 수 있습니다.

첫 번째 last_location는 CreateVehicle 호출에 포함될 수 있습니다. Vehicle는 허용되지만 last_location 없이 ONLINE 상태에서 생성되어서는 안 됩니다.

차량 유형 필드에 관한 자세한 내용은 차량 유형을 참고하세요.

속성 필드에 관한 자세한 내용은 차량 속성을 참고하세요.

CreateVehicle에서 반환된 값은 생성된 Vehicle 항목입니다.

예시

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles?vehicleId=vid-8241890" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "OFFLINE",
    "supportedTripTypes": ["EXCLUSIVE"],
    "maximumCapacity": 4,
    "vehicleType": {"category": "AUTO"},
    "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

providers.vehicles.create 참조를 확인하세요.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService =
    VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Vehicle vehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.OFFLINE)  // Initial state
    .addSupportedTripTypes(TripType.EXCLUSIVE)
    .setMaximumCapacity(4)
    .setVehicleType(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .addAttributes(VehicleAttribute.newBuilder()
        .setKey("on_trip").setValue("false"))  // Opaque to the Fleet Engine
    // Add .setBackToBackEnabled(true) to make this vehicle eligible for trip
    // matching while even if it is on a trip.  By default this is disabled.
    .build();

CreateVehicleRequest createVehicleRequest =
    CreateVehicleRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setVehicleId("vid-8241890")  // Vehicle ID assigned by Rideshare or Delivery Provider
        .setVehicle(vehicle)  // Initial state
        .build();

// In this case, the Vehicle is being created in the OFFLINE state and
// no initial position is being provided.  When the Driver App checks
// in with the Rideshare or Delivery Provider, the state can be set to ONLINE and
// the Driver App will update the Vehicle Location.

try {
  Vehicle createdVehicle =
      vehicleService.createVehicle(createVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle created successfully.

차량 생성을 위한 Google Cloud Platform 로그

Fleet Engine API는 CreateVehicle 엔드포인트에 대한 호출이 수신되면 Google Cloud Platform 로그를 통해 로그 항목을 작성합니다. 로그 항목에는 CreateVehicle 요청의 값에 대한 정보가 포함됩니다. 호출이 성공하면 반환된 Vehicle에 관한 정보도 포함됩니다.

shell

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog"
'

다음과 유사한 레코드가 출력되어야 합니다.

---
insertId: c2cf4d3a180251c1bdb892137c14f022
jsonPayload:
  '@type': type.googleapis.com/maps.fleetengine.v1.CreateVehicleLog
  request:
    vehicle:
      attributes:
      - key: on_trip
        value: 'false'
      maximumCapacity: 4
      state: VEHICLE_STATE_OFFLINE
      supportedTrips:
      - EXCLUSIVE_TRIP
      vehicleType:
        vehicleCategory: AUTO
    vehicleId: vid-8241890
  response:
    attributes:
    - key: on_trip
      value: 'false'
    availableCapacity: 4
    currentRouteSegmentHandle: AdSiwAwCO9gZ7Pw5UZZimOXOo41cJTjg/r3SuwVPQmuuaV0sU3+3UCY+z53Cl9i6mWHLoCKbBt9Vsj5PMRgOJ8zX
    maximumCapacity: 4
    name: providers/project-id/vehicles/vid-8241890
    state: VEHICLE_STATE_OFFLINE
    supportedTrips:
    - EXCLUSIVE_TRIP
    vehicleType:
      vehicleCategory: AUTO
labels:
  vehicle_id: vid-8241890
logName: projects/project-id/logs/fleetengine.googleapis.com%2Fcreate_vehicle
receiveTimestamp: '2021-09-22T03:25:16.361159871Z'
resource:
  labels:
    location: global
    resource_container: projects/project-id
  type: fleetengine.googleapis.com/Fleet
timestamp: '2021-09-22T03:25:15.724998Z'

차량 생성을 위한 Cloud Pub/Sub 알림

Fleet Engine API는 새 차량이 생성되면 Cloud Pub/Sub를 통해 알림을 게시합니다. 이러한 알림을 받으려면 여기의 안내를 따르세요.

방법: 차량 위치 업데이트

Driver SDK를 사용하여 차량 위치를 업데이트하지 않는 경우 차량 위치를 사용하여 Fleet Engine을 직접 호출할 수 있습니다. 활성 차량의 경우 Fleet Engine은 최소 1분에 한 번, 최대 5초마다 위치 업데이트를 예상합니다. 이 업데이트에는 Fleet Engine 드라이버 SDK 사용자 권한만 필요합니다.

예시

shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
}
EOM

providers.vehicles.update 참조를 확인하세요.

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setLastLocation(VehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(LocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("last_location"))
    .build();

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

방법: 다른 차량 필드 업데이트

차량 상태의 다른 속성 업데이트는 위치 업데이트보다 자주 발생합니다. last_location 이외의 속성을 업데이트하려면 Fleet Engine 수퍼유저 권한이 필요합니다.

UpdateVehicleRequest에는 업데이트할 필드를 나타내는 update_mask가 포함되어 있습니다. 필드 동작은 필드 마스크에 관한 Protobuf 문서와 같습니다.

차량 속성에서 언급했듯이 attributes 필드를 업데이트하려면 보존할 모든 속성을 작성해야 합니다. UpdateVehicle 호출에서 키-값 쌍 하나의 값만 업데이트할 수는 없습니다. 특정 속성의 값을 업데이트하려면 UpdateVehicleAttributes API를 사용하면 됩니다.

예시

이 예시에서는 back_to_back를 사용 설정합니다.

shell

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=vehicle_state,attributes,back_to_back_enabled" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
    "vehicleState": "ONLINE",
    "attributes": [
      {"key": "on_trip", "value": "true"},
      {"key": "cash_only", "value": "false"}
    ],
    "backToBackEnabled": true
}
EOM

providers.vehicles.update 참조를 확인하세요.

Java

static final String PROJECT_ID = "project-id";
static final String VEHICLE_ID = "vid-8241890";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String vehicleName = "providers/" + PROJECT_ID + "/vehicles/" + VEHICLE_ID;
Vehicle updatedVehicle = Vehicle.newBuilder()
    .setVehicleState(VehicleState.ONLINE)
    .addAllAttributes(ImmutableList.of(
        VehicleAttribute.newBuilder().setKey("on_trip").setValue("true").build(),
        VehicleAttribute.newBuilder().setKey("cash_only").setValue("false").build()))
    .setBackToBackEnabled(true)
    .build();

UpdateVehicleRequest updateVehicleRequest = UpdateVehicleRequest.newBuilder()
    .setName(vehicleName)
    .setVehicle(updatedVehicle)
    .setUpdateMask(FieldMask.newBuilder()
        .addPaths("vehicle_state")
        .addPaths("attributes")
        .addPaths("back_to_back_enabled"))
    .build();

// Attributes and vehicle state are being updated, so both are
// included in the field mask.  Note that of on_trip were
// not being updated, but rather cash_only was being changed,
// the desired value of "on_trip" would still need to be written
// as the attributes are completely replaced in an update operation.

try {
  Vehicle updatedVehicle =
      vehicleService.updateVehicle(updateVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      // Most implementations will call CreateVehicle in this case
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}
// If no Exception, Vehicle updated successfully.

차량 업데이트용 Google Cloud Platform 로그

Fleet Engine API는 UpdateVehicle 엔드포인트에 대한 호출이 수신되면 Google Cloud Platform 로그를 통해 로그 항목을 작성합니다. 로그 항목에는 UpdateVehicle 요청의 값에 대한 정보가 포함됩니다. 호출이 성공하면 반환된 Vehicle에 관한 정보도 포함됩니다.

shell

gcloud --project=project-id logging read --freshness=1h '
  jsonPayload.request.vehicleId="vid-8241890"
  jsonPayload.@type="type.googleapis.com/maps.fleetengine.v1.UpdateVehicleLog"
'

차량 업데이트용 Cloud Pub/Sub 알림

Fleet Engine API는 기존 차량이 업데이트되면 Cloud Pub/Sub를 통해 알림을 게시합니다. 이러한 알림을 받으려면 여기의 안내를 따르세요.

방법: 차량 검색

Fleet Engine은 차량 검색을 지원합니다. SearchVehicles API를 사용하면 차량 공유 서비스나 배달 요청과 같은 작업에 가장 적합한 근처 운전자를 찾을 수 있습니다. SearchVehicles API는 작업 속성과 차량 내 차량 속성과 일치하는 운전자의 순위 목록을 반환합니다. 자세한 내용은 주변 운전자 찾기를 참고하세요.

예시

이용 가능한 차량을 검색할 때 Fleet Engine은 기본적으로 이동 중인 차량을 제외합니다. 차량 공유 또는 배송 제공업체의 서비스는 검색 요청에 명시적으로 포함해야 합니다. 다음 예는 그랜드 인도네시아 이스트 몰에서 발라이 시당 자카르타 컨벤션 센터까지의 경로와 일치하는 차량 검색에 이러한 차량을 포함하는 방법을 보여줍니다.

shell

먼저 이전 단계에서 만든 차량의 위치를 업데이트하여 요건을 충족하도록 합니다. 실제로는 차량의 Android 또는 iOS 기기에서 실행되는 Driver SDK를 통해 실행됩니다.

curl -X PUT \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles/vid-8241890?updateMask=last_location,attributes" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "updateTime": "$( date -u +"%Y-%m-%dT%H:%M:%SZ" )",
    "location": {
      "latitude": "-6.195139",
      "longitude": "106.820826"
    }
  },
  "attributes": [{"key": "on_trip", "value": "false"}]
}
EOM

검색을 실행하면 최소한 해당 차량이 생성됩니다.

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:search" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  },
  "pickupRadiusMeters": 2000,
  "count": 10,
  "minimumCapacity": 2,
  "tripTypes": ["EXCLUSIVE"],
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
  "orderBy": "PICKUP_POINT_ETA",
  "includeBackToBack": true
}
EOM

providers.vehicles.search 참조를 확인하세요.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
SearchVehiclesRequest searchVehiclesRequest = SearchVehiclesRequest.newBuilder()
    .setParent(parent)
    .setPickupPoint( // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    .setDropoffPoint( // Balai Sidang Jakarta Convention Center
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.213796).setLongitude(106.807195)))
    .setPickupRadiusMeters(2000)
    .setCount(10)
    .setMinimumCapacity(2)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setOrderBy(VehicleMatchOrder.PICKUP_POINT_ETA)
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  SearchVehiclesResponse searchVehiclesResponse =
      vehicleService.searchVehicles(searchVehiclesRequest);

  // Search results: Each vehicle match contains a vehicle entity and information
  // about the distance and ETA to the pickup point and dropoff point.
  List<VehicleMatch> vehicleMatches = searchVehiclesResponse.getMatchesList();
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

차량 필터링 쿼리

SearchVehicles 및 ListVehicles는 필터 쿼리를 사용하여 차량 속성의 필터링을 지원합니다. 필터 쿼리 구문은 AIP-160의 예를 참고하세요.

필터 쿼리는 차량 속성에 대한 필터링만 지원하며 다른 필드에는 사용할 수 없습니다. 필터 쿼리는 SearchVehiclesRequest의 minimum_capacity 또는 vehicle_types와 같은 다른 제약조건과 함께 AND 절로 작동합니다.

방법: 차량 나열

SearchVehicles는 순위가 지정된 차량을 매우 빠르게 찾는 데 최적화되어 있으며 주로 작업에 가장 적합한 근처 운전자를 찾는 데 사용됩니다. 그러나 결과를 페이징해야 하는 경우에도 특정 기준을 충족하는 모든 차량을 찾으려는 경우가 있습니다. ListVehicles는 이러한 사용 사례에 맞게 설계되었습니다.

ListVehicles API를 사용하면 특정 요청 옵션을 충족하는 모든 차량을 찾을 수 있습니다. ListVehicles API는 프로젝트에서 일부 요구사항과 일치하는 차량의 페이지로 나눈 목록을 반환합니다.

차량 속성을 필터링하려면 차량 필터링 쿼리를 참고하세요.

예시

이 예에서는 filter 문자열을 사용하여 vehicle_type 및 속성을 필터링합니다.

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/vehicles:list" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "vehicleTypes": [{"category": "AUTO"}],
  "filter": "attributes.on_trip=\"false\"",
}
EOM

providers.vehicles.list 참조를 확인하세요.

Java

static final String PROJECT_ID = "project-id";

VehicleServiceBlockingStub vehicleService = VehicleService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
ListVehiclesRequest listVehiclesRequest = ListVehiclesRequest.newBuilder()
    .setParent(parent)
    .addTripTypes(TripType.EXCLUSIVE)
    .addVehicleTypes(VehicleType.newBuilder().setCategory(VehicleType.Category.AUTO))
    .setFilter("attributes.on_trip=\"false\"")
    .setIncludeBackToBack(true) // Fleet Engine includes vehicles that are en route.
    .build();

// Error handling
// If matches are returned and the authentication passed, the request completed
// successfully

try {
  ListVehiclesResponse listVehiclesResponse =
      vehicleService.listVehicles(listVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

이동 및 경로의 수명 주기

Trip API와 수명 주기는 차량 API 및 수명 주기와 유사합니다. 차량 공유 제공업체는 Fleet Engine 인터페이스를 사용하여 이동을 만들어야 합니다. Fleet Engine은 RPC 서비스( TripService)와 REST 리소스(provider.trips)를 모두 제공합니다. 이러한 인터페이스는 경로 항목 생성, 정보 요청, 검색 기능, 업데이트 기능을 지원합니다.

Trip에는 수명 주기 동안 진행 상황을 추적하는 상태 필드가 있습니다. 값은 NEW에서 COMPLETE, CANCELED 및 UNKNOWN_TRIP_STATUS로 이동합니다. RPC의 경우 trip_status 또는 REST의 경우 TripStatus를 참고하세요.

NEW
ENROUTE_TO_PICKUP
ARRIVED_AT_PICKUP
ENROUTE_TO_INTERMEDIATE_DESTINATION
ARRIVED_AT_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETE

서비스에서 CANCELED(으)로의 이동을 다음 상태 중 하나에서 업데이트할 수 있습니다. 서비스에서 이동을 만들면 엔진이 상태를 NEW로 설정합니다. vehicle_id는 선택사항입니다. 차량과 마찬가지로 7일 후에 업데이트 없이 이동이 자동으로 삭제됩니다. 서비스에서 이미 존재하는 ID로 이동을 만들려고 하면 오류가 반환됩니다. 상태가 COMPLETE 또는 CANCELED이 아닌 경우 '활성' 이동으로 간주됩니다. 이 구분은 차량 항목의 active_trips 필드와 SearchTripsRequest에서 중요합니다.

이동이 활성 상태일 때만 서비스에서 경로에 할당된 vehicle_id를 변경할 수 있습니다. 예를 들어 운전자가 이동 중에 경로를 취소하고 이동이 다른 차량에 재할당되는 경우 이 작업을 실행할 수 있습니다.

이 상태는 연달아 이동 지원을 구현할 때 중요합니다. 이 지원을 통해 제공자는 차량이 활성 이동에 있는 동안 새 이동을 차량에 할당할 수 있습니다. 연달아 이동 경로를 만드는 코드는 단일 경로와 동일하며 동일한 차량 ID를 사용합니다. Fleet Engine은 새 이동의 출발지와 목적지를 차량의 경유지에 추가합니다. 연속 여정에 대한 자세한 내용은 여러 경유지 경로 만들기를 참고하세요.

남은 경유지 경로

이동 항목에는 remainingWaypoints (RPC | REST)라고 하는 TripWaypoint(RPC | REST)의 반복되는 필드가 포함되어 있습니다. 이 필드에는 이 경로의 최종 하차 지점 전에 차량이 순서대로 이동해야 하는 모든 경유지가 포함됩니다. 차량의 나머지 경유지에서 계산합니다. 연달아 이동 및 카풀 사용 사례에서 이 목록에는 이 이동 전에 통과할 다른 이동의 경유지가 포함되지만 이 이동 후의 경유지는 제외됩니다. 목록의 경유지는 TripId 및 WaypointType로 식별할 수 있습니다.

이동 상태와 차량 남은 경유지 사이의 관계

Fleet Engine이 경로 상태 변경 요청을 수신하면 차량의 나머지 경유지 (RPC | REST)가 업데이트됩니다. tripStatus(RPC | REST)가 다른 상태에서 ENROUTE_TO_XXX로 변경되면 이전 경유지는 차량의 나머지 경유지 목록에서 삭제됩니다. 즉, 이동 상태가 ENROUTE_TO_PICKUP에서 ARRIVED_AT_PICKUP으로 변경될 경우 이동의 승차 지점은 여전히 차량의 나머지 경유지 목록에 남아 있게 됩니다. 단, 이동 상태가 ENROUTE_TO_INTERMEDIATE_DESTINATION 또는 ENROUTE_TO_DROPOFF로 변경되면 승차 차량의 남은 경유지가 승차 지점에서 삭제됩니다.

ARRIVED_AT_INTERMEDIATE_DESTINATION 및 ENROUTE_TO_INTERMDEDIATE_DESTINATION의 경우도 마찬가지입니다. ARRIVED_AT_INTERMEDIATE_DESTINATION인 경우 현재 중간 목적지는 차량이 다음 경유지로 향하는 경로를 보고할 때까지 차량의 나머지 경유지 목록에서 삭제되지 않습니다.

이동 상태가 COMPLETED로 변경되면 이 이동의 경유지가 차량의 나머지 경유지 목록에 포함되지 않습니다.

방법: 여행 만들기

각 이동 요청을 추적하고 Fleet의 차량과 일치시키려면 Trip 항목을 만들어야 합니다. CreateTrip 엔드포인트를 CreateTripRequest와 함께 사용하여 이동을 만듭니다.

이동을 만들려면 다음 속성이 필요합니다.

parent - Google Cloud 프로젝트를 만들 때 생성된 제공업체 ID가 포함된 문자열입니다.
trip_id - 차량 공유 제공업체에서 생성한 문자열입니다.
trip - 경로를 설명하는 기본 메타데이터가 포함된 컨테이너입니다.
- trip_type - 여정에 동일한 차량에 다른 출발지 및 목적지의 다른 탑승자가 있는지 (SHARED) 또는 단일 당사자만 (EXCLUSIVE)을 포함할 수 있는지를 나타내는 열거형입니다.
- pickup_point - 이동의 출발지를 나타내는 TerminalLocation입니다. RPC 참조 또는 REST 참조를 참조하세요.

경로를 만들 때 number_of_passengers, dropoff_point, vehicle_id를 제공할 수 있습니다. 이러한 필드는 필수는 아니지만, 제공해도 유지됩니다. 다른 모든 이동 필드는 무시됩니다. 예를 들어 생성 요청에서 CANCELED의 trip_status를 전달하더라도 모든 경로는 NEW의 trip_status로 시작합니다.

예시

다음 예에서는 Grand Indonesia 이스트 몰에 대한 여행을 만듭니다. 이 여행은 승객 2인용이며 전용 여행입니다. Trip의 provider_id는 프로젝트 ID와 동일해야 합니다. 이 예에서 차량 공유 제공업체가 Google Cloud 프로젝트 project-id를 만들었습니다. 이 프로젝트에는 Fleet Engine을 호출하는 데 사용되는 서비스 계정이 있어야 합니다. 이동 상태는 NEW입니다.

나중에 서비스가 차량과 이동을 매칭하면 UpdateTrip를 호출하고 이동이 차량에 할당될 때 vehicle_id를 변경할 수 있습니다.

shell

curl -X POST \
  "https://fleetengine.googleapis.com/v1/providers/project-id/trips?tripId=tid-1f97" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  --data-binary @- << EOM
{
  "tripType": "EXCLUSIVE",
  "numberOfPassengers": 2,
  "pickupPoint": {
    "point": {"latitude": "-6.195139", "longitude": "106.820826"}
  },
  "dropoffPoint": {
    "point": {"latitude": "-6.1275", "longitude": "106.6537"}
  }
}
EOM

providers.trips.create 참조를 확인하세요.

Java

static final String PROJECT_ID = "project-id";

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

String parent = "providers/" + PROJECT_ID;
Trip trip = Trip.newBuilder()
    .setTripType(TripType.EXCLUSIVE) // Use TripType.SHARED for carpooling
    .setPickupPoint(                 // Grand Indonesia East Mall
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
    // Provide the number of passengers if available.
    .setNumberOfPassengers(2)
    // Provide the drop-off point if available.
    .setDropoffPoint(
        TerminalLocation.newBuilder().setPoint(
            LatLng.newBuilder().setLatitude(-6.1275).setLongitude(106.6537)))
    .build();

CreateTripRequest createTripRequest =
    CreateTripRequest.newBuilder()  // no need for the header
        .setParent(parent)
        .setTripId("tid-1f97")  // Trip ID assigned by the Provider
        .setTrip(trip)              // Initial state
        .build();

// Error handling
// If Fleet Engine does not have trip with that id and the credentials of the
// requestor pass, the service creates the trip successfully.

try {
  Trip createdTrip =
      tripService.createTrip(createTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case ALREADY_EXISTS:
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

경로 생성을 위한 Google Cloud Platform 로그

Fleet Engine API는 CreateTrip 엔드포인트에 대한 호출이 수신되면 Google Cloud Platform 로그를 사용하여 로그 항목을 작성합니다. 로그 항목에는 CreateTrip 요청의 값에 대한 정보가 포함됩니다. 호출이 성공하면 반환된 Trip에 관한 정보도 포함됩니다.

방법: 경로 업데이트하기

이동 항목에는 서비스를 통한 추적 및 Driver SDK 및 소비자 SDK의 이동 진행 상황을 보고할 수 있는 필드가 포함되어 있습니다. 속성을 업데이트하려면 UpdateTripRequest 메시지를 사용합니다. 이렇게 하면 요청의 field_mask에 따라 이동 필드가 업데이트됩니다. UpdateTripRequest를 참고하세요.

차량 공유 제공업체는 다음 속성을 업데이트해야 합니다.

이동 상태
차량 ID. 생성 시 또는 차량을 이동과 일치시킨 후에
승차, 하차 또는 경유지 변경

Fleet Engine은 드라이버 SDK 또는 소비자 SDK를 통해 여정 공유 기능을 사용할 때 다음 필드를 자동으로 업데이트합니다.

경로
도착예정시간
남은 거리
차량 위치
나머지 경유지

RPC의 Trip 또는 REST의 Resource.Trip을 참조하세요.

이동 업데이트의 Google Cloud Platform 로그

Fleet Engine API는 UpdateTrip 엔드포인트에 대한 호출이 수신되면 Google Cloud Platform 로그를 사용하여 로그 항목을 작성합니다. 로그 항목에는 UpdateTrip 요청의 값에 대한 정보가 포함됩니다. 호출이 성공하면 반환된 Trip에 관한 정보도 포함됩니다.

방법: 경로 검색

Fleet Engine은 경로 검색을 지원합니다. 앞서 언급했듯이 이동은 7일 후에 자동으로 삭제되므로 SearchTrips는 모든 이동의 전체 기록을 노출하지 않습니다.

SearchTrips는 유연한 API이지만 아래 목록은 두 가지 사용 사례를 고려합니다.

차량의 활성 이동 확인: 제공자는 차량의 현재 진행 중인 이동을 확인할 수 있습니다. SearchTripsRequest 내에서 vehicle_id는 고려 중인 차량으로 설정되고 active_trips_only는 true로 설정되어야 합니다.
제공업체와 Fleet Engine 상태 조정 -- 제공업체는 SearchTrips를 사용하여 이동 상태와 Fleet Engine의 이동 상태를 일치시킬 수 있습니다. 이는 특히 TripStatus에 중요합니다. 차량에 할당된 이동의 상태가 COMPLETE 또는 CANCELED로 올바르게 설정되지 않은 경우 차량은 SearchVehicles에 포함되지 않습니다.

이러한 방식으로 SearchTrips를 사용하려면 vehicle_id를 비워 두고 active_trips_only를 true로 설정하고, minimum_staleness을 대부분의 이동 시간보다 긴 시간으로 설정합니다. 예를 들어 1시간을 사용할 수 있습니다. 결과에는 완료 또는 취소된 상태가 아니며 1시간 넘게 업데이트되지 않은 이동이 포함됩니다. 제공업체는 이러한 이동을 검사하여 Fleet Engine의 상태가 제대로 업데이트되도록 해야 합니다.

문제 해결

DEADLINE_EXCEEDED 오류가 발생하면 Fleet Engine의 상태를 알 수 없습니다. 제공업체는 CreateTrip를 다시 호출해야 하며, 이렇게 하면 201 (CREATED) 또는 409 (CONFLICT)가 반환됩니다. 후자의 경우에는 이전 요청이 DEADLINE_EXCEEDED보다 먼저 성공했습니다. 경로 오류 처리에 대한 자세한 내용은 Consumer API 가이드(Android 또는 iOS)를 참조하세요.

카풀 탑승 지원

TripType.SHARED를 지원하는 차량에 SHARED 이동을 여러 번 할당할 수 있습니다. CreateTrip 또는 UpdateTrip 요청에서 공유 이동에 vehicle_id를 할당할 때 Trip.vehicle_waypoints를 통해 이 공유 차량에 할당된 모든 이동의 모든 통과 경유지 순서를 지정해야 합니다. RPC의 경우 vehicle_waypoints 또는 REST의 경우 vehicleWaypoints를 참조하세요.

여러 대상 지원

중간 대상 식별

이동 (RPC | REST)의 intermediateDestinations 필드와 intermediateDestinationIndex 필드는 결합하여 목적지를 나타내는 데 사용됩니다.

중간 대상 업데이트

UpdateTrip를 통해 중간 대상을 업데이트할 수 있습니다. 중간 대상을 업데이트할 때는 새로 추가되었거나 수정할 대상이 아닌 방문한 대상을 포함하여 중간 대상의 전체 목록을 제공해야 합니다. intermediateDestinationIndex가 새로 추가/수정된 중간 목적지 위치 이후의 색인을 가리키면 신규/업데이트된 중간 대상이 차량의 waypoints 또는 이동의 remainingWaypoints에 추가되지 않습니다. intermediateDestinationIndex 이전의 모든 중간 대상은 이미 방문한 것으로 간주되기 때문입니다.

이동 상태 변경사항

Fleet Engine에 전송된 이동 상태 업데이트 요청에서 (RPC | REST)의 intermediateDestinationsVersion 필드는 중간 목적지가 통과되었음을 나타내기 위해 필요합니다. 타겟팅된 중간 대상은 intermediateDestinationIndex 필드를 통해 지정됩니다. tripStatus (RPC | REST)가 ENROUTE_TO_INTERMEDIATE_DESTINATION인 경우 [0..N-1] 사이의 숫자는 차량이 다음에 건너갈 중간 목적지를 나타냅니다. tripStatus이 ARRIVED_AT_INTERMEDIATE_DESTINATION인 경우 [0..N-1] 사이의 숫자는 차량이 위치한 중간 목적지를 나타냅니다.

예시

다음 코드 예에서는 다중 목적지 이동을 만들었고 여정이 승차 지점을 통과했다고 가정하고 이동 상태를 첫 번째 중간 목적지로 업데이트하는 방법을 보여줍니다.

Java

static final String PROJECT_ID = "project-id";
static final String TRIP_ID = "multi-destination-trip-A";

String tripName = "providers/" + PROJECT_ID + "/trips/" + TRIP_ID;
Trip trip = …; // Fetch trip object from FleetEngine or your storage.

TripServiceBlockingStub tripService = TripService.newBlockingStub(channel);

// Trip settings to update.
Trip trip = Trip.newBuilder()
    // Trip status cannot go back to a previous status once it is passed
    .setTripStatus(TripStatus.ENROUTE_TO_INTERMEDIATE_DESTINATION)
    // Enrouting to the first intermediate destination.
    .setIntermediateDestinationIndex(0)
    // intermediate_destinations_version MUST be provided to ensure you
    // have the same picture on intermediate destinations list as FleetEngine has.
    .setIntermediateDestinationsVersion(
        trip.getIntermediateDestinationsVersion())
    .build();

// Trip update request
UpdateTripRequest updateTripRequest =
    UpdateTripRequest.newBuilder()
        .setName(tripName)
        .setTrip(trip)
        .setUpdateMask(
            FieldMask.newBuilder()
                .addPaths("trip_status")
                .addPaths("intermediate_destination_index")
                // intermediate_destinations_version must not be in the
                // update mask.
                .build())
        .build();

// Error handling
try {
  Trip updatedTrip = tripService.updateTrip(updateTripRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
    case NOT_FOUND:  // Trip does not exist.
      break;
    case FAILED_PRECONDITION:  // The given trip status is invalid, or the
                                // intermediate_destinations_version
                                // doesn’t match FleetEngine’s.
      break;
    case PERMISSION_DENIED:
      break;
  }
  return;
}

방법: Fleet Engine API에서 알림 메시지 구독

Fleet Engine API는 Google Cloud Pub/Sub를 사용하여 소비자 Google Cloud 프로젝트에서 만든 주제에 대한 알림을 게시합니다. Pub/Sub는 Google Cloud 프로젝트의 Fleet Engine에 기본적으로 사용 설정되지 않습니다. 지원 케이스를 제출하거나 고객 엔지니어에게 문의하여 Pub/Sub를 사용 설정하세요.

Cloud 프로젝트에서 주제를 만들려면 이 안내를 따르세요. 주제 ID는 'fleet_engine_notifications'여야 합니다.

주제는 Fleet Engine API를 호출하는 동일한 Cloud 프로젝트에서 만들어야 합니다.

주제를 만든 후에는 Fleet Engine API에 주제에 게시할 권한을 부여해야 합니다. 권한을 부여하려면 방금 만든 주제를 클릭하고 새 권한을 추가합니다. 정보 패널 표시를 클릭하여 권한 편집기를 열어야 할 수도 있습니다. 주 구성원은 geo-fleet-engine@system.gserviceaccount.com이어야 하고 역할은 Pub/Sub publisher여야 합니다.

알림을 구독하도록 Cloud 프로젝트를 설정하려면 이 안내를 따르세요.

Fleet Engine API는 각 알림을 protobuf 및 json의 두 가지 데이터 형식으로 게시합니다. 각 알림의 데이터 형식은 PubsubMessage 속성에 표시되며, 키는 data_format, 값은 protobuf 또는 json입니다.

알림 스키마:

Protobuf

// A batch of notifications that is published by the Fleet Engine service using
// Cloud Pub/Sub in a single PubsubMessage.
message BatchNotification {
  // Required. At least one notification must exist.
  // List of notifications containing information related to changes in
  // Fleet Engine data.
  repeated Notification notifications = 1;
}

// A notification related to changes in Fleet Engine data.
// The data provides additional information specific to the type of the
// notification.
message Notification {
  // Required. At least one type must exist.
  // Type of notification.
  oneof type {
    // Notification related to changes in vehicle data.
    VehicleNotification vehicle_notification = 1;
  }
}

// Notification sent when a new vehicle was created.
message CreateVehicleNotification {
  // Required.
  // Vehicle must contain all fields that were set when it was created.
  Vehicle vehicle = 1;
}

// Notification sent when an existing vehicle is updated.
message UpdateVehicleNotification {
  // Required.
  // Vehicle must only contain name and fields that are present in the
  // field_mask field below.
  Vehicle vehicle = 1;

  // Required.
  // Contains vehicle field paths that were specifically requested
  // by the Provider.
  google.protobuf.FieldMask field_mask = 2;
}

// Notification related to changes in vehicle data.
message VehicleNotification {
  // Required. At least one type must be set.
  // Type of notification.
  oneof type {
    // Notification sent when a new vehicle was created.
    CreateVehicleNotification create_notification = 1;
    // Notification sent when an existing vehicle is updated.
    UpdateVehicleNotification update_notification = 2;
  }
}

JSON

BatchNotification: {
  "description": "A batch of notifications that is published by the Fleet Engine service using Cloud Pub/Sub in a single PubsubMessage.",
  "type": "object",
  "required": ["notifications"],
  "properties": {
    "notifications": {
      "description": "At least one notification must exist. List of notifications containing information related to changes in Fleet Engine data.",
      "type": "Notification[]"
    }
  }
}

Notification: {
  "description": "A notification related to changes in Fleet Engine data. The data provides additional information specific to the type of the notification.",
  "type": "object",
  "properties": {
    "vehicleNotification": {
      "description": "Notification related to changes in vehicle data.",
      "type": "VehicleNotification"
    }
  }
}

VehicleNotification: {
  "description": "Notification related to changes in vehicle data.",
  "type": "object",
  "properties": {
    "createNotification": {
      "description": "Notification sent when a new vehicle was created.",
      "type": "CreateVehicleNotification"
    },
    "updateNotification": {
      "description": "Notification sent when an existing vehicle is updated.",
      "type": "UpdateVehicleNotification"
    }
  }
}

CreateVehicleNotification: {
  "description": "Notification sent when a new vehicle was created.",
  "type": "object",
  "required": ["vehicle"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must contain all fields that were set when it was created.",
      "type": "Vehicle"
    }
  }
}

UpdateVehicleNotification: {
  "description": "Notification sent when an existing vehicle is updated.",
  "type": "object",
  "required": ["vehicle", "fieldMask"],
  "properties": {
    "vehicle": {
      "description": "Vehicle must only contain name and fields that are present in the fieldMask field below.",
      "type": "Vehicle"
    },
    "fieldMask": {
      "description": "Contains vehicle field paths that were specifically requested by the Provider.",
      "type": "FieldMask"
    }
  }
}