라스트 마일 Fleet 솔루션은 현재 일부 고객에게만 제공됩니다. 자세한 내용은 영업팀에 문의하세요.

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

Fleet 성능을 위한 Fleet Engine 시작하기

Fleet Engine Deliveries API를 사용하여 배송의 최초 마일과 라스트 마일에 대한 Fleet 활동을 모델링합니다. Android 및 iOS용 Driver SDK를 사용하거나 직접 HTTP REST 또는 gRPC 호출을 통해 이 API를 사용할 수 있습니다.

초기 설정

Google Cloud 콘솔에서 Fleet Engine Deliveries API를 구성합니다.

콘솔 내에서 수행할 단계와 승인을 위해 JSON 웹 토큰을 만드는 방법에 대한 자세한 내용은 인증 및 승인을 참조하세요.
콘솔 사용에 대한 자세한 내용은 Google Cloud Console 문서를 참조하세요.

설정 확인

서비스 계정을 만든 후 설정이 완료되었고 배달 차량을 만들 수 있는지 확인합니다. 설정을 즉시 확인하면 프로젝트를 설정할 때 발생할 수 있는 일반적인 승인 문제를 해결할 수 있습니다. 설정을 확인하는 방법에는 두 가지가 있습니다.

설정의 두 가지 주요 부분, 즉 gcloud 명령줄 유틸리티를 사용하여 승인 토큰 서명과 무료 체험판 제공 차량 생성을 테스트합니다. 자세한 내용은 설정 확인 가이드를 참고하세요.
Fleet Engine 인증 샘플 스크립트를 사용하여 설정을 테스트합니다.

클라이언트 라이브러리

원시 gRPC 또는 REST보다 더 나은 개발자 환경을 제공하려면 여러 일반적인 프로그래밍 언어로 클라이언트 라이브러리를 사용합니다. 서버 애플리케이션에 대한 클라이언트 라이브러리를 가져오는 방법은 클라이언트 라이브러리를 참조하세요.

이 문서의 Java 예에서는 사용자가 gRPC에 익숙하다고 가정합니다.

데이터 구조

Fleet Engine Deliveries API는 두 가지 데이터 구조를 사용하여 화물 수령 및 배송을 모델링합니다.

화물 운송에 사용되는 배송 수단입니다.
배송 수령 및 배송 작업

또한 작업을 사용하여 하루 동안 운전자 중단과 예약된 정류장을 모델링합니다.

배송 차량

배송 차량은 화물을 창고에서 배송 위치로, 수령 위치에서 창고로 운송합니다. 경우에 따라 상품을 수령 위치에서 배송 위치로 직접 운송할 수도 있습니다.

Driver SDK를 사용하여 Fleet Engine에서 DeliveryVehicle 객체를 만들고 배송 및 차량 추적을 위한 위치 업데이트를 전송합니다.

참고: DeliveryVehicle 객체에 최대 500개의 태스크와 300개의 남은 차량 여정 세그먼트를 할당할 수 있습니다.

태스크

차량이 낮 동안 수행하는 작업의 경우 작업 유형에 따라 작업을 할당합니다.

수령 및 배송의 경우 배송 작업을 할당합니다.
필요한 휴식 시간과 같이 운전자를 사용할 수 없는 경우에는 비가용성 작업을 할당합니다.
보관용 집 또는 고객 위치에서 운전하지 않는 작업의 경우 예약된 정차 작업을 할당합니다.

할당하는 각 작업에는 고유한 작업 ID가 있어야 하지만 여러 작업은 동일한 추적 ID를 공유할 수 있습니다. Fleet Engine은 각 태스크의 ETA 기간을 계산할 때 모든 태스크와 예측하도록 예약된 순서를 사용합니다. 작업 ID에 관한 자세한 내용은 작업 ID 가이드라인을 참조하세요.

Fleet Engine에서 태스크를 만들려면 Driver SDK 작업 관리자를 사용하세요.

배송 작업

배송 상품 수령 및 배송을 위한 배송 태스크를 만들고 다음 정보를 포함합니다.

수령 또는 배달 위치입니다.
운송장 번호 또는 ID
작업을 완료하거나, 주차장을 찾거나, 핸드오프 위치로 걸어가기 위한 추가 시간을 고려하기 위한 체류 시간입니다.
고유한 작업 ID입니다. 작업 ID 가이드라인을 참고하세요.

자세한 내용은 다음 항목을 참조하세요.

Android

iOS

GMTD DeliveryTaskManager를 전송했습니다.
GMTSTaskType

사용할 수 없는 작업

비가용성 작업에는 차량 주유를 위한 휴식 또는 운전자 휴식 휴식과 같이 차량을 수령 또는 배달할 수 없는 기간이 포함됩니다.

다음 정보를 사용하여 비가용성 태스크를 만듭니다.

광고 시점의 길이입니다.
원하는 경우 시점 위치를 지정합니다. 특정 위치를 제공할 필요는 없지만, 이렇게 하면 하루 중 더 정확한 도착예정시간을 제공할 수 있습니다.

자세한 내용은 다음 항목을 참조하세요.

Android

예약된 사용 중지

iOS

GMTD DeliveryTaskManager를 전송했습니다.
GMTSTaskType

예약된 중지 작업

예약 정차 작업을 만들어 배달 차량이 진행해야 하는 정류장을 모델링합니다. 예를 들어 동일한 위치의 다른 배송 또는 수령과는 별개로 특정 위치의 일일 예약된 수거 정류장에 대한 예약된 중지 태스크를 만듭니다. 또한 드롭박스에서 또는 서비스 센터 및 서비스 지점에서 피더-차량 간 환승 또는 정류장을 모델링하기 위한 수거에 대한 예약된 정차 작업을 만들 수도 있습니다.

자세한 내용은 다음 항목을 참조하세요.

Android

예정된 경유지

iOS

GMTD DeliveryTaskManager를 전송했습니다.
GMTSTaskType

작업 ID 가이드라인

작업 ID를 만들 때는 다음 콘텐츠 및 형식 가이드라인을 따르세요.

고유한 작업 ID 만들기
개인 식별 정보 (PII) 또는 일반 텍스트 데이터를 노출하지 마세요.
유효한 유니코드 문자열을 사용하세요.
64자(영문 기준) 이하여야 합니다.
ASCII 문자 '/', ':', '\', '?', '#'은 포함하지 마세요.
유니코드 정규화 양식 C에 따라 정규화합니다.

다음은 좋은 작업 ID의 몇 가지 예입니다.

566c33d9-2a31-4b6a-9cd4-80ba1a0c643b
e4708eabcfa39bf2767c9546c9273f747b4626e8cc44e9630d50f6d129013d38
NTA1YTliYWNkYmViMTI0ZmMzMWFmOWY2NzNkM2Jk

다음 표는 지원되지 않는 작업 ID의 예를 보여줍니다.

지원되지 않는 작업 ID	이유
8/31/2019-20:48-46.70746,-130.10807,-85.17909,61.33680	개인 식별 정보 및 문자 요구사항(쉼표, 마침표, 콜론, 슬래시) 위반
JohnDoe-577b484da26f-Cupertino-SantaCruz	개인 식별 정보(PII) 요건 위반
4R0oXLToF"112 Summer Dr. East Hartford, CT06118"577b484da26f8a	개인 식별 정보 및 문자 요구사항(공백, 쉼표, 따옴표) 위반 64자(영문 기준) 초과

추가 리소스

각 데이터 구조에 포함된 특정 필드를 보려면 DeliveryVehicle(gRPC, REST) 및 Task (gRPC, REST)에 대한 API 참조 문서를 확인하세요.

차량 수명

DeliveryVehicle 객체는 퍼스트 마일 또는 라스트 마일 배송 차량을 나타냅니다. 다음을 사용하여 DeliveryVehicle 객체를 만듭니다.

Fleet Engine API를 호출하는 데 사용되는 서비스 계정이 포함된 Google Cloud 프로젝트의 프로젝트 ID입니다.
고객 소유 차량 ID입니다.

차량마다 고유한 차량 ID를 사용합니다. 원래 차량에 진행 중인 작업이 없으면 차량 ID를 재사용하지 마세요.

Fleet Engine은 7일 후에 UpdateDeliveryVehicle를 사용하여 업데이트되지 않은 DeliveryVehicle 객체를 자동으로 삭제합니다. 차량이 있는지 확인하는 방법은 다음과 같습니다.

UpdateDeliveryVehicle를 호출합니다.
NOT_FOUND 오류가 발생하면 CreateDeliveryVehicle를 호출하여 차량을 다시 만듭니다. 통화로 인해 차량이 반환되는 경우는 계속 업데이트할 수 있습니다.

차량 속성

DeliveryVehicle 항목에 DeliveryVehicleAttribute의 반복되는 필드가 포함되어 있습니다. ListDeliveryVehicles API에는 반환되는 DeliveryVehicle 항목을 지정된 속성이 있는 항목으로 제한할 수 있는 filter 필드가 포함되어 있습니다. DeliveryVehicleAttribute는 Fleet Engine 라우팅 동작에 영향을 주지 않습니다.

이 필드는 사용자에게 표시될 수 있으므로 개인 식별 정보 (PII) 또는 민감한 정보를 속성에 포함하지 마세요.

태스크 수명

Deliveries API gRPC 또는 REST 인터페이스를 사용하여 Fleet Engine에서 태스크를 생성, 업데이트, 쿼리할 수 있습니다.

Task 객체에는 수명 주기 동안 진행 상황을 추적하는 상태 필드가 있습니다. 값은 열기에서 닫힘으로 이동합니다. 새 태스크는 다음 중 하나를 나타내는 OPEN 상태로 생성됩니다.

작업이 아직 배송 차량에 할당되지 않았습니다.
배송 차량이 아직 작업에 할당된 차량 정류장을 통과하지 않았습니다.

작업 가이드라인

차량이 OPEN 상태인 경우에만 작업을 할당할 수 있습니다.

작업을 취소하려면 차량 정류장 목록에서 작업을 삭제하면 작업 상태가 자동으로 CLOSED로 설정됩니다.

작업의 차량이 작업의 차량 중지를 완료하면 다음을 실행합니다.

작업의 결과 필드를 SUCCEEDED 또는 FAILED로 업데이트합니다.

참고: 태스크 완료 전이나 후에 언제든지 태스크 결과를 설정할 수 있지만 한 번만 설정할 수 있습니다.
이벤트의 타임스탬프를 지정합니다.

그러면 자바스크립트 Fleet 추적 라이브러리가 태스크 결과를 표시하고 태스크 상태가 자동으로 CLOSED로 설정됩니다. 자세한 내용은 자바스크립트 Fleet 추적 라이브러리로 Fleet 추적을 참고하세요.

차량과 마찬가지로 Fleet Engine은 7일이 지나도 업데이트되지 않은 태스크를 삭제하며, 이미 존재하는 ID로 태스크를 만들려고 하면 오류가 반환됩니다.

참고: Fleet Engine은 태스크를 명시적으로 삭제하는 기능을 지원하지 않습니다. 이 서비스는 7일이 지나면 업데이트하지 않고 태스크를 자동으로 삭제합니다. 작업 데이터를 7일보다 오래 보관하려면 해당 기능을 직접 구현해야 합니다.

태스크 속성

Task 항목에는 반복되는 TaskAttribute 필드가 포함되어 있으며 이 필드는 문자열, 숫자, 부울의 세 가지 유형 중 하나의 값을 가질 수 있습니다. ListTasks API에는 반환되는 Task 항목을 지정된 속성이 있는 항목으로 제한할 수 있는 filter 필드가 포함되어 있습니다. 태스크 속성은 Fleet Engine 라우팅 동작에 영향을 미치지 않습니다.

개인 식별 정보 (PII) 또는 기타 민감한 정보는 사용자에게 표시될 수 있으므로 속성에 포함하지 마세요.

차량 및 작업 수명 주기 관리

알림: 내부 시스템은 Fleet Engine Deliveries API가 사용자를 대신하여 보강하는 신뢰할 수 있는 데이터 소스 역할을 합니다.

시스템에서 차량 및 작업 수명 주기를 관리하려면 Fleet Engine Deliveries API를 사용하여 차량 및 관련 작업을 생성, 업데이트, 추적하세요.

동시에 드라이버 애플리케이션은 Fleet Engine과 직접 통신하여 기기 위치와 경로 정보를 업데이트합니다. 이 모델을 사용하면 Fleet Engine이 실시간 위치를 효율적으로 관리할 수 있습니다 추적 라이브러리로 위치를 직접 전송하면 이를 사용하여 소비자에게 주문 상태를 업데이트할 수 있습니다.

예를 들어 다음과 같은 시나리오가 있다고 가정해 보겠습니다.

배달 기사 근처에 있습니다. 드라이버 애플리케이션은 위치를 Fleet Engine으로 전송합니다.
Fleet Engine은 기기 위치를 추적 라이브러리로 전송하고 소비자 애플리케이션은 이 추적 라이브러리를 사용하여 소비자에게 패키지의 근접성을 알립니다.
배송 기사는 배송을 완료한 후 드라이버 애플리케이션의 '배송 배송됨' 버튼을 클릭합니다.
'배송 완료' 작업은 필요한 비즈니스 유효성 검사 및 확인 단계를 수행하는 백엔드 시스템으로 정보를 전송합니다.
시스템이 작업을 SUCCEEDED로 확인하고 Deliveries API를 사용하여 Fleet Engine을 업데이트합니다.

다음 다이어그램은 이러한 프로세스를 일반적인 수준에서 보여줍니다. 또한 시스템, 클라이언트, Fleet Engine 간의 표준 관계도 보여줍니다.

Deliveries API 통합 다이어그램>

클라이언트 토큰 관리

드라이버 애플리케이션에서 생성되어 Fleet Engine으로 직접 전송되는 위치 업데이트에는 승인 토큰이 필요합니다. 클라이언트에서 Fleet Engine으로 업데이트를 처리하는 데 권장되는 방법은 다음과 같습니다.

Fleet Engine Delivery 신뢰할 수 없는 운전자 사용자 서비스 계정 역할을 사용하여 토큰을 생성합니다.
드라이버 애플리케이션에 제한된 범위의 토큰을 제공합니다. 이 범위를 사용하면 Fleet Engine의 기기 위치만 업데이트할 수 있습니다.

이 접근 방식을 사용하면 신뢰도가 낮은 환경으로 간주되는 휴대기기에서 발생하는 호출이 최소 권한 원칙을 준수합니다.

기타 서비스 계정 역할

대신 특정 작업 업데이트와 같이 신뢰할 수 없는 드라이버 역할로 제한된 것 이상으로 직접 Fleet Engine 업데이트를 수행하도록 드라이버 애플리케이션을 승인하려면 신뢰할 수 있는 드라이버 역할을 사용하면 됩니다. 신뢰할 수 있는 드라이버 역할을 사용하는 모델에 대한 자세한 내용은 신뢰할 수 있는 드라이버 모델을 참조하세요.

신뢰할 수 없고 신뢰할 수 있는 드라이버 역할의 용도에 관한 자세한 내용은 Cloud 프로젝트 설정을 참고하세요.

근무일 모델링

다음 표에서는 운송 및 물류 회사의 관점에서 1마일 또는 라스트 마일 배송 기사가 어떻게 근무하는지 설명합니다. 회사는 세부 사항에 차이가 있을 수 있지만 근무일을 어떻게 모델링할 수 있는지는 확인할 수 있습니다.

시간	활동	모델링
하루를 시작한 후 24시간 이내	운영자가 배송 차량 또는 경로에 배송물을 할당합니다.	Fleet Engine에서 배송, 수령, 파손 등의 작업을 미리 만들 수 있습니다. 예를 들어 배송 수령 태스크, 배송 배송 태스크, 예약 불가 또는 예약된 중지를 만들 수 있습니다. 배달 패키지 세트와 전달되어야 하는 순서가 확정되면 차량에 작업을 할당합니다.
하루의 시작	운전자는 드라이버 앱에 로그인하여 창고에서 하루를 시작합니다.	Delivery Driver API 초기화 필요에 따라 Fleet Engine에서 배송 수단을 만듭니다.
	운전자가 배송 차량에 화물을 적재하고 배송 상품을 스캔합니다.	배송 배송 태스크가 미리 생성되지 않았다면 스캔 시 배송 배송 태스크를 만듭니다.
	드라이버가 실행할 작업의 순서를 확인합니다.	미리 생성되지 않은 경우 배송 수령 작업, 예약된 이용 불가, 예정된 정류장을 만듭니다.
	드라이버가 디포를 떠나고 완료될 다음 작업 수를 커밋합니다.	완료 순서를 커밋하여 차량에 모든 작업 또는 작업의 하위 집합을 할당합니다.
	운전자가 배송 상품을 배송합니다.	배달 정류장에 도착한 후 정류장에 도착한 차량과 관련된 작업을 실행합니다. 배송 상품을 배송한 후 배송 태스크를 종료하고 필요한 경우 배송 상태 및 기타 메타 정보를 저장합니다. 정류장에서 모든 작업을 완료한 후 다음 정류장으로 운전을 시작하기 전에 차량이 정류장을 완료함 및 다음 정류장으로 이동하는 차량과 관련된 작업을 실행합니다.
	운전자가 피더 차량과 만나 추가 배송품을 배송 차량으로 전송합니다.	피더와 배송 차량 간의 환승을 위한 만남의 장소는 예정된 정류장으로 모델링해야 합니다. 배송 상품을 이전 및 스캔한 후 배송 태스크를 생성합니다(아직 생성되지 않은 경우). 그런 다음 차량에 작업을 할당하고 작업 순서를 업데이트하여 작업 완료 순서를 업데이트합니다.
	운전자가 승차 요청 알림을 받습니다.	수령 요청을 수락한 후 배송 수령 태스크를 만듭니다. 그런 다음 차량에 작업을 할당하고 작업 순서를 업데이트하여 작업 실행 순서를 업데이트합니다.
정오	운전자가 점심시간입니다.	위치가 예약 불가 작업과 연결된 경우 다른 작업처럼 처리합니다. 정류장에 도착한 차량, 차량이 정류장을 완료하고, 다음 정류장으로 이동하는 차량과 관련된 작업을 실행합니다. 그렇지 않으면 광고 시점이 끝날 때까지 추가 작업이 필요하지 않습니다. 다음 작업과 나머지 작업을 확인하고 작업 순서를 업데이트하여 작업을 삭제합니다.
	운전자가 배송 상품을 수령합니다.	배달 정류장처럼 모델링되었습니다. 정류장에 도착한 차량 및 작업 종료와 관련된 작업을 실행하고 선택적으로 배송 상태 및 기타 메타 정보 저장과 관련된 작업을 실행합니다. 정류장에서 모든 작업을 완료한 후 다음 정류장으로 운전을 시작하기 전에 차량이 정류장을 완료함 및 다음 정류장으로 이동하는 차량과 관련된 작업을 실행합니다. 참고: 정확한 결제를 위해 모든 수령에 해당하는 배송 태스크가 있어야 합니다. 당일 운전자가 같은 경로에 있는 다른 위치로 픽업이 배송되는 경우 해당 배송 작업을 경로의 다른 배송 작업과 모델링하는 것이 좋습니다. 기사가 창고로 승차 위치를 다시 가져오는 경우 창고 목적지에서 배송 작업을 만드는 것이 좋습니다.
	배송 기사가 보관함에서 배송 상품을 수령하기 위해 정해진 시간에 정차합니다.	다른 승차장과 동일한 방식으로 모델링됩니다. 정류장에 도착한 차량 및 작업 종료와 관련된 작업을 실행합니다. 정류장에서 모든 작업을 완료하고 다음 정류장으로 운전을 시작한 후 차량이 정류장을 완료함 및 다음 정류장으로 이동하는 차량과 관련된 작업을 실행합니다.
	운전자가 배송 상품이 다른 장소로 우회되고 있다는 알림을 받습니다.	원래 배송 배송 태스크 상태를 '완료됨'으로 설정하고 새 배송 위치에 대한 새 배송 배송 태스크를 만듭니다. 자세한 내용은 배송 경로 다시 지정을 참고하세요.
	운전자가 택배를 전송하려고 했지만 실패했습니다.	이는 전송 중지가 성공한 경우와 유사하게 모델링되어 전송 태스크가 완료된 것으로 표시합니다. 정류장에 도착한 차량과 관련된 작업을 실행합니다. 배송 물품을 배송하지 못하면 태스크를 종료하고, 원하는 경우 배송 상태 및 기타 메타 정보를 저장합니다. 정류장에서 모든 작업을 완료한 후 다음 정류장으로 운전을 시작하기 전에 차량이 정류장을 완료함 및 다음 정류장으로 이동하는 차량과 관련된 작업을 실행합니다.
	운전기사에게 배송을 보류 (배송하지 말 것)하라는 알림을 받았습니다.	알림을 수신하고 확인한 후 작업 상태를 COMPLETED로 설정합니다.
	운전자가 다음 배송 상품을 배송하라는 알림을 받고 약정 배송 주문을 변경했습니다.	작업 순서를 업데이트합니다.
	운전자가 잘못된 배송 상품을 배송하기로 선택합니다.	작업 순서를 업데이트한 후 평소와 같이 진행합니다.
	운전자가 단일 위치로 여러 화물을 배송합니다.	이는 단일 배송 경유지와 유사하게 모델링됩니다. 정류장에 도착한 후 정류장에 도착한 차량과 관련된 작업을 실행합니다. 각 배송 상품을 배송한 후 각 태스크를 닫고 배송 상태 및 기타 메타 정보를 저장합니다(선택사항). 정류장에서 모든 작업을 완료한 후 다음 정류장으로 운전을 시작하기 전에 차량이 정류장을 완료함 및 다음 정류장으로 이동하는 차량과 관련된 작업을 실행합니다.
전체 과정 종료 시간	운전자가 창고로 돌아옵니다.	배송 기사가 경로 중에 상품을 수령한 상태로 창고로 돌아오는 경우 정확한 결제를 위해 각 패키지를 배송 태스크로 생성하고 마감해야 합니다. 다른 배송 경유지와 마찬가지로 창고를 모델링하면 됩니다. 해당 창고가 배송 경유지로 사용되지 않는 경우에도 원하는 경우 해당 창고를 예약된 정류장으로 모델링할 수 있습니다. 정류장을 모델링하면 운전자가 차고지에 도착하는 경로를 확인하고 예상 도착 시간을 파악할 수 있습니다.

위치 업데이트 작동 방식

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

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

차량 위치 업데이트를 제공하는 방법과 관계없이 백엔드는 배송 차량이 정류장으로 가는 중 (물류장 포함) 및 정류장에 도착할 때 Fleet Engine을 업데이트해야 합니다. Fleet Engine은 이러한 이벤트를 자동으로 감지하지 않습니다.

차량 정류장 및 배송 위치

차량 정류장은 배송 차량이 배송 작업 또는 다른 작업을 완료하는 곳입니다. 이는 로딩 도크 또는 도로에 맞춰진 위치와 같은 액세스 지점입니다.

배송 위치는 배송품을 배달 또는 수령하는 위치입니다. 배송 위치에 오기 위해서는 차량 정류장에서 걸어야 할 수 있습니다.

예를 들어 운전자가 쇼핑몰의 매장으로 배송품을 배달할 때 배송 차량은 매장과 가장 가까운 입구 근처의 쇼핑몰 주차장에 정차합니다. 차량 정류장입니다. 운전자는 차량 정류장에서 출발하여 매장이 위치한 쇼핑몰 내 위치로 이동합니다. 배송 위치입니다.

사용자에게 최상의 배송 추적 환경을 제공하려면 배송 작업을 차량 정류장에 할당하는 방법을 고려해야 하며, 배송 진행 상황을 확인할 수 있도록 배송 작업에 남은 차량 정류장 수가 사용자에게 보고된다는 점에 유의하세요.

예를 들어 운전자가 단일 사무실 건물로 많은 배송을 하는 경우 모든 배송 작업을 단일 차량 정류장에 할당하는 것이 좋습니다. 각 배송 작업이 자체 차량 정류장에 할당되면 배송 추적 환경이 사용자에게 도움이 되지 않습니다. 차량이 목적지 전 제한된 수의 차량 정류장 내에 있어야 추적이 가능하기 때문입니다. 짧은 시간 내에 많은 차량 정류장이 완료되더라도 사용자가 배송 진행 상황을 추적하는 데 사용할 시간이 많지 않습니다.

모바일 SDK 사용

드라이버 SDK를 호출하기 전에 먼저 초기화해야 합니다.

Delivery Driver API 초기화

Driver SDK에서 Delivery Driver API를 초기화하기 전에 Navigation SDK를 초기화해야 합니다. 그런 다음 아래 예와 같이 Delivery Driver API를 초기화합니다.

static final String PROVIDER_ID = "provider-1234";
static final String VEHICLE_ID = "vehicle-8241890";

NavigationApi.getNavigator(
   this, // Activity.
   new NavigatorListener() {
     @Override
     public void onNavigatorReady(Navigator navigator) {
       DeliveryDriverApi.createInstance(DriverContext.builder(getApplication())
         .setNavigator(navigator)
         .setProviderId(PROVIDER_ID)
         .setVehicleId(VEHICLE_ID)
         .setAuthTokenFactory((context) -> "JWT") // AuthTokenFactory returns JWT for call context.
         .setRoadSnappedLocationProvider(NavigationApi.getRoadSnappedLocationProvider(getApplication()))
         .setNavigationTransactionRecorder(NavigationApi.getNavigationTransactionRecorder(getApplication()))
         .setStatusListener((statusLevel,statusCode,statusMsg) -> // Optional, surfaces polling errors.
             Log.d("TAG", String.format("New status update. %s, %s, %s", statusLevel, statusCode, statusMsg)))
         .build));
     }
     @Override
     public void onError(int errorCode) {
       Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
     }
   });

사용 사례

이 섹션에서는 Deliveries API를 사용하여 일반적인 사용 사례를 모델링하는 방법을 설명합니다.

고유 개체 식별자

REST 호출에 사용되는 고유 항목 식별자의 형식과 값은 Fleet Engine에 불투명합니다. 자동 증분 ID를 사용하지 말고 식별자에 운전자 전화번호와 같은 개인 식별 정보 (PII)가 포함되어 있지 않은지 확인하세요.

차량 만들기

Driver SDK에서 또는 gRPC나 REST를 사용하는 서버 환경에서 차량을 만들 수 있습니다.

gRPC

새 차량을 만들려면 Fleet Engine에 CreateDeliveryVehicle 호출을 전송합니다. CreateDeliveryVehicleRequest 객체를 사용하여 새 배송 차량의 속성을 정의합니다. Name 필드에 지정된 모든 값은 사용자 지정 ID에 대한 API 안내에 따라 무시됩니다. DeliveryVehicleId 필드를 사용하여 차량 ID를 설정해야 합니다.

DeliveryVehicle를 만들 때 선택적으로 다음 필드를 지정할 수 있습니다.

특성
LastLocation
유형

다른 필드는 설정하지 마세요. 그러면 해당 필드가 읽기 전용이거나 UpdateDeliveryVehicle 호출로만 업데이트될 수 있으므로 Fleet Engine이 오류를 반환합니다.

선택적 필드를 설정하지 않고 차량을 만들려면 CreateDeliveryVehicleRequest에서 DeliveryVehicle 필드를 설정하지 않은 상태로 두면 됩니다.

다음 예에서는 자바 gRPC 라이브러리를 사용하여 차량을 만드는 방법을 보여줍니다.

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String VEHICLE_ID = "vehicle-8241890"; // Avoid auto-incrementing IDs.

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    String parent = "providers/" + PROJECT_ID;
    DeliveryVehicle vehicle = DeliveryVehicle.newBuilder()
      .addAttributes(DeliveryVehicleAttribute.newBuilder()
        .setKey("route_number").setValue("1"))  // Opaque to the Fleet Engine
      .build();

    // Vehicle request
    CreateDeliveryVehicleRequest createVehicleRequest =
      CreateDeliveryVehicleRequest.newBuilder()  // No need for the header
          .setParent(parent)
          .setDeliveryVehicleId(VEHICLE_ID)     // Vehicle ID assigned by the Provider
          .setDeliveryVehicle(vehicle)
          .build();

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

    try {
      DeliveryVehicle createdVehicle =
        deliveryService.createDeliveryVehicle(createVehicleRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

서버 환경에서 차량을 만들려면 CreateDeliveryVehicle에 대한 HTTP REST 호출을 실행합니다.

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles?deliveryVehicleId=<id>

<id>는 차량 내 배송 차량의 고유 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

POST 본문은 생성할 DeliveryVehicle 항목을 나타냅니다. 다음과 같은 선택적 필드를 지정할 수 있습니다.

속성
lastLocation
유형

curl 명령어 예시:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
--data-binary @- << EOM
{
  "attributes": [{"key": "model", "value": "sedan"}],
  "lastLocation": {"location": {"latitude": 12.1, "longitude": 14.5}}
}
EOM

Fleet Engine은 사용자 지정 ID에 대한 API 안내에 따라 DeliveryVehicle 항목의 name 필드를 무시합니다. 다른 필드는 설정하지 마세요. 그러면 해당 필드가 읽기 전용이거나 UpdateDeliveryVehicle 호출을 사용해서만 업데이트될 수 있으므로 Fleet Engine이 오류를 반환합니다.

필드를 설정하지 않고 차량을 만들려면 POST 요청의 본문을 비워 둡니다. 그런 다음 새로 생성된 차량이 POST URL의 deliveryVehicleId 매개변수에서 차량 ID를 추출합니다.

curl 명령어 예시:

# Set $JWT, $PROJECT_ID, and $VEHICLE_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?deliveryVehicleId=${VEHICLE_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}"

배송 수령 작업 만들기

Driver SDK 또는 gRPC나 REST를 사용하여 서버 환경에서 배송 수령 태스크를 만들 수 있습니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 배송 수령 태스크를 만드는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

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

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

서버 환경에서 배송 수령 태스크를 만들려면 CreateTask에 대한 HTTP REST 호출을 실행합니다.

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id>는 작업의 고유 식별자입니다. 배송의 운송장 번호가 아니어야 합니다. 시스템에 작업 ID가 없으면 범용 고유 식별자 (UUID)를 생성할 수 있습니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 Task 항목이 포함되어야 합니다.

필수 필드:

필드	값
유형	Type.PICKUP
state	State.OPEN
trackingId	배송 추적에 사용하는 번호 또는 식별자입니다.
plannedLocation	작업을 완료할 위치입니다(이 경우 배송 수령 위치입니다).
taskDuration	수령 위치에서 상품을 수령하는 데 걸리는 예상 시간(초)입니다.

선택적 필드:

필드	값
targetTimeWindow	작업이 완료되어야 하는 기간입니다. 이 문제는 라우팅 동작에는 영향을 미치지 않습니다.
속성	커스텀 Task 속성 목록 각 속성에는 고유한 키가 있어야 합니다.

항목의 다른 모든 필드는 생성 시 무시됩니다. 요청에 할당된 deliveryVehicleId이 있으면 Fleet Engine에서 예외가 발생합니다. 작업은 UpdateDeliveryVehicleRequest를 사용하여 할당합니다. 자세한 내용은 차량에 작업 할당 및 UpdateDeliveryVehicleRequest를 참고하세요.

curl 명령어 예시:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "PICKUP",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

배송 태스크 만들기

Driver SDK에서 또는 gRPC나 REST를 사용하여 서버 환경에서 배송 배송 태스크를 만듭니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 배송 태스크를 만드는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("my-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .setTargetTimeWindow(
    TimeWindow.newBuilder()
      .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
      .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
  .addAttributes(TaskAttribute.newBuilder().setKey("foo").setStringValue("value"))
  .addAttributes(TaskAttribute.newBuilder().setKey("bar").setNumberValue(10))
  .addAttributes(TaskAttribute.newBuilder().setKey("baz").setBoolValue(false))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(task)              // Initial state
      .build();

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

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

gRPC 또는 REST를 사용하여 서버 환경에서 배송 태스크를 만들려면 CreateTask에 대한 HTTP REST 호출을 실행합니다.

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id>는 작업의 고유 식별자입니다. 배송의 운송장 번호가 아니어야 합니다. 시스템에 작업 ID가 없으면 범용 고유 식별자 (UUID)를 생성할 수 있습니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 Task 항목이 포함되어야 합니다.

필수 필드:

필드	값
유형	Type.DELIVERY
state	State.OPEN
trackingId	배송 추적에 사용하는 번호 또는 식별자입니다.
plannedLocation	태스크가 완료될 위치입니다. 이 경우 배송의 배송지 위치입니다.
taskDuration	배송 위치에 상품을 반납하는 데 걸리는 예상 시간(초)입니다.

선택적 필드:

필드	값
targetTimeWindow	작업이 완료되어야 하는 기간입니다. 이 문제는 라우팅 동작에는 영향을 미치지 않습니다.
속성	커스텀 Task 속성 목록 각 속성에는 고유한 키가 있어야 합니다.

항목의 다른 모든 필드는 생성 시 무시됩니다. 요청에 할당된 DeliveryVehicleId가 포함된 경우 Fleet Engine에서 예외가 발생합니다. 작업은 UpdateDeliveryVehicleRequest를 사용하여 할당합니다. 자세한 내용은 차량에 작업 할당 및 UpdateDeliveryVehicleRequest를 참고하세요.

curl 명령어 예시:

# Set $JWT, $PROJECT_ID, $TRACKING_ID, and $TASK_ID in the local
# environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "DELIVERY",
  "state": "OPEN",
  "trackingId": "${TRACKING_ID}",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "90s",
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

태스크 일괄 생성

gRPC 또는 REST를 사용하여 서버 환경에서 태스크 배치를 만들 수 있습니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 배달 및 수령에 대한 태스크와 동일한 위치에서 태스크를 하나씩 만드는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Delivery Task settings
Task deliveryTask = Task.newBuilder()
  .setType(Task.Type.DELIVERY)
  .setState(Task.State.OPEN)
  .setTrackingId("delivery-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Delivery Task request
CreateTaskRequest createDeliveryTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8312508")  // Task ID assigned by the Provider
      .setTask(deliveryTask)      // Initial state
      .build();

// Pickup Task settings
Task pickupTask = Task.newBuilder()
  .setType(Task.Type.PICKUP)
  .setState(Task.State.OPEN)
  .setTrackingId("pickup-tracking-id")
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Pickup Task request
CreateTaskRequest createPickupTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header or parent fields
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTask(pickupTask)        // Initial state
      .build();

// Batch Create Tasks settings
String parent = "providers/" + PROJECT_ID;

// Batch Create Tasks request
BatchCreateTasksRequest batchCreateTasksRequest =
  BatchCreateTasksRequest.newBuilder()
      .setParent(parent)
      .addRequests(createDeliveryTaskRequest)
      .addRequests(createPickupTaskRequest)
      .build();

// Error handling
// If Fleet Engine does not have any task(s) with these task ID(s) and the
// credentials of the requestor pass, the service creates the task(s)
// successfully.

try {
  BatchCreateTasksResponse createdTasks = deliveryService.batchCreateTasks(
    batchCreateTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

서버 환경에서 배송 및 수령 태스크를 만들려면 BatchCreateTasks에 대한 HTTP REST 호출을 실행합니다.

POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:batchCreate

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 BatchCreateTasksRequest 항목이 포함되어야 합니다.

필수 필드:

필드 값

요청 배열<CreateTasksRequest>
선택적 필드:

필드 값

헤더 `DeliveryRequestHeader`

필드	값
요청	배열<`CreateTasksRequest`>

필드	값
헤더	`DeliveryRequestHeader`

requests의 각 CreateTasksRequest 요소는 CreateTask 요청과 동일한 유효성 검사 규칙을 전달해야 합니다. 단, parent 및 header 필드는 선택사항입니다. 설정된 경우 최상위 BatchCreateTasksRequest에 있는 각 필드와 동일해야 합니다. 각각에 대한 특정 유효성 검사 규칙은 배송 수령 태스크 만들기 및 배송 태스크 만들기를 참조하세요.

자세한 내용은 BatchCreateTasks에 대한 API 참조 문서(gRPC, REST)를 참조하세요.

curl 명령어 예시:

# Set $JWT, $PROJECT_ID, $DELIVERY_TRACKING_ID, $DELIVERY_TASK_ID,
# $PICKUP_TRACKING_ID, and $PICKUP_TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks:batchCreate" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "requests" : [
    {
      "taskId": "${DELIVERY_TASK_ID}",
      "task" : {
        "type": "DELIVERY",
        "state": "OPEN",
        "trackingId": "${DELIVERY_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    },
    {
      "taskId": "${PICKUP_TASK_ID}",
      "task" : {
        "type": "PICKUP",
        "state": "OPEN",
        "trackingId": "${PICKUP_TRACKING_ID}",
        "plannedLocation": {
          "point": {
              "latitude": -6.195139,
              "longitude": 106.820826
          }
        },
        "taskDuration": "90s"
      }
    }
  ]
}
EOM

예약된 사용 중지

Driver SDK 또는 gRPC나 REST를 사용하는 서버 환경에서 사용할 수 없음을 나타내는 작업 (예: 운전자 고장 또는 차량 주유)을 만들 수 있습니다. 예약된 사용 불가 작업에는 추적 ID가 포함되면 안 됩니다. 선택사항으로 위치를 제공할 수도 있습니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 비가용성 태스크를 만드는 방법을 보여줍니다.

    static final String PROJECT_ID = "my-delivery-co-gcp-project";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String parent = "providers/" + PROJECT_ID;
    Task task = Task.newBuilder()
      .setType(Task.Type.UNAVAILABLE)
      .setState(Task.State.OPEN)
      .setTaskDuration(
        Duration.newBuilder().setSeconds(60 * 60))  // 1hr break
      .build();

    // Task request
    CreateTaskRequest createTaskRequest =
      CreateTaskRequest.newBuilder()  // No need for the header
          .setParent(parent)          // Avoid using auto-incrementing IDs for the taskId
          .setTaskId("task-8241890")  // Task ID assigned by the Provider
          .setTask(task)              // Initial state
          .build();

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

    try {
      Task createdTask = deliveryService.createTask(createTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case ALREADY_EXISTS:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

서버 환경에서 사용 불가 태스크를 만들려면 CreateTask에 대한 HTTP REST 호출을 실행합니다.

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id>는 작업의 고유 식별자입니다. 시스템에 작업 ID가 없으면 범용 고유 식별자 (UUID)를 생성할 수 있습니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 Task 항목이 포함되어야 합니다.

필수 필드:

필드 값

유형 Type.UNAVAILABLE

state State.OPEN

taskDuration 광고 시점의 길이(초)입니다.
선택적 필드:

필드 값

plannedLocation 특정 위치에서 촬영해야 하는 경우 휴식 위치입니다.

필드	값
유형	Type.UNAVAILABLE
state	State.OPEN
taskDuration	광고 시점의 길이(초)입니다.

필드	값
plannedLocation	특정 위치에서 촬영해야 하는 경우 휴식 위치입니다.

curl 명령어 예시:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "UNAVAILABLE",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "300s"
    }
    EOM

예정된 경유지

Driver SDK 또는 gRPC나 REST를 사용하여 서버 환경에서 예약된 중지 작업을 만들 수 있습니다. 예약된 중지 작업에는 추적 ID가 포함되지 않을 수 있습니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 예약 중지 태스크를 만드는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String parent = "providers/" + PROJECT_ID;
Task task = Task.newBuilder()
  .setType(Task.Type.SCHEDULED_STOP)
  .setState(Task.State.OPEN)
  .setPlannedLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .setTaskDuration(
    Duration.newBuilder().setSeconds(2 * 60))
  .build();

// Task request
CreateTaskRequest createTaskRequest =
  CreateTaskRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setTaskId("task-8241890")  // Task ID assigned by the Provider
      .setTrip(task)              // Initial state
      .build();

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

try {
  Task createdTask = deliveryService.createTask(createTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case ALREADY_EXISTS:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

서버 환경에서 예약된 중지 태스크를 만들려면 CreateTask에 대한 HTTP REST 호출을 실행합니다.

`POST https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks?taskId=<id>`

<id>는 작업의 고유 식별자입니다. 시스템에 작업 ID가 없으면 범용 고유 식별자 (UUID)를 생성할 수 있습니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 Task 항목이 포함되어야 합니다.

필수 필드:

필드 값

유형 Type.SCHEDULED_STOP

state State.OPEN

plannedLocation 정류장의 위치입니다.

taskDuration 예상 정류장 시간(초)입니다.
선택적 필드:
- 없음

필드	값
유형	Type.SCHEDULED_STOP
state	State.OPEN
plannedLocation	정류장의 위치입니다.
taskDuration	예상 정류장 시간(초)입니다.

curl 명령어 예시:

    # Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
    curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "type": "SCHEDULED_STOP",
      "state": "OPEN",
      "plannedLocation": {
         "point": {
            "latitude": -6.195139,
            "longitude": 106.820826
         }
      },
      "taskDuration": "600s"
    }
    EOM

목표 기간 설정

타겟 기간은 작업이 완료되어야 하는 TimeWindow입니다. 예를 들어 배달 수신자에게 배송 기간을 알리면 태스크 목표 기간을 사용하여 이 기간을 캡처하고 이 필드를 사용하여 알림을 생성하거나 이동 후 실적을 분석할 수 있습니다.

대상 기간은 시작 시간과 종료 시간으로 구성되며 모든 작업 유형에서 설정할 수 있습니다. 대상 기간은 라우팅 동작에 영향을 미치지 않습니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 태스크 기간을 설정하는 방법을 보여줍니다.

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String TASK_ID = "task-8241890";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Task settings
    String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
    Task task = Task.newBuilder()
      .setName(taskName)
      .setTargetTimeWindow(
        TimeWindow.newBuilder()
          .setStartTime(Timestamp.newBuilder().setSeconds(1680123600))
          .setEndTime(Timestamp.newBuilder().setSeconds(1680130800)))
      .build();

    // Task request
    UpdateTaskRequest updateTaskRequest =
      UpdateTaskRequest.newBuilder()  // No need for the header
          .setTask(task)
          .setUpdateMask(FieldMask.newBuilder().addPaths("targetTimeWindow"))
          .build();

    try {
      Task updatedTask = deliveryService.updateTask(updateTaskRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case NOT_FOUND:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

HTTP를 사용하여 작업 기간을 설정하려면 UpdateTask를 호출합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=targetTimeWindow`

<id>는 작업의 고유 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 Task 항목이 포함되어야 합니다.

필수 필드:

필드 값

targetTimeWindow 작업이 완료되어야 하는 기간입니다. 이 설정은 라우팅 동작에 영향을 미치지 않습니다.
선택적 필드:
- 없음

필드	값
targetTimeWindow	작업이 완료되어야 하는 기간입니다. 이 설정은 라우팅 동작에 영향을 미치지 않습니다.

항목의 다른 모든 필드는 업데이트 시 무시됩니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=targetTimeWindow" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "targetTimeWindow": {
    "startTime": "2023-03-29T21:00:00Z",
    "endTime": "2023-03-29T23:00:00Z"
  }
}
EOM

작업 추적 공개 상태 구성 설정

배송 추적 라이브러리의 데이터 및 GetTaskTrackingInfo 호출에서 반환되는 데이터의 공개 상태는 작업에 TaskTrackingViewConfig를 설정하여 작업별로 제어할 수 있습니다. 자세한 내용은 활성 차량 작업을 참고하세요. 이 작업은 태스크를 만들거나 업데이트할 때 수행할 수 있습니다. 다음은 이 구성으로 태스크를 업데이트하는 예시입니다.

gRPC

다음 예에서는 자바 gRPC 라이브러리를 사용하여 태스크 추적 뷰 구성을 설정하는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskTrackingViewConfig(
    TaskTrackingViewConfig.newBuilder()
      .setRoutePolylinePointsVisibility(
        VisibilityOption.newBuilder().setRemainingStopCountThreshold(3))
      .setEstimatedArrivalTimeVisibility(
        VisibilityOption.newBuilder().remainingDrivingDistanceMetersThreshold(5000))
      .setRemainingStopCountVisibility(
        VisibilityOption.newBuilder().setNever(true)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("taskTrackingViewConfig"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
        break;
      case PERMISSION_DENIED:
        break;
  }
  return;
}

REST

HTTP를 사용하여 작업 추적 뷰 구성 창을 설정하려면 UpdateTask를 호출합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskTrackingViewConfig`

<id>는 작업의 고유 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 Task 항목이 포함되어야 합니다.

필수 필드:

필드 값

taskTrackingViewConfig 특정 상황에서 최종 사용자에게 표시되는 데이터 요소를 지정하는 작업 추적 구성입니다.
선택적 필드:
- 없음

필드	값
taskTrackingViewConfig	특정 상황에서 최종 사용자에게 표시되는 데이터 요소를 지정하는 작업 추적 구성입니다.

항목의 다른 모든 필드는 업데이트 시 무시됩니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskTrackingViewConfig" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskTrackingViewConfig": {
    "routePolylinePointsVisibility": {
      "remainingStopCountThreshold": 3
    },
    "estimatedArrivalTimeVisibility": {
      "remainingDrivingDistanceMetersThreshold": 5000
    },
    "remainingStopCountVisibility": {
      "never": true
    }
  }
}
EOM

차량에 작업 할당

차량의 작업 순서를 업데이트하여 배송 차량에 작업을 할당합니다. 차량의 작업 순서는 배달 차량의 차량 정류장 목록에 따라 결정되며 각 차량 정류장에 하나 이상의 작업을 할당할 수 있습니다. 자세한 내용은 태스크 순서 업데이트를 참조하세요.

한 차량에서 다른 차량으로 배송을 변경하려면 원래 작업을 닫은 다음 다시 만든 후 새 차량에 할당합니다. 이미 다른 차량에 할당된 작업의 작업 순서를 업데이트하면 오류가 발생합니다.

할 일 순서 업데이트

차량에 할당된 주문 작업은 Driver SDK 또는 서버 환경에서 실행될 수 있습니다. 경합 상태를 방지하고 단일 정보 소스를 유지하기 위해 두 가지 방법을 모두 사용하지 마세요.

차량의 작업 순서를 업데이트하면 다음 작업도 실행됩니다.

차량에 새로운 작업을 할당합니다.
이전에 차량에 할당되었지만 업데이트된 순서에 없는 작업을 닫습니다.

언제든지 할 일 순서를 업데이트할 수 있습니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 차량의 작업 순서를 업데이트하는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";
static final String TASK1_ID = "task-756390";
static final String TASK2_ID = "task-849263";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.NEW)))
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

서버 환경에서 차량의 작업 순서를 업데이트하려면 UpdateDeliveryVehicle에 대한 HTTP REST 호출을 실행합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id>는 작업 순서를 업데이트하려는 차량 내 배송 차량의 고유 식별자입니다. 차량을 만들 때 지정한 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 DeliveryVehicle 항목이 포함되어야 합니다.

필수 필드:

필드	값
remainingVehicleJourneySegments	태스크가 실행되어야 하는 순서대로 나열된 여정 세그먼트 목록입니다. 목록의 첫 번째 작업이 먼저 실행됩니다.
leftVehicleJourneySegments[i].stop 정류장	목록에서 작업 i의 경유지입니다.
leftVehicleJourneySegments[i].stop.plannedLocation	정류장의 계획된 위치입니다.
leftVehicleJourneySegments[i].stop.tasks	이 차량 정류장에서 실행할 작업 목록입니다.
remainingVehicleJourneySegments[i].stop.state	State.NEW

선택적 필드:
- 없음

항목의 다른 모든 필드는 업데이트 시 무시됩니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

차량이 다음 정류장으로 이동 중

차량이 정류장에서 출발하거나 내비게이션을 시작할 때 Fleet Engine에 알려야 합니다. Driver SDK에서 또는 gRPC나 REST를 사용하는 서버 환경에서 Fleet Engine에 알릴 수 있습니다. 경합 상태를 방지하고 단일 정보 소스를 유지하기 위해 두 메서드를 모두 사용하지 마세요.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 차량이 다음 정류장으로 이동 중임을 Fleet Engine에 알리는 방법을 보여줍니다.

    static final String PROJECT_ID = "my-delivery-co-gcp-project";
    static final String VEHICLE_ID = "vehicle-8241890";

    DeliveryServiceBlockingStub deliveryService =
      DeliveryServiceGrpc.newBlockingStub(channel);

    // Vehicle settings
    DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
        // Next stop marked as ENROUTE
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 1st stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.7749)
                       .setLongitude(122.4194)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
               .setState(VehicleStop.State.ENROUTE)))
        // All other stops marked as NEW
        .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
           .setStop(VehicleStop.newBuilder()
               .setPlannedLocation(LocationInfo.newBuilder()
                   .setPoint(LatLng.newBuilder()
                       .setLatitude(37.3382)
                       .setLongitude(121.8863)))
               .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
               .setState(VehicleStop.State.NEW)))
        .build();

    // DeliveryVehicle request
    UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
      UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
          .setName(vehicleName)
          .setDeliveryVehicle(deliveryVehicle)
          .setUpdateMask(FieldMask.newBuilder().addPaths("remaining_vehicle_journey_segments"))
          .build();

    try {
      DeliveryVehicle updatedDeliveryVehicle =
          deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
    } catch (StatusRuntimeException e) {
      Status s = e.getStatus();
      switch (s.getCode()) {
         case NOT_FOUND:
           break;
         case PERMISSION_DENIED:
           break;
      }
      return;
    }

REST

차량이 서버 환경에서 다음 정류장으로 이동 중임을 Fleet Engine에 알리려면 UpdateDeliveryVehicle에 대한 HTTP REST 호출을 실행합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id>는 작업 순서를 업데이트하려는 Fleet에서 배송 차량의 고유 식별자입니다. 차량을 만들 때 지정한 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 DeliveryVehicle 항목이 포함되어야 합니다.

필수 입력란:

필드	값
remainingVehicleJourneySegments	상태가 State.NEW로 표시된 나머지 차량 정류장 목록입니다. 목록의 첫 번째 정류장은 State.ENROUTE로 표시된 상태가 있어야 합니다.

선택적 필드:
- 없음

항목의 다른 모든 필드는 알림에서 무시됩니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ENROUTE",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

차량 위치 업데이트

Driver SDK를 사용하여 차량 위치를 업데이트하지 않는 경우 차량 위치를 사용하여 Fleet Engine을 직접 호출할 수 있습니다. 모든 활성 차량의 경우 Fleet Engine은 위치가 최소 1분에 한 번, 최대 5초에 한 번 업데이트될 것으로 예상합니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 Fleet Engine에서 차량 위치를 업데이트하는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle myDeliveryVehicle = DeliveryVehicle.newBuilder()
    .setLastLocation(DeliveryVehicleLocation.newBuilder()
        .setSupplementalLocation(LatLng.newBuilder()
            .setLatitude(37.3382)
            .setLongitude(121.8863))
        .setSupplementalLocationTime(now())
        .setSupplementalLocationSensor(DeliveryVehicleLocationSensor.CUSTOMER_SUPPLIED_LOCATION)
        .setSupplementalLocationAccuracy(DoubleValue.of(15.0)))  // Optional
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(myDeliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("last_location"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

HTTP REST를 사용하여 Fleet Engine에서 차량 위치를 업데이트하려면 UpdateDeliveryVehicle를 호출합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=last_location`

<id>는 차량에 있거나 위치를 업데이트하려는 배송 차량의 고유 식별자입니다. 차량을 만들 때 지정한 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 DeliveryVehicle 항목이 포함되어야 합니다.

필수 입력란:

필드	값
lastLocation.supplementalLocation	차량의 위치입니다.
lastLocation.supplementalLocationTime	차량이 이 위치에 있었던 마지막으로 알려진 타임스탬프입니다.
lastLocation.supplementalLocationSensor	CUSTOMER_SUPPLIED_LOCATION으로 채워져야 합니다.

선택적 필드:

필드 값

lastLocation.supplementalLocationAccuracy 제공된 위치의 정확도(미터)입니다.

필드	값
lastLocation.supplementalLocationAccuracy	제공된 위치의 정확도(미터)입니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "lastLocation": {
    "supplementalLocation": {"latitude": 12.1, "longitude": 14.5},
    "supplementalLocationTime": "$(date -u --iso-8601=seconds)",
    "supplementalLocationSensor": "CUSTOMER_SUPPLIED_LOCATION",
    "supplementalLocationAccuracy": 15
  }
}
EOM

차량이 정류장에 도착함

차량이 정류장에 도착하면 Fleet Engine에 알려야 합니다. Driver SDK에서 또는 gRPC나 REST를 사용하는 서버 환경에서 Fleet Engine에 알릴 수 있습니다. 경합 상태를 방지하고 단일 정보 소스를 유지하기 위해 두 메서드를 모두 사용하지 마세요.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 차량이 정류장에 도착했음을 Fleet Engine에 알리는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // Marking the arrival at stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.7749)
                   .setLongitude(122.4194)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
           .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // 2nd stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW))) // Remaining stops must be NEW.
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // No need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

서버 환경에서 정류장에 도착함을 Fleet Engine에 알리려면 UpdateDeliveryVehicle에 대한 HTTP REST 호출을 실행합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remainingVehicleJourneySegments`

<id>는 작업 순서를 업데이트하려는 Fleet에서 배송 차량의 고유 식별자입니다. 차량을 만들 때 지정한 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 DeliveryVehicle 항목이 포함되어야 합니다.

필수 필드:

필드 값

remainingVehicleJourneySegments State.ARRIVED로 상태가 설정된 도착한 정류장과 상태가 State.NEW로 표시된 나머지 차량 정류장 목록이 표시됩니다.
선택적 필드:
- 없음

필드	값
remainingVehicleJourneySegments	State.ARRIVED로 상태가 설정된 도착한 정류장과 상태가 State.NEW로 표시된 나머지 차량 정류장 목록이 표시됩니다.

항목의 다른 모든 필드는 업데이트 시 무시됩니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
# environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "remainingVehicleJourneySegments": [
    {
      "stop": {
        "state": "ARRIVED",
        "plannedLocation": {
          "point": {
            "latitude": 37.7749,
            "longitude": -122.084061
          }
        },
        "tasks": [
          {
            "taskId": "${TASK1_ID}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

차량 정차 완료

차량이 정차를 완료하면 Fleet Engine에 알려야 합니다. 그러면 정류장과 관련된 모든 작업이 CLOSED 상태로 설정됩니다. Driver SDK에서 또는 gRPC나 REST를 사용하는 서버 환경에서 Fleet Engine을 알릴 수 있습니다. 경합 상태를 방지하고 단일 정보 소스를 유지하기 위해 두 메서드를 모두 사용하지 마세요.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 차량이 정차를 완료했음을 Fleet Engine에 알리는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle settings
String vehicleName = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
DeliveryVehicle deliveryVehicle = DeliveryVehicle.newBuilder()
    // This stop has been completed and is commented out to indicate it
    // should be removed from the list of vehicle journey segments.
    // .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()
    //    .setStop(VehicleStop.newBuilder()
    //        .setPlannedLocation(LocationInfo.newBuilder()
    //            .setPoint(LatLng.newBuilder()
    //                .setLatitude(37.7749)
    //                .setLongitude(122.4194)))
    //        .addTasks(TaskInfo.newBuilder().setTaskId(TASK1_ID))
    //        .setState(VehicleStop.State.ARRIVED)))
    // All other remaining stops marked as NEW.
    // The next stop could be marked as ENROUTE if the vehicle has begun
    // its journey to the next stop.
    .addRemainingVehicleJourneySegments(VehicleJourneySegment.newBuilder()  // Next stop
       .setStop(VehicleStop.newBuilder()
           .setPlannedLocation(LocationInfo.newBuilder()
               .setPoint(LatLng.newBuilder()
                   .setLatitude(37.3382)
                   .setLongitude(121.8863)))
           .addTasks(TaskInfo.newBuilder().setTaskId(TASK2_ID))
           .setState(VehicleStop.State.NEW)))
    .build();

// DeliveryVehicle request
UpdateDeliveryVehicleRequest updateDeliveryVehicleRequest =
  UpdateDeliveryVehicleRequest.newBuilder()  // no need for the header
      .setName(vehicleName)
      .setDeliveryVehicle(deliveryVehicle)
      .setUpdateMask(FieldMask.newBuilder()
          .addPaths("remaining_vehicle_journey_segments"))
      .build();

try {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

서버 환경에서 중지가 완료되었음을 Fleet Engine에 알리려면 UpdateDeliveryVehicle에 대해 HTTP REST 호출을 실행합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<id>?updateMask=remaining_vehicle_journey_segments`

<id>는 작업 순서를 업데이트하려는 Fleet에서 배송 차량의 고유 식별자입니다. 차량을 만들 때 지정한 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 DeliveryVehicle 항목이 포함되어야 합니다.

필수 필드:

필드 값

remaining_vehicle_journey_segments 완료한 정류장이 더 이상 남은 차량 정류장 목록에 포함되지 않습니다.
선택적 필드:
- 없음

필드	값
remaining_vehicle_journey_segments	완료한 정류장이 더 이상 남은 차량 정류장 목록에 포함되지 않습니다.

항목의 다른 모든 필드는 업데이트 시 무시됩니다.

curl 명령어 예시:

    # Set JWT, PROJECT_ID, VEHICLE_ID, TASK1_ID, and TASK2_ID in the local
    # environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}?updateMask=remainingVehicleJourneySegments" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "remainingVehicleJourneySegments": [
        {
          "stop": {
            "state": "NEW",
            "plannedLocation": {
              "point": {
                "latitude": 37.3382,
                "longitude": 121.8863
              }
            },
            "tasks": [
              {
                "taskId": "${TASK2_ID}"
              }
            ]
          }
        }
      ]
    }
    EOM

할 일 업데이트

대부분의 태스크 필드는 변경할 수 없습니다. 하지만 태스크 항목을 직접 업데이트하여 상태, 태스크 결과, 태스크 결과 시간, 태스크 결과 위치, 속성을 수정할 수 있습니다. 예를 들어 작업이 차량에 할당되지 않은 경우 상태를 직접 업데이트하여 작업을 닫을 수 있습니다.

gRPC

gRPC를 통해 태스크를 업데이트하는 예시입니다.

REST

REST를 통해 태스크를 업데이트하는 예시입니다.

할 일 닫기

차량에 할당된 작업을 닫으려면 차량이 작업이 발생하는 위치에서 정차를 완료했음을 Fleet Engine에 알리거나 차량 정류장 목록에서 해당 작업을 삭제합니다. 이렇게 하려면 차량의 작업 순서를 업데이트할 때와 마찬가지로 나머지 차량 정류장 목록을 설정하면 됩니다.

작업에 아직 차량이 할당되지 않아 닫아야 한다면 작업을 닫힘 상태로 업데이트합니다. 하지만 닫은 작업은 다시 열 수 없습니다.

태스크의 종료는 성공 또는 실패를 나타내지 않습니다. 이는 작업이 더 이상 진행 중인 것으로 간주되지 않음을 나타냅니다. Fleet 추적의 경우 전송 결과를 표시할 수 있도록 태스크의 실제 결과를 나타내는 것이 중요합니다.

gRPC

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setState(Task.State.CLOSED) // You can only directly CLOSE a
  .build();                    // task that is NOT assigned to a vehicle.

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("state"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

작업을 서버 환경에서 종료된 것으로 표시하려면 UpdateTask에 대한 HTTP REST 호출을 실행합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=state`

<id>는 작업의 고유 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에 Task 항목을 포함해야 합니다.

필수 필드:

필드 값

state State.CLOSED

필드	값
state	State.CLOSED

선택적 필드:

필드	값
taskOutcome	Outcome.SUCCEEDED 또는 Outcome.FAILED
taskOutcomeTime	할 일이 완료된 시간입니다.
taskOutcomeLocation	할 일이 완료된 위치입니다. 제공업체가 수동으로 재정의하지 않는 한 Fleet Engine은 이 위치를 마지막 차량 위치로 기본값으로 설정합니다.

항목의 다른 모든 필드는 업데이트 시 무시됩니다.

curl 명령어 예시:

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=state,taskOutcome,taskOutcomeTime" \
      -H "Content-type: application/json" \
      -H "Authorization: Bearer ${JWT}" \
      --data-binary @- << EOM
    {
      "state": "CLOSED",
      "taskOutcome": "SUCCEEDED",
      "taskOutcomeTime": "$(date -u --iso-8601=seconds)"
    }
    EOM

작업 결과 및 결과 위치 설정

태스크 종료는 성공 또는 실패를 나타내는 것이 아니라 태스크가 더 이상 진행 중인 것으로 간주되지 않음을 나타냅니다. Fleet 추적의 경우 전송 결과를 표시하고 적절한 서비스 비용이 청구되도록 태스크의 실제 결과를 나타내는 것이 중요합니다. 설정한 후에는 작업 결과를 변경할 수 없습니다. 그러나 작업 결과 시간 및 작업 결과 위치를 설정한 후에 수정할 수 있습니다.

CLOSED 상태에 있는 작업은 결과를 성공 또는 실패로 설정할 수 있습니다. Fleet Engine은 성공 상태인 전송 작업에만 비용을 청구합니다.

작업 결과를 표시할 때 Fleet Engine은 마지막으로 알려진 차량 위치로 작업 결과 위치를 자동으로 채웁니다. 이 동작을 재정의할 수 있습니다.

gRPC

결과를 설정할 때 작업 결과 위치를 설정할 수 있습니다. 위치를 설정하면 Fleet Engine에서 마지막 차량 위치의 기본값으로 설정할 수 없습니다. 나중에 설정된 태스크 결과 위치 Fleet Engine을 덮어쓸 수도 있습니다. Fleet Engine은 사용자가 제공한 태스크 결과 위치를 덮어쓰지 않습니다. 태스크 결과가 설정되지 않은 태스크에는 태스크 결과 위치를 설정할 수 없습니다. 동일한 요청 내에서 태스크 결과와 태스크 결과 위치를 모두 설정할 수 있습니다.

다음 예에서는 자바 gRPC 라이브러리를 사용하여 작업 결과를 SUCCEEDED로 설정하고 작업이 완료된 위치를 설정하는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task settings
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
Task task = Task.newBuilder()
  .setName(taskName)
  .setTaskOutcome(TaskOutcome.SUCCEEDED)
  .setTaskOutcomeTime(now())
  .setTaskOutcomeLocation(               // Grand Indonesia East Mall
    LocationInfo.newBuilder().setPoint(
      LatLng.newBuilder().setLatitude(-6.195139).setLongitude(106.820826)))
  .build();

// Task request
UpdateTaskRequest updateTaskRequest =
  UpdateTaskRequest.newBuilder()  // No need for the header
      .setTask(task)
      .setUpdateMask(FieldMask.newBuilder().addPaths("task_outcome", "task_outcome_time", "task_outcome_location"))
      .build();

try {
  Task updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

작업을 서버 환경에서 완료된 것으로 표시하려면 UpdateTask에 대한 HTTP REST 호출을 실행합니다.

`PATCH https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<id>?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation`

<id>는 작업의 고유 식별자입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문에는 Task 항목이 포함되어야 합니다.

필수 필드:

필드 값

taskOutcome Outcome.SUCCEEDED 또는 Outcome.FAILED

선택적 필드:

필드	값
taskOutcomeLocation	할 일이 완료된 위치입니다. 설정하지 않으면 Fleet Engine에서 마지막 차량 위치를 기본값으로 설정합니다.
taskOutcomeTime	태스크가 완료된 시점의 타임스탬프입니다.

항목의 다른 모든 필드는 업데이트 시 무시됩니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, and TASK_ID in the local environment
curl -X PATCH "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}?updateMask=taskOutcome,taskOutcomeTime,taskOutcomeLocation" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "taskOutcome": "SUCCEEDED",
  "taskOutcomeTime": "$(date -u --iso-8601=seconds)",
  "taskOutcomeLocation": {
    "point": {
      "latitude": -6.195139,
      "longitude": 106.820826
    }
  }
}
EOM

배송 경로 변경

배송 작업이 생성되면 계획된 위치를 변경할 수 없습니다. 배송 경로를 변경하려면 결과를 설정하지 않고 배송 태스크를 종료한 다음 업데이트된 계획 위치로 새 태스크를 만듭니다. 새 작업을 만든 후 동일한 차량에 작업을 할당합니다. 자세한 내용은 배송 작업 닫기 및 작업 할당을 참고하세요.

피더 및 배송 수단 사용

하루 동안 피더 차량을 사용하여 배송 차량으로 배송을 운송하는 경우 배송 차량의 예약 중단 작업으로 배송 운송을 모델링합니다. 정확한 위치 추적을 위해서는 배송 차량이 배송 차량에 적재된 후에만 배송된 상품의 배송 작업을 할당하세요. 자세한 내용은 예정된 경유지를 참고하세요.

매장 배송 상태 및 기타 메타 정보

배송 작업이 완료되면 작업 상태와 결과가 작업에 기록됩니다. 하지만 배송과 관련된 다른 메타 정보를 업데이트할 수도 있습니다. Fleet Engine 서비스 외부에서 참조할 수 있는 다른 메타 정보를 저장하려면 태스크와 연결된 tracking_id를 외부 테이블의 키로 사용합니다.

자세한 내용은 태스크 수명을 참조하세요.

차량 찾기

Driver SDK에서 또는 gRPC나 REST를 사용하는 서버 환경에서 차량을 조회할 수 있습니다.

gRPC

다음 예에서는 자바 gRPC 라이브러리를 사용하여 차량을 찾는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String VEHICLE_ID = "vehicle-8241890";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Vehicle request
String name = "providers/" + PROJECT_ID + "/deliveryVehicles/" + VEHICLE_ID;
GetDeliveryVehicleRequest getVehicleRequest = GetDeliveryVehicleRequest.newBuilder()  // No need for the header
    .setName(name)
    .build();

try {
  DeliveryVehicle vehicle = deliveryService.getDeliveryVehicle(getVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

서버 환경에서 차량을 조회하려면 GetVehicle에 대한 HTTP REST 호출을 실행합니다.

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles/<vehicleId>`

<id>는 작업의 고유 식별자입니다.

<vehicleId>는 조회할 차량의 ID입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문은 비어 있어야 합니다.

조회에 성공하면 응답 본문에 차량 항목이 포함됩니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles/${VEHICLE_ID}"

할 일 찾기

gRPC 또는 REST를 사용하여 서버 환경에서 작업을 조회할 수 있습니다. 드라이버 SDK는 작업 조회를 지원하지 않습니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 태스크를 찾는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TASK_ID = "task-8597549";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Task request
String taskName = "providers/" + PROJECT_ID + "/tasks/" + TASK_ID;
GetTaskRequest getTaskRequest = GetTaskRequest.newBuilder()  // No need for the header
    .setName(taskName)
    .build();

try {
  Task task = deliveryService.getTask(getTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

서버 환경에서 작업을 조회하려면 GetTask에 대한 HTTP REST 호출을 실행합니다.

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks/<taskId>`

<id>는 작업의 고유 식별자입니다.

<taskId>는 조회할 작업의 ID입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

요청 본문은 비어 있어야 합니다.

조회에 성공하면 응답 본문에 작업 항목이 포함됩니다.

curl 명령어 예시:

    # Set JWT, PROJECT_ID, and TASK_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks/${TASK_ID}"

추적 ID로 배송 작업 정보 조회

다음과 같은 방법으로 Fleet 태스크 정보를 조회할 수 있으며, 각 방법은 별개의 용도로 사용됩니다.

작업 ID별: 작업 데이터의 전체 보기에 액세스할 수 있는 Fleet 운영자와 같은 사용자가 사용합니다.
추적 ID로: 클라이언트 소프트웨어에서 최종 사용자에게 제한된 정보를 제공하기 위해 사용됩니다(예: 물품이 고객의 자택으로 배송될 것으로 예상됨).

이 섹션에서는 추적 ID로 작업 정보를 찾는 방법을 설명합니다. 작업 ID로 작업을 찾으려면 작업 찾기로 이동하세요.

추적 ID로 정보를 조회하려면 다음 중 하나를 사용하면 됩니다.

gRPC를 사용하여 Java로 조회
HTTP를 사용한 조회

조회 요구사항

추적 ID에서 제공하는 배송 정보는 추적 중인 위치의 공개 상태 관리에 명시된 공개 상태 규칙을 준수합니다.
Fleet Engine을 사용하여 추적 ID로 배송 정보를 조회합니다. 드라이버 SDK는 추적 ID를 사용한 정보 조회를 지원하지 않습니다. Fleet Engine으로 이 작업을 수행하려면 서버 또는 브라우저 환경을 사용합니다.
보안 위험을 제한하기 위해 가능한 한 가장 좁은 토큰을 사용합니다. 예를 들어 배송 소비자 토큰을 사용하는 경우 Fleet Engine Deliveries API 호출은 배송업체 또는 배송 수신자와 같이 최종 사용자와 관련된 정보만 반환합니다. 응답의 다른 모든 정보는 수정됩니다. 토큰에 대한 자세한 내용은 승인을 위한 JSON 웹 토큰 (JWT) 만들기를 참조하세요.

gRPC를 사용하여 Java로 조회

다음 예에서는 자바 gRPC 라이브러리를 사용하여 추적 ID로 배송 태스크에 대한 정보를 찾는 방법을 보여줍니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
GetTaskTrackingInfoRequest getTaskTrackingInfoRequest = GetTaskTrackingInfoRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setTrackingId(TRACKING_ID)
    .build();

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

HTTP를 사용한 조회

브라우저에서 배송 태스크를 조회하려면 GetTaskTrackingInfo에 대한 HTTP REST 호출을 실행합니다.

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/taskTrackingInfo/<tracking_id>`

<tracking_id>는 작업과 연결된 추적 ID입니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

조회가 성공하면 응답 본문에 taskTrackingInfo 항목이 포함됩니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, and TRACKING_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/taskTrackingInfo/${TRACKING_ID}"

태스크 표시

서버 또는 브라우저 환경에서 작업을 나열할 수 있습니다. Driver SDK는 작업 나열을 지원하지 않습니다.

태스크 나열에는 태스크에 대한 광범위한 액세스 권한이 필요합니다. 태스크 나열은 신뢰할 수 있는 사용자만을 대상으로 합니다. 목록 작업을 요청할 때 전송 Fleet 리더 또는 전송 수퍼 사용자 인증 토큰을 사용합니다.

나열된 태스크는 다음 필드가 수정됩니다.

VehicleStop.planned_location
VehicleStop.state
VehicleStop.TaskInfo.taskId

나열된 작업은 대부분의 작업 속성으로 필터링할 수 있습니다. 필터 쿼리 구문은 AIP-160을 참조하세요. 다음 목록은 필터링에 사용할 수 있는 유효한 작업 속성을 보여줍니다.

속성
delivery_vehicle_id
state
planned_location
task_duration
task_outcome
task_outcome_location
task_outcome_location_source
task_outcome_time
tracking_id
유형

Google API 개선 제안에 따라 다음 필드 형식을 사용합니다.

필드 유형	형식	예
타임스탬프	RFC-3339	`task_outcome_time = 2022-03-01T11:30:00-08:00`
시간	초 다음에 `s`이 오는 시간입니다.	`task_duration = 120s`
enum	문자열	`state = CLOSED AND type = PICKUP`
위치	`point.latitude` 및 `point.longitude`	`planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0`

필터 쿼리 연산자의 전체 목록은 AIP-160을 참조하세요.

필터 쿼리를 지정하지 않으면 모든 태스크가 나열됩니다.

할 일 목록은 페이지로 나눠집니다. 페이지 크기는 태스크 나열 요청에서 지정할 수 있습니다. 페이지 크기가 지정된 경우 반환되는 작업 수는 지정된 페이지 크기보다 크지 않습니다. 페이지 크기가 없으면 적절한 기본값이 사용됩니다. 요청된 페이지 크기가 내부 최댓값을 초과하면 내부 최댓값이 사용됩니다.

작업 목록에는 결과의 다음 페이지를 읽기 위한 토큰이 포함될 수 있습니다. 이전 요청과 동일한 요청과 함께 페이지 토큰을 사용하여 다음 태스크 페이지를 검색합니다. 반환된 페이지 토큰이 비어 있으면 더 이상 작업을 검색할 수 없습니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 DeliveryVehicleId 및 태스크 속성의 태스크를 나열하는 방법을 보여줍니다. 성공 응답은 여전히 비워 둘 수 있습니다. 빈 응답은 제공된 DeliveryVehicleId와 연결된 Tasks가 없음을 나타냅니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";
static final String TRACKING_ID = "TID-7449w087464x5";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListTasksRequest listTasksRequest = ListTasksRequest.newBuilder()  // No need for the header
    .setParent(parent)
    .setFilter("delivery_vehicle_id = 123 AND attributes.foo = true")
    .build();

try {
  ListTasksResponse listTasksResponse = deliveryService.listTasks(listTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

브라우저에서 작업을 나열하려면 ListTasks에 대한 HTTP REST 호출을 실행합니다.

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks`

나열된 작업에 필터를 적용하려면 URL로 이스케이프 처리된 필터 검색어와 함께 'filter' URL 매개변수를 값으로 포함합니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

조회에 성공하면 응답 본문에 다음과 같은 구조의 데이터가 포함됩니다.

    // JSON representation
    {
      "tasks": [
        {
          object (Task)
        }
      ],
      "nextPageToken": string,
      "totalSize": integer
    }

성공 응답은 여전히 비어 있을 수 있습니다. 응답이 비어 있으면 지정된 필터 기준을 충족하는 작업이 없음을 나타냅니다.

curl 명령어 예시:

    # Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
    curl -H "Authorization: Bearer ${JWT}" \
      "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?filter=state%20%3D%20OPEN%20AND%20delivery_vehicle_id%20%3D%20${VEHICLE_ID}"

배송 차량 나열

서버 또는 브라우저 환경에서 배송 차량을 나열할 수 있습니다. Driver SDK는 배달 차량 나열을 지원하지 않습니다.

배송 차량을 나열하는 것은 배송 차량에 대한 광범위한 액세스를 요청하며 신뢰할 수 있는 사용자만을 대상으로 합니다. 목록 전송 수단 요청 시 전송 Fleet 리더 또는 전송 수퍼 사용자 인증 토큰을 사용합니다.

나열된 배송 차량은 응답 크기에 미치는 영향으로 인해 다음 필드가 수정됩니다.

CurrentRouteSegment
RemainingVehicleJourneySegments

attributes 속성을 기준으로 배송 차량 목록을 필터링할 수 있습니다. 예를 들어 키가 my_key이고 값이 my_value인 속성을 쿼리하려면 attributes.my_key = my_value를 사용합니다. 여러 속성을 쿼리하려면 attributes.key1 = value1 AND attributes.key2 = value2와 같이 논리적 AND 및 OR 연산자를 사용하여 쿼리를 조인합니다. 필터 쿼리 구문에 대한 자세한 설명은 AIP-160을 참조하세요.

viewport 요청 매개변수를 사용하여 나열된 배송 차량을 위치별로 필터링할 수 있습니다. viewport 요청 매개변수는 두 가지 경계 좌표, 즉 high (북동쪽)과 low (남서쪽) 위도 및 경도 좌표 쌍을 사용하여 표시 영역을 정의합니다. 지리적으로 낮은 위도보다 낮은 높은 위도가 포함된 경우 요청이 거부됩니다.

배달 차량 목록은 기본적으로 적절한 페이지 크기를 사용하여 페이지로 나뉩니다. 페이지 크기를 지정하면 요청은 한도에서 지정된 차량 수 이하의 차량만 반환합니다. 요청된 페이지 크기가 내부 최댓값을 초과하면 내부 최댓값이 사용됩니다. 기본 및 최대 페이지 크기는 모두 차량 100대입니다.

배달 수단 목록에는 결과의 다음 페이지를 읽는 토큰이 포함될 수 있습니다. 페이지 토큰은 더 많은 배달 차량 페이지를 가져올 수 있는 경우에만 응답에 존재합니다. 다음 태스크 페이지를 검색하려면 이전 요청과 동일한 요청과 함께 페이지 토큰을 사용합니다.

gRPC

다음 예시에서는 자바 gRPC 라이브러리를 사용하여 특정 속성을 가진 특정 리전의 배송 차량을 나열하는 방법을 보여줍니다. 성공 응답은 여전히 비어 있을 수 있습니다. 이 경우 지정된 속성을 가진 차량이 이미 지정된 표시 영역에 없음을 의미합니다.

static final String PROJECT_ID = "my-delivery-co-gcp-project";

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

// Tasks request
String parent = "providers/" + PROJECT_ID;
ListDeliveryVehiclesRequest listDeliveryVehiclesRequest =
  ListDeliveryVehiclesRequest.newBuilder()  // No need for the header
      .setParent(parent)
      .setViewport(
            Viewport.newBuilder()
              .setHigh(LatLng.newBuilder()
                  .setLatitude(37.45)
                  .setLongitude(-122.06)
                  .build())
              .setLow(LatLng.newBuilder()
                  .setLatitude(37.41)
                  .setLongitude(-122.11)
                  .build())
      .setFilter("attributes.my_key = my_value")
      .build();

try {
  ListDeliveryVehiclesResponse listDeliveryVehiclesResponse =
      deliveryService.listDeliveryVehicles(listDeliveryVehiclesRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
      case NOT_FOUND:
          break;

      case PERMISSION_DENIED:
          break;
  }
  return;
}

REST

브라우저에서 작업을 나열하려면 ListDeliveryVehicles에 대한 HTTP REST 호출을 실행합니다.

`GET https://fleetengine.googleapis.com/v1/providers/<project_id>/deliveryVehicles`

나열된 작업에 필터를 적용하려면 URL로 이스케이프 처리된 필터 쿼리와 함께 'filter' URL 매개변수를 값으로 포함합니다.

요청 헤더에는 값이 Bearer <token>인 Authorization 필드가 포함되어야 합니다. 여기서 <token>은 Fleet Engine 토큰 팩토리에서 발급한 토큰입니다.

조회에 성공하면 응답 본문에 다음과 같은 구조의 데이터가 포함됩니다.

// JSON representation
{
  "deliveryVehicles": [
    {
      object (DeliveryVehicle)
    }
  ],
  "nextPageToken": string,
  "totalSize": integer
}

성공 응답은 여전히 비어 있을 수 있습니다. 이 경우 지정된 필터 쿼리 및 표시 영역을 충족하는 배송 차량이 발견되지 않았습니다.

curl 명령어 예시:

# Set JWT, PROJECT_ID, and VEHICLE_ID in the local environment
curl -H "Authorization: Bearer ${JWT}" \
  "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/deliveryVehicles?filter=attributes.my_key%20%3D%20my_value%20&viewport.high.latitude=37.45&viewport.high.longitude=-122.06&viewport.low.latitude=37.41&viewport.low.longitude=-122.11"

차량 추적

Fleet Engine Deliveries API를 사용하여 Fleet 추적을 사용 설정하는 옵션은 두 가지입니다.

권장: JavaScript Fleet 추적 라이브러리를 사용합니다. 라이브러리를 사용하면 Fleet Engine에서 추적한 차량의 위치와 관심 위치를 시각화할 수 있습니다. 여기에는 표준 google.maps.Map 객체의 드롭인 대체인 자바스크립트 지도 구성요소와 Fleet Engine과 연결되는 데이터 구성요소가 포함되어 있습니다. 이 구성요소를 사용하면 웹 또는 모바일 애플리케이션에서 맞춤설정이 가능한 애니메이션 차량 추적 환경을 제공할 수 있습니다.
Fleet Engine Deliveries API를 기반으로 자체 차량 추적을 구현합니다.

핵심은 추적 ID로 Fleet 작업을 조회하는 것입니다.

로깅

Cloud Logging으로 RPC 로그를 전송하도록 Fleet Engine을 설정할 수 있습니다. 자세한 내용은 로깅을 참조하세요.

승인 역할 및 토큰

차량 및 작업 수명 주기 관리와 개별 사용 사례에 대한 승인 참고사항에 설명된 것처럼, Fleet Engine을 호출하려면 서비스 계정 사용자 인증 정보를 사용하여 서명된 JSON 웹 토큰으로 인증해야 합니다. 이러한 토큰을 발급하는 데 사용되는 서비스 계정에는 하나 이상의 역할이 있을 수 있으며 각 역할은 서로 다른 권한 집합을 부여합니다.

자세한 내용은 인증 및 승인을 참조하세요.

일반적인 문제 해결

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

복원력

Fleet Engine은 정보 소스로 간주되지 않습니다. 필요한 경우 Fleet Engine에 의존하지 않고 시스템 상태를 복원할 책임은 사용자에게 있습니다.

Fleet Engine의 손실 상태

Fleet Engine으로 작업할 때는 장애가 발생하면 시스템이 자체적으로 복구되도록 클라이언트를 구현합니다. 예를 들어 Fleet Engine이 차량을 업데이트하려고 하면 차량이 존재하지 않는다는 오류로 응답할 수 있습니다. 그런 다음 클라이언트는 새 상태로 차량을 다시 만들어야 합니다. 이 문제는 드물게 발생하지만 시스템이 이를 처리할 수 있을 만큼 탄력적인지 확인하세요.

극히 드물지만 Fleet Engine에 치명적인 장애가 발생하는 경우 차량과 작업의 대부분 또는 전체를 다시 만들어야 할 수 있습니다. 생성 비율이 너무 높아지면 서비스 거부 (DOS) 공격을 방지하기 위한 할당량 검사가 이루어지므로 할당량 문제로 일부 요청이 다시 실패할 수 있습니다. 이 경우 재시도에 백오프 전략을 사용하여 재생성 속도를 늦추세요.

드라이버 앱의 상태 손실

드라이버 앱이 비정상 종료되면 앱은 드라이버 SDK 내에서 현재 상태를 다시 만들어야 합니다. 앱은 작업이 있는지 확인하고 현재 상태를 복원하기 위해 작업을 다시 만들어야 합니다. 또한 앱은 Driver SDK의 정류장 목록을 다시 만들고 명시적으로 설정해야 합니다.

FAQ

운전자가 잘못된 순서로 작업을 위해 정차하면 어떻게 해야 하나요?

이 경우 먼저 작업 순서를 업데이트한 다음 평소와 같이 진행하여 정류장 도착, 작업 완료 및 기타 세부정보를 표시합니다. 그러지 않으면 시스템이 일관되지 않고 ETA가 부정확해질 수 있으며, 예기치 않은 오류가 보고될 수 있습니다.