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

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

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

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

초기 설정

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

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

설정 확인

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

설정의 두 가지 주요 부분인 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에서 작업을 만들려면 드라이버 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	쉼표, 마침표, 콜론, 슬래시 등 PII 및 문자 요구사항을 위반합니다.
JohnDoe-577b484da26f-Cupertino-SantaCruz	개인 식별 정보 요건 위반
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로 업데이트합니다.

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

그러면 JavaScript Fleet 추적 라이브러리가 작업 결과를 나타내고 작업 상태가 자동으로 CLOSED로 설정됩니다. 자세한 내용은 JavaScript 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은 기기 위치를 추적 라이브러리로 전송하며, 소비자 애플리케이션은 이를 사용하여 소비자에게 택배가 가까이 있음을 알립니다.
배송 기사가 배송을 완료한 후 운전자 애플리케이션에서 'Shipment delivered'(배송 완료) 버튼을 클릭합니다.
'배송 완료' 작업은 백엔드 시스템으로 정보를 전송하고 백엔드 시스템은 필요한 비즈니스 유효성 검사 및 확인 단계를 실행합니다.
시스템에서 작업을 SUCCEEDED로 확인하고 Deliveries API를 사용하여 Fleet Engine을 업데이트합니다.

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

Deliveries API 다이어그램 통합>

클라이언트 토큰 관리

드라이버 애플리케이션에서 시작되어 Fleet Engine에 직접 전송되는 위치 업데이트에는 승인 토큰이 필요합니다. 다음은 클라이언트에서 Fleet Engine으로의 업데이트를 처리할 때 권장되는 방법입니다.

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

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

기타 서비스 계정 역할

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

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

근무일 모델링

다음 표에서는 배송 및 물류 회사에서 퍼스트 마일 또는 라스트 마일 드라이버의 근무일이 어떻게 나타나는지 설명합니다. 회사마다 세부 사항이 다를 수 있지만 업무일을 모델링하는 방법을 확인할 수 있습니다.

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

위치 업데이트 작동 방식

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

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

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

차량 정류장 및 배송 위치

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

배송 위치는 상품이 배송되거나 수령되는 위치입니다. 배송 위치로 가려면 차량 정류장에서 도보로 약간의 거리를 이동해야 할 수 있습니다.

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

사용자에게 최상의 배송 추적 환경을 제공하려면 배송 작업을 차량 정류장에 할당하는 방법을 고려하세요. 배송 작업을 위해 남은 차량 정류장 수가 사용자에게 보고되어 사용자가 배송 진행 상황을 확인할 수 있습니다.

예를 들어 운전자가 하나의 사무실 건물에서 여러 번 배송하는 경우 모든 배송 작업을 단일 차량 정류장에 할당해 보세요. 각 배송 작업이 자체 차량 정류장에 할당되면 배송 추적 환경은 사용자에게 유용하지 않습니다. 차량이 목적지에 도달하기 전에 제한된 수의 차량 정류장 내에 있는 경우에만 추적을 사용할 수 있기 때문입니다. 짧은 시간에 많은 차량 정류장을 완료하면 배송 진행 상황을 추적하는 데 사용할 시간이 많지 않습니다.

모바일 SDK 사용

Driver 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
유형

다른 필드는 설정하지 마세요. 그렇게 하면 Fleet Engine이 오류를 반환합니다. 읽기 전용이거나 UpdateDeliveryVehicle 호출을 통해서만 업데이트할 수 있기 때문입니다.

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

다음 예에서는 Java 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 필드를 무시합니다. 다른 필드는 설정하지 마세요. 그렇게 하면 Fleet Engine에서 오류를 반환합니다. 이러한 필드는 읽기 전용이거나 UpdateDeliveryVehicle 호출을 사용해서만 업데이트할 수 있기 때문입니다.

필드를 설정하지 않고 차량을 만들려면 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	작업을 완료해야 하는 기간입니다. 이는 라우팅 동작에 영향을 미치지 않습니다.
속성	사용자 지정 작업 속성의 목록입니다. 각 속성에는 고유 키가 있어야 합니다.

항목의 다른 모든 필드는 생성 시 무시됩니다. 요청에 할당된 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	작업을 완료해야 하는 기간입니다. 이는 라우팅 동작에 영향을 미치지 않습니다.
속성	사용자 지정 작업 속성의 목록입니다. 각 속성에는 고유 키가 있어야 합니다.

항목의 다른 모든 필드는 생성 시 무시됩니다. 요청에 할당된 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>
선택적 필드:

필드 가치

헤더 '게재 요청 헤더'

필드	가치
요청	배열<`CreateTasksRequest`>

필드	가치
헤더	'게재 요청 헤더'

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

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

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

예약 불가능 시간

운전자 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

예약된 정류장

드라이버 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

다음 예는 Java 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>는 작업 순서를 업데이트하려는 Fleet의 배송 차량에 대한 고유 식별자입니다. 차량을 만들 때 지정한 식별자입니다.

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

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

필수 필드:

필드	가치
remainingVehicleJourneySegments	작업이 실행되어야 하는 순서대로 나열된 작업의 여정 세그먼트 목록입니다. 목록의 첫 번째 작업이 먼저 실행됩니다.
나머지차량 여정 세그먼트[i].stop	목록에서 작업 i의 중지
나머지 차량JourneySegments[i].stop.plannedLocation	정류장에 대해 계획된 위치입니다.
나머지차량JourneySegments[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

다음 예는 Java 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에 알리거나 차량 정류장 목록에서 삭제합니다. 이렇게 하려면 차량의 작업 순서를 업데이트할 때와 마찬가지로 나머지 차량 정류장의 목록을 설정하면 됩니다.

작업에 아직 차량에 할당되지 않았고 닫아야 하는 경우 작업을 CLOSED 상태로 업데이트합니다. 그러나 CLOSED 작업은 다시 열 수 없습니다.

작업 종료는 성공 또는 실패를 나타내지 않습니다. 이는 작업이 더 이상 진행 중인 것으로 간주되지 않음을 나타냅니다. 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 상태인 태스크의 결과는 SUCCEEDED 또는 FAILED로 설정될 수 있습니다. Fleet Engine은 상태가 SUCCEEDED인 전송 태스크에만 요금을 청구합니다.

태스크 결과를 표시할 때 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

다음 예는 Java 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로 배송 정보를 조회합니다. Driver 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}"

태스크 표시

서버 또는 브라우저 환경에서 작업을 나열할 수 있습니다. 드라이버 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

다음 예에서는 Java gRPC 라이브러리를 사용하여 deliveryVehicleId와 태스크 속성의 태스크를 나열하는 방법을 보여줍니다. 성공적인 응답은 비어 있을 수 있습니다. 빈 응답은 제공된 deliveryVehicleId와 연결된 태스크가 없음을 나타냅니다.

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 객체의 삽입형 대체물인 JavaScript 지도 구성요소와 Fleet Engine에 연결하는 데이터 구성요소가 포함되어 있습니다. 이 구성요소를 사용하면 웹 또는 모바일 애플리케이션에서 맞춤설정 가능한 애니메이션 Fleet 추적 환경을 제공할 수 있습니다.
Fleet Engine Deliveries API를 기반으로 자체 Fleet 추적을 구현합니다.

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

로깅

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

승인 역할 및 토큰

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

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

일반적인 문제 해결

문제가 발생하면 다음 섹션에서 도움을 받으세요.

복원력

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

Fleet Engine의 손실 상태

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

드물지만 Fleet Engine에 치명적인 장애가 발생하는 시나리오가 발생하면 대부분 또는 모든 차량 및 태스크를 다시 만들어야 할 수 있습니다. 생성 비율이 너무 높아지면 DOS (서비스 거부) 공격을 방지하기 위해 할당량 확인이 이루어지므로 할당량 문제로 인해 일부 요청이 다시 실패할 수 있습니다. 이 경우 재시도를 위한 백오프 전략을 사용하여 재생성 속도를 낮춥니다.

드라이버 앱의 상태 손실

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

FAQ

운전자가 고장 난 작업을 위해 멈춘 경우 어떻게 해야 하나요?

이 경우 먼저 작업 순서를 업데이트한 다음 정상적으로 진행하여 정류장 도착, 작업 완료, 기타 세부정보로 표시합니다. 그렇지 않으면 시스템이 일관되지 않고 도착예정시간이 잘못되거나 예기치 않은 오류가 보고될 수 있습니다.