Начните работу с Fleet Engine для отслеживания поставок

Смоделируйте деятельность своего автопарка на первой и последней миле поставок с помощью API Fleet Engine Delivery. Вы можете использовать этот API с помощью Driver SDK для Android и iOS или напрямую с помощью вызовов HTTP REST или gRPC.

Начальная настройка

Вы настраиваете API доставки Fleet Engine в Google Cloud Console.

• Информацию о действиях, которые необходимо выполнить в консоли, и о том, как создать веб-токен JSON для авторизации, см. в разделе Аутентификация и авторизация .

• Подробности об использовании консоли см. в документации Google Cloud Console .

Проверьте настройки

После создания сервисных учетных записей убедитесь, что настройка завершена и вы можете создать средство доставки. Немедленная проверка настроек гарантирует, что вы устранили распространенные проблемы с авторизацией, которые могут возникнуть при настройке вашего проекта. Есть два способа проверить настройки:

• Проверьте две ключевые части вашей установки: подписание токена авторизации и создание пробного средства доставки с помощью утилиты командной строки gcloud . Подробную информацию см. в руководстве «Проверка установки» .

• Проверьте свою настройку с помощью примеров сценариев аутентификации Fleet Engine .

Клиентские библиотеки

Чтобы разработчикам было удобнее использовать необработанный gRPC или REST, используйте клиентские библиотеки на нескольких распространенных языках программирования. Инструкции о том, как получить клиентские библиотеки для вашего серверного приложения, см. в разделе Клиентские библиотеки .

Примеры Java в этой документации предполагают, что вы знакомы с gRPC.

Структуры данных

API Fleet Engine Delivery использует две структуры данных для моделирования получения и доставки отправлений:

• Транспортное средство, используемое для перевозки груза.
• Задачи по приему и доставке груза.

Вы также можете использовать задачи для моделирования перерывов водителя и запланированных остановок в течение дня.

Транспортные средства доставки

Транспортные средства доставки доставляют грузы со склада в пункт доставки и из пункта выдачи на склад. В некоторых случаях они также могут доставить груз непосредственно из места получения в место доставки.

Используйте Driver SDK, чтобы создать объект DeliveryVehicle в Fleet Engine и отправлять обновления местоположений для отслеживания отгрузки и автопарка.

Задания

Для действий, которые совершает машина в течение дня, вы назначаете задачи по типу действия:

• Для самовывоза и доставки назначьте задачи по доставке .
• На случай, если водители недоступны, например, во время необходимых перерывов, назначайте задачи по недоступности .
• Для задач, не связанных с вождением, в почтовых ящиках или местах расположения клиентов назначьте задачи плановой остановки .

Каждая назначенная вами задача должна иметь уникальный идентификатор задачи, но задачи могут использовать один и тот же идентификатор отслеживания. Когда Fleet Engine вычисляет окна ETA для каждой задачи, он использует все задачи и порядок, в котором они запланированы, для оценки. Дополнительные сведения об идентификаторах задач см. в разделе Рекомендации по идентификаторам задач .

Для создания задач в Fleet Engine используйте диспетчер задач Driver SDK.

Задачи по отгрузке

Создайте задачи по отправке как для получения, так и для доставки отправления и включите следующую информацию:

• Место самовывоза или доставки.
• Номер отслеживания или идентификатор.
• Время ожидания, учитывающее дополнительное время на выполнение задачи, поиск парковки или прогулку к месту передачи.
• Уникальный идентификатор задачи. См. рекомендации по идентификаторам задач .

Для получения дополнительной информации см. следующие темы:

Андроид

• Создайте задачу получения груза
• Создайте задачу доставки отправления

iOS

• Менеджер задач доставки GMTD .
• ГМТСтасктип

Задачи недоступности

Задачи недоступности охватывают периоды времени, когда транспортное средство недоступно для получения или доставки, например перерывы для дозаправки автомобиля или перерывы для отдыха водителя.

Создайте задачу недоступности со следующей информацией:

• Продолжительность перерыва.
• Необязательно, место разрыва. Вам не обязательно указывать конкретное местоположение, но это позволит получить более точные окна расчетного времени прибытия в течение дня.

Примечание. Во время задачи недоступности никакая информация о местоположении не передается конечным пользователям библиотеки отслеживания поставок. Однако он доступен менеджерам автопарков, использующим библиотеку отслеживания автопарка.

Для получения дополнительной информации см. следующие темы:

Андроид

• Запланированная недоступность

iOS

• Менеджер задач доставки GMTD .
• ГМТСтасктип

Запланированные остановки задач

Создавайте задачи запланированных остановок, чтобы моделировать остановки, которые необходимо совершить транспортному средству доставки. Например, создайте задачу запланированной остановки для ежедневной запланированной остановки выдачи в определенном месте, независимо от других доставок или самовывозов в том же месте. Вы также можете создавать задачи запланированной остановки для сбора данных из ящиков или для моделирования пересадок или остановок подвозящих транспортных средств в сервисных центрах и точках обслуживания.

Для получения дополнительной информации см. следующие темы:

Андроид

• Запланированные остановки

iOS

• Менеджер задач доставки GMTD .
• ГМТСтасктип

Рекомендации по идентификатору задачи

При создании идентификаторов задач следуйте следующим рекомендациям по содержанию и формату:

• Создавайте уникальные идентификаторы задач
• Не раскрывайте какую-либо личную информацию (PII) или данные в виде открытого текста.
• Используйте допустимые строки Unicode.
• Используйте 64 или меньше символов.
• Не включайте следующие символы ASCII: «/», «:», «\", «?» или «#».
• Нормализовать в соответствии с формой нормализации Unicode C.

Совет: Вы можете создавать идентификаторы задач, используя любой программный механизм, который вы предпочитаете. Google рекомендует использовать инструмент UUID версии 4 .

Ниже приведены примеры хороших идентификаторов задач:

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

В следующей таблице показаны примеры неподдерживаемых идентификаторов задач:

Неподдерживаемые идентификаторы задач	Причина
31.08.2019-20:48-46.70746,-130.10807,-85.17909,61.33680	Нарушаются требования к PII и символам: запятые, точки, двоеточия и косая черта.
JohnDoe-577b484da26f-Купертино-Санта-Круз	Нарушает требования PII.
4R0oXLToF"112 Саммер Доктор Ист Хартфорд, CT06118"577b484da26f8a	Нарушаются требования к PII и символам: пробелы, запятые и кавычки. Длиннее 64 символов.

Больше ресурсов

Чтобы просмотреть конкретные поля, содержащиеся в каждой структуре данных, см. справочную документацию по API для DeliveryVehicle ( gRPC , REST ) и Task ( gRPC , REST ).

Жизнь автомобиля

Объект DeliveryVehicle представляет средство доставки первой или последней мили. Вы создаете объект DeliveryVehicle , используя:

• Идентификатор проекта Google Cloud, который содержит учетную запись службы, используемую для вызова API Fleet Engine.
• Идентификатор автомобиля, принадлежащего клиенту.

Используйте идентификаторы транспортных средств, уникальные для каждого транспортного средства. Не используйте повторно идентификатор транспортного средства, если для исходного транспортного средства нет активных задач.

Fleet Engine автоматически удаляет объекты DeliveryVehicle , которые не были обновлены с помощью UpdateDeliveryVehicle через семь дней. Чтобы узнать, существует ли транспортное средство:

1. Вызовите UpdateDeliveryVehicle .
2. Если вы получили ошибку NOT_FOUND , вызовите CreateDeliveryVehicle , чтобы воссоздать транспортное средство. Если вызов возвращает транспортное средство , оно все равно доступно для обновления.

Примечание. Если вы вызываете CreateDeliveryVehicle с уже существующей парой идентификатора проекта и идентификатора транспортного средства, вы получите сообщение об ошибке.

Типы транспортных средств

Сущность VehicleType содержит необязательное поле VehicleType , содержащее перечисление Category , которое вы можете указать как AUTO , TWO_WHEELER , BICYCLE или PEDESTRIAN . Если вы не зададите это поле, по умолчанию оно будет иметь значение AUTO .

Все маршруты для транспортных средств используют соответствующий RouteTravelMode для типа транспортного средства.

Атрибуты автомобиля

Сущность DeliveryVehicle содержит повторяющееся поле DeliveryVehicleAttribute . API ListDeliveryVehicles включает поле filter , которое может ограничивать возвращаемые сущности DeliveryVehicle только теми, у которых есть указанные атрибуты. DeliveryVehicleAttribute не влияет на поведение маршрутизации Fleet Engine.

Не включайте в атрибуты личную информацию (PII) или конфиденциальную информацию, поскольку это поле может быть видно пользователям.

Жизнь задачи

Вы можете создавать, обновлять и запрашивать задачи в Fleet Engine с помощью интерфейсов API доставки gRPC или REST.

Объект Task имеет поле состояния, позволяющее отслеживать его продвижение по жизненному циклу. Значения изменяются от ОТКРЫТО к ЗАКРЫТО. Новые задачи создаются в состоянии OPEN, что означает, что либо:

• Задача пока не поставлена ​​на средство доставки.
• Транспортное средство доставки еще не проехало назначенную для задачи остановку.

Рекомендации по выполнению задач

Назначать задачу транспортному средству можно только тогда, когда он находится в состоянии ОТКРЫТО.

Вы отменяете задачу, удаляя ее из списка остановок транспортных средств, что автоматически устанавливает состояние задачи ЗАКРЫТО.

Когда транспортное средство задачи завершает остановку транспортного средства задачи:

1. Обновите поле результата задачи на УСПЕШНО или НЕУДАЧНО.

   Примечание. Вы можете установить результат задачи в любое время до или после ее завершения, но установить его можно только один раз.

2. Укажите временную метку события.

   Библиотека отслеживания поставок JavaScript затем указывает результат выполнения задачи, и статус задачи автоматически устанавливается на ЗАКРЫТО. Дополнительную информацию см. в разделе Отслеживание доставки с помощью библиотеки отслеживания доставки JavaScript .

Как и в случае с транспортными средствами, Fleet Engine удаляет задачи, которые не были обновлены, по истечении семи дней, а если вы попытаетесь создать задачу с уже существующим идентификатором, она вернет ошибку.

Примечание. Fleet Engine не поддерживает явное удаление задачи. Сервис автоматически удаляет задачи через семь дней без обновлений. Если вы хотите хранить данные задачи дольше семи дней, вам необходимо реализовать эту возможность самостоятельно.

Атрибуты задачи

Сущность Task содержит повторяющееся поле TaskAttribute , которое может иметь значение одного из трех типов: строка, число и логическое значение. API ListTasks включает поле filter , которое может ограничивать возвращаемые сущности Task только теми, которые имеют указанные атрибуты. Атрибуты задачи не влияют на поведение маршрутизации Fleet Engine.

Не включайте в атрибуты личную информацию (PII) или другую конфиденциальную информацию, поскольку эти атрибуты могут быть видны пользователям.

Управляйте жизненным циклом транспортных средств и задач

Напоминание: ваша внутренняя система выступает в качестве надежного источника данных, которые API Fleet Engine Delivery дополняет от вашего имени.

Чтобы управлять жизненными циклами транспортных средств и задач в вашей системе, используйте API Fleet Engine Deliveries для создания, обновления и отслеживания ваших транспортных средств и связанных с ними задач.

В то же время приложение-драйвер напрямую связывается с Fleet Engine для обновления информации о местоположении устройства и маршруте. Эта модель позволяет Fleet Engine эффективно управлять местоположением в режиме реального времени. Он отправляет местоположение непосредственно в библиотеку отслеживания, которую затем можно использовать для информирования потребителей о статусе их заказа.

Например, предположим, что у вас есть следующий сценарий:

• Водитель приближается к остановке доставки. Приложение-драйвер отправляет свое местоположение в Fleet Engine.
• Fleet Engine отправляет местоположение устройства в библиотеку отслеживания, которую ваше потребительское приложение использует, чтобы предупредить потребителя о близости его посылки.
• После того, как водитель завершит доставку, он нажимает кнопку «Доставка доставлена» в приложении водителя.
• Действие «Отгрузка доставлена» отправляет информацию в вашу серверную систему, которая выполняет необходимые шаги по проверке и проверке бизнеса.
• Ваша система подтверждает, что задача ВЫПОЛНЕНА, и обновляет Fleet Engine с помощью API доставки.

Следующая диаграмма иллюстрирует эти процессы на общем уровне. Он также показывает стандартные отношения между вашей системой, клиентом и Fleet Engine.

Управление клиентскими токенами

Для обновлений местоположения, исходящих из приложения драйвера и отправляемых непосредственно в Fleet Engine, требуются токены авторизации. Вот рекомендуемый подход для обработки обновлений от клиента до Fleet Engine:

1. Создайте токен, используя роль учетной записи службы ненадежного пользователя-драйвера Fleet Engine Delivery .

2. Предоставьте приложению драйвера токен ограниченной области действия. Эта область позволяет обновлять местоположение устройства только в Fleet Engine.

Такой подход гарантирует, что вызовы, исходящие с мобильных устройств (считающихся средами с низким уровнем доверия), соответствуют принципу наименьших привилегий .

Другие роли учетной записи службы

Если вместо этого вы хотите разрешить приложениям-драйверам выполнять прямые обновления Fleet Engine, помимо тех, которые ограничены ролью ненадежного драйвера, например, для обновлений определенных задач, вы можете использовать роль доверенного драйвера. Информацию о модели, использующей роль доверенного драйвера, см. в разделе Модель доверенного драйвера .

Дополнительные сведения об использовании ненадежных и доверенных ролей драйвера см. в разделе Настройка облачного проекта .

Смоделируйте рабочий день

В следующей таблице показано, как может выглядеть рабочий день водителей первой и последней мили в компании по доставке и логистике. Ваша компания может отличаться в деталях, но вы можете увидеть, как можно смоделировать рабочий день.

Время	Активность	Моделирование
В течение 24 часов с начала суток	Диспетчер распределяет грузы по средствам доставки или маршрутам.	Вы можете заранее создавать задачи для доставки, получения, перерывов и других задач в Fleet Engine. Например, вы можете создать задачу получения груза , задачу доставки груза , запланированную недоступность или запланированную остановку . Назначайте задачи транспортному средству после того, как будет определен набор комплектов поставки и порядок их доставки.
Начало дня	Водитель начинает день в депо с входа в приложение «Водитель».	Инициализируйте API драйвера доставки. При необходимости создайте средство доставки в Fleet Engine.
	Водитель загружает грузы в автомобиль доставки, сканирует грузы.	Если задачи по доставке отправлений не были созданы заранее, создайте задачи по доставке отправлений во время сканирования.
	Водитель подтверждает порядок выполнения задач.	Если они не были созданы заранее, создайте задачи получения груза , запланированную недоступность и запланированные остановки .
	Водитель покидает депо и берет на себя обязательство выполнить следующее количество задач.	Назначьте транспортному средству все задачи или подмножество задач, зафиксировав порядок их выполнения.
	Водитель доставляет посылку.	После прибытия на остановку доставки выполнить действия, связанные с прибытием транспортного средства на остановку . После доставки груза закройте задачу доставки и при необходимости сохраните статус отправления и другую метаинформацию . После выполнения всех задач на остановке и перед началом движения до следующей остановки выполнить действия, связанные с завершением остановки ТС и движением ТС до следующей остановки .
	Водитель встречает транспортное средство, чтобы перегрузить дополнительные грузы на транспортное средство доставки.	Место встречи для пересадки между транспортными средствами подачи и доставки должно быть смоделировано как запланированная остановка . После передачи и сканирования отправлений создайте задачи доставки , если они еще не созданы. Затем обновите порядок выполнения задач, назначив задачи транспортному средству и обновив порядок задач .
	Водитель получает уведомление о запросе на получение.	После принятия заявки на самовывоз создайте задачу на получение отправления . Затем обновите порядок выполнения задач, назначив задачи транспортному средству и обновив порядок выполнения задач .
Полдень	Водитель берет перерыв на обед.	Если расположение связано с задачей недоступности, рассматривайте ее как любую другую задачу. Выполнять действия, связанные с прибытием транспортного средства на остановку , завершением остановки и движением транспортного средства к следующей остановке . В противном случае никаких дальнейших действий до конца перерыва не требуется. Удалите задачу, подтвердив следующую и оставшиеся задачи и обновив порядок задач .
	Водитель забирает посылку.	Это моделируется так же, как остановка доставки. Выполнять действия, связанные с прибытием транспортного средства на остановку и закрытием задачи и, при необходимости, сохранением статуса отправки и другой метаинформации . После выполнения всех задач на остановке и перед началом движения до следующей остановки выполнить действия, связанные с завершением остановки ТС и движением ТС до следующей остановки . Примечание. Чтобы обеспечить правильность выставления счетов, все самовывозы должны иметь соответствующую задачу по доставке. Если в тот же день пикап должен быть доставлен в другое место на том же маршруте водителя, мы рекомендуем смоделировать эту задачу доставки как любую другую задачу доставки на маршруте. Если водитель везет самовывоз обратно в депо, рекомендуем создать задачу доставки в пункт назначения депо.
	Водитель делает запланированную остановку, чтобы забрать груз из почтового ящика.	Это моделируется так же, как и любая другая остановка пикапа. Выполнение действий, связанных с прибытием транспортного средства на остановку и закрытием задачи . Выполнив все задачи на остановке и начав движение до следующей остановки, выполнить действия, связанные с завершением остановки транспортного средства и движением транспортного средства к следующей остановке .
	Водитель получает уведомление о перенаправлении груза в альтернативное место.	Установите статус исходной задачи доставки отправления на ЗАВЕРШЕНО и создайте новую задачу доставки отправления для нового места доставки. Дополнительную информацию см. в разделе Перенаправление груза .
	Водитель попытался доставить посылку, но не смог этого сделать.	Это моделируется аналогично успешной остановке доставки, отмечая задачу доставки как выполненную. Выполнять действия, связанные с прибытием транспортного средства на остановку . Если не удалось доставить груз, закройте задачу и, при необходимости, сохраните статус отправления и другую метаинформацию . После выполнения всех задач на остановке и перед началом движения до следующей остановки выполнить действия, связанные с завершением остановки ТС и движением ТС до следующей остановки .
	Водитель был уведомлен о необходимости задержать (не доставить) груз.	После получения и подтверждения уведомления установите статус задачи ЗАВЕРШЕНО.
	Водитель был уведомлен о необходимости доставить определенную партию следующей, что изменило зафиксированный заказ на доставку.	Обновите порядок задач .
	Водитель решает доставить груз не по порядку.	Обновите порядок задач и действуйте как обычно.
	Водитель доставляет несколько отправлений в одно место.	Это моделируется аналогично остановке доставки одной партии. После прибытия на остановку выполнить действия, связанные с прибытием транспортного средства на остановку . После доставки каждого груза закройте каждую задачу и, при необходимости, сохраните статус отправления и другую метаинформацию . После выполнения всех задач на остановке и перед началом движения до следующей остановки выполнить действия, связанные с завершением остановки ТС и движением ТС до следующей остановки .
Конец дня	Водитель возвращается в депо.	Если водитель возвращается на склад с грузом, полученным во время его маршрута, вам также необходимо создать и закрыть каждую посылку как задачу доставки, чтобы обеспечить правильность выставления счетов. Вы можете сделать это, смоделировав депо, как и любую другую остановку доставки. Если склад не используется в качестве остановки доставки, вы все равно можете смоделировать его как запланированную остановку. Моделирование остановки позволяет вашим водителям видеть обратный путь до депо и прогнозировать предполагаемое время прибытия.

Как работают обновления местоположения

Для обеспечения максимальной производительности Fleet Engine предоставьте ему поток обновлений о местоположении транспортных средств. Используйте любой из следующих способов для предоставления этих обновлений:

1. Используйте Driver SDK — Android , iOS — самый простой вариант.
2. Используйте собственный код . Это полезно, если местоположения передаются через серверную часть или если вы используете устройства, отличные от Android или iOS.

Независимо от того, как вы предоставляете обновления о местонахождении транспортных средств, ваш сервер отвечает за обновление Fleet Engine, когда транспортное средство доставки направляется к остановке (включая депо) и когда оно прибывает на остановку . Fleet Engine не обнаруживает эти события автоматически.

Остановки транспортных средств и места доставки

Остановка транспортного средства — это место, где средство доставки выполняет задачу по доставке или какую-либо другую задачу. Это либо точка доступа, например погрузочная площадка, либо место с привязкой к дороге.

Местом доставки является место, где груз доставляется или забирается. Чтобы добраться до места доставки и обратно, может потребоваться некоторая прогулка от остановки автомобиля.

Например, когда водитель доставляет товар в магазин в торговом центре, машина доставки останавливается на парковке торгового центра возле ближайшего входа в магазин. Это остановка транспорта. Затем водитель идет от остановки автомобиля к месту в торговом центре, где расположен магазин. Это место доставки.

Чтобы обеспечить удобство отслеживания доставки для ваших пользователей, рассмотрите, как задачи по отправке назначаются остановкам транспортных средств, и имейте в виду, что количество оставшихся остановок транспортных средств для задач по отправке сообщается пользователю, чтобы помочь им отслеживать ход выполнения своей перевозки.

Например, если водитель осуществляет множество доставок в одно офисное здание, рассмотрите возможность назначения всех задач по доставке на одну остановку автомобиля. Если каждая задача доставки назначена отдельной остановке транспортного средства, отслеживание груза будет менее полезным для ваших пользователей, поскольку отслеживание становится доступным только в том случае, если транспортное средство находится в пределах ограниченного количества остановок транспортного средства до пункта назначения. Завершение большого количества остановок транспортных средств за короткое время не дает пользователю много времени, которое можно было бы использовать для отслеживания хода их доставки.

Используйте мобильные SDK

Прежде чем выполнять какие-либо вызовы Driver SDK, обязательно инициализируйте его.

Инициализация API драйвера доставки

Прежде чем инициализировать API драйвера доставки в Driver SDK, обязательно инициализируйте Navigation SDK . Затем инициализируйте 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));
     }
   });

Примечание. Driver SDK содержит API для нескольких вертикалей, включая доставку. Чтобы уменьшить общий размер двоичного файла, используйте ProGuard или какой-либо другой инструмент оптимизации, чтобы удалить неиспользуемый код.

Случаи использования

В этом разделе описывается, как использовать API доставки для моделирования распространенных случаев использования.

Уникальные идентификаторы объектов

Формат и значение уникальных идентификаторов объектов, используемых в вызовах REST, непрозрачны для Fleet Engine. Избегайте использования автоматически увеличивающихся идентификаторов и убедитесь, что идентификатор не содержит никакой личной информации (PII), такой как номер телефона водителя.

Создать автомобиль

Вы можете создать автомобиль либо из Driver SDK , либо из серверной среды с помощью gRPC или REST.

gRPC

Чтобы создать новый автомобиль, вы вызываете CreateDeliveryVehicle к Fleet Engine. Используйте объект CreateDeliveryVehicleRequest , чтобы определить атрибуты нового средства доставки. Обратите внимание, что любое значение, указанное в поле Name , игнорируется в соответствии с рекомендациями API для идентификаторов, указанных пользователем . Вы должны использовать поле DeliveryVehicleId , чтобы установить идентификатор транспортного средства.

При создании DeliveryVehicle вы можете указать следующие поля:

• Атрибуты
• Последнее местоположение
• Тип

Не устанавливайте никаких других полей. Если вы это сделаете, Fleet Engine вернет ошибку, поскольку эти поля либо доступны только для чтения, либо могут быть обновлены только с помощью вызова UpdateDeliveryVehicle .

Чтобы создать транспортное средство без установки каких-либо дополнительных полей, вы можете оставить поле DeliveryVehicle незаданным в CreateDeliveryVehicleRequest .

В следующем примере показано, как использовать библиотеку 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;
    }

ОТДЫХ

Чтобы создать транспортное средство из серверной среды, выполните HTTP REST-вызов CreateDeliveryVehicle :

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

<id> — уникальный идентификатор транспортного средства в вашем автопарке.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело POST представляет собой создаваемую сущность DeliveryVehicle . Вы можете указать следующие необязательные поля:

• атрибуты
• последнее местоположение
• тип

Пример команды 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 игнорирует поле name сущности DeliveryVehicle в соответствии с рекомендациями API для идентификаторов, указанных пользователем . Не устанавливайте никаких других полей. Если вы это сделаете, Fleet Engine вернет ошибку, поскольку эти поля либо доступны только для чтения, либо могут быть обновлены только с помощью вызова UpdateDeliveryVehicle .

Чтобы создать транспортное средство без заполнения каких-либо полей, оставьте тело запроса POST пустым. Затем вновь созданное транспортное средство извлекает идентификатор транспортного средства из параметра deliveryVehicleId в URL-адресе POST.

Пример команды 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

В следующем примере показано, как использовать библиотеку Java 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;
}

ОТДЫХ

Чтобы создать задачу получения груза из серверной среды, выполните HTTP REST-вызов CreateTask :

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

<id> — уникальный идентификатор задачи. Это не должен быть номер отслеживания посылки. Если в вашей системе нет идентификаторов задач, вы можете создать универсальный уникальный идентификатор (UUID).

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность Task :

• Обязательные поля:

  Поле	Ценить
  тип	Тип.ПИККУП
  состояние	Государство.ОТКРЫТО
  Идентификатор отслеживания	Номер или идентификатор, который вы используете для отслеживания отправления.
  запланированоМестоположение	Место, где должна быть выполнена задача, в данном случае место получения груза.
  TaskDuration	Ожидаемое время в секундах, необходимое для получения груза в пункте выдачи.

• Необязательные поля:

  Поле	Ценить
  таргеттимевиндов	Временной интервал, в течение которого задача должна быть выполнена. Это не влияет на поведение маршрутизации.
  атрибуты	Список пользовательских атрибутов задачи. Каждый атрибут должен иметь уникальный ключ.

Все остальные поля сущности игнорируются при создании. Fleet Engine выдает исключение, если запрос включает назначенный deliveryVehicleId . Вы назначаете задачи с помощью 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

В следующем примере показано, как использовать библиотеку Java 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;
}

ОТДЫХ

Чтобы создать задачу доставки груза из серверной среды с помощью gRPC или REST, выполните HTTP REST-вызов CreateTask :

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

<id> — уникальный идентификатор задачи. Это не должен быть номер отслеживания посылки. Если в вашей системе нет идентификаторов задач, вы можете создать универсальный уникальный идентификатор (UUID).

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность Task :

• Обязательные поля:

  Поле	Ценить
  тип	Тип.ДОСТАВКА
  состояние	Государство.ОТКРЫТО
  Идентификатор отслеживания	Номер или идентификатор, который вы используете для отслеживания отправления.
  запланированоМестоположение	Место, где должна быть выполнена задача, в данном случае место доставки этой партии.
  TaskDuration	Ожидаемое время в секундах, необходимое для доставки груза в место доставки.

• Необязательные поля:

  Поле	Ценить
  таргеттимевиндов	Временной интервал, в течение которого задача должна быть выполнена. Это не влияет на поведение маршрутизации.
  атрибуты	Список пользовательских атрибутов задачи. Каждый атрибут должен иметь уникальный ключ.

Все остальные поля сущности игнорируются при создании. Fleet Engine выдает исключение, если запрос включает назначенный идентификатор DeliveryVehicleId. Вы назначаете задачи с помощью 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

В следующем примере показано, как использовать библиотеку Java 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;
}

ОТДЫХ

Чтобы создать задачу доставки и получения из серверной среды, выполните HTTP REST-вызов BatchCreateTasks :

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

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность BatchCreateTasksRequest :

• Обязательные поля:

  Поле	Ценить
  Запросы	Массив CreateTasksRequest

• Необязательные поля:

  Поле	Ценить
  заголовок	`DeliveryRequestHeader`

Каждый элемент CreateTasksRequest в requests должен проходить те же правила проверки, что и запрос CreateTask , за исключением того, что parent поля и поля header являются необязательными. Если они установлены, они должны быть идентичны соответствующим полям на верхнем уровне BatchCreateTasksRequest . См. раздел «Создание задачи получения груза» и «Создание задачи доставки груза», чтобы узнать о конкретных правилах проверки для каждого из них.

Дополнительные сведения см. в справочной документации по API для BatchCreateTasks ( 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. Запланированная задача недоступности не должна включать идентификатор отслеживания. При желании вы можете указать местоположение.

gRPC

В следующем примере показано, как использовать библиотеку Java 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;
    }

ОТДЫХ

Чтобы создать задачу недоступности из серверной среды, выполните HTTP REST-вызов CreateTask :

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

<id> — уникальный идентификатор задачи. Если в вашей системе нет идентификаторов задач, вы можете создать универсальный уникальный идентификатор (UUID).

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность Task :

• Обязательные поля:

  Поле	Ценить
  тип	Тип.НЕДОСТУПЕН
  состояние	Государство.ОТКРЫТО
  TaskDuration	Продолжительность перерыва в секундах.

• Необязательные поля:

  Поле	Ценить
  запланированоМестоположение	Местоположение перерыва, если его необходимо сделать в определенном месте.

Все остальные поля сущности игнорируются при создании. Fleet Engine выдает исключение, если запрос включает назначенный идентификатор DeliveryVehicleId. Вы назначаете задачи с помощью UpdateDeliveryVehicleRequest . Дополнительные сведения см. в разделах Назначение задач транспортному средству и UpdateDeliveryVehicleRequest .

Пример команды 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. Задача запланированной остановки может не включать идентификатор отслеживания.

gRPC

В следующем примере показано, как использовать библиотеку Java 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;
}

ОТДЫХ

Чтобы создать задачу запланированной остановки из серверной среды, выполните HTTP REST-вызов CreateTask :

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

<id> — уникальный идентификатор задачи. Если в вашей системе нет идентификаторов задач, вы можете создать универсальный уникальный идентификатор (UUID).

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность Task :

• Обязательные поля:

  Поле	Ценить
  тип	Тип.SCHEDULED_STOP
  состояние	Государство.ОТКРЫТО
  запланированоМестоположение	Расположение остановки.
  TaskDuration	Ожидаемая продолжительность остановки в секундах.

• Необязательные поля:

  • Никто

Все остальные поля сущности игнорируются при создании. Fleet Engine выдает исключение, если запрос включает назначенный идентификатор DeliveryVehicleId. Вы назначаете задачи с помощью UpdateDeliveryVehicleRequest . Дополнительные сведения см. в разделах Назначение задач транспортному средству и UpdateDeliveryVehicleRequest .

Пример команды 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

В следующем примере показано, как использовать библиотеку Java 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;
    }

ОТДЫХ

Чтобы установить окно времени задачи с помощью HTTP, вызовите UpdateTask :

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

<id> — уникальный идентификатор задачи.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность Task :

• Обязательные поля:

  Поле	Ценить
  таргеттимевиндов	Временной интервал, в течение которого задача должна быть выполнена. Этот параметр не влияет на поведение маршрутизации.

• Необязательные поля:

  • Никто

Все остальные поля сущности игнорируются при обновлении.

Пример команды 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

В следующем примере показано, как использовать библиотеку Java 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;
}

ОТДЫХ

Чтобы настроить окно конфигурации представления отслеживания задач с использованием HTTP, вызовите UpdateTask :

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

<id> — уникальный идентификатор задачи.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность Task :

• Обязательные поля:

  Поле	Ценить
  задачаТреккингвиевконфиг	Конфигурация отслеживания задач, определяющая, какие элементы данных и при каких обстоятельствах видны конечным пользователям.

• Необязательные поля:

  • Никто

Все остальные поля сущности игнорируются при обновлении.

Пример команды 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;
}

ОТДЫХ

Чтобы обновить порядок задач для транспортного средства из серверной среды, выполните HTTP REST-вызов UpdateDeliveryVehicle :

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

<id> — это уникальный идентификатор средства доставки в вашем парке, для которого вы собираетесь обновить порядок задач. Это идентификатор, который вы указали при создании автомобиля.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность DeliveryVehicle :

• Обязательные поля:

  Поле	Ценить
  оставшееся транспортное средствоJourneySegments	Список сегментов пути для задач в порядке их выполнения. Первая задача в списке выполняется первой.
  restVehicleJourneySegments[i].stop	Остановка для задачи i в списке.
  restVehicleJourneySegments[i].stop.plannedLocation	Планируемое место остановки.
  restVehicleJourneySegments[i].stop.tasks	Перечень задач, которые необходимо выполнить на данной остановке транспортного средства.
  restVehicleJourneySegments[i].stop.state	Государство.НОВОЕ

• Необязательные поля:

  • Никто

Все остальные поля сущности игнорируются при обновлении.

Пример команды curl :

Примечание. Эта команда перезаписывает все remainingVehicleJourneySegments , уже установленные в транспортном средстве доставки.

# 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 должен быть уведомлен, когда транспортное средство трогается с места или начинает навигацию. Вы можете уведомить Fleet Engine либо из Driver SDK , либо из серверной среды с помощью gRPC или REST. Не используйте оба метода, чтобы избежать гонок и сохранить единый источник истины.

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
    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;
    }

ОТДЫХ

Чтобы уведомить Fleet Engine о том, что транспортное средство движется к следующей остановке из серверной среды, выполните HTTP REST-вызов UpdateDeliveryVehicle :

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

<id> — это уникальный идентификатор средства доставки в вашем парке, для которого вы хотите обновить порядок заказа задач. Это идентификатор, который вы указали при создании автомобиля.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность DeliveryVehicle :

• Обязательное поле:

  Поле	Ценить
  оставшееся транспортное средствоJourneySegments	Список оставшихся остановок транспортных средств с указанием их состояний как State.NEW. Состояние первой остановки в списке должно быть отмечено как State.ENROUTE.

• Необязательные поля:

  • Никто

Все остальные поля сущности игнорируются для уведомления.

Пример команды curl :

Примечание. Эта команда перезаписывает все remainingVehicleJourneySegments , уже установленные в транспортном средстве доставки.

# 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 ожидает обновления местоположения не реже одного раза в минуту и ​​не чаще одного раза в 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;
}

ОТДЫХ

Чтобы обновить местоположение автомобиля в Fleet Engine с помощью HTTP REST, вызовите UpdateDeliveryVehicle :

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

<id> — это уникальный идентификатор средства доставки в вашем парке или местонахождение которого вы собираетесь обновить. Это идентификатор, который вы указали при создании автомобиля.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность DeliveryVehicle :

• Обязательное поле:

  Поле	Ценить
  LastLocation.supplementalLocation	Местоположение транспортного средства.
  LastLocation.supplementalLocationTime	Последняя известная временная метка, когда транспортное средство находилось в этом месте.
  LastLocation.supplementalLocationSensor	Должно быть заполнено CUSTOMER_SUPPLIED_LOCATION.

• Необязательные поля:

  Поле	Ценить
  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 должен быть уведомлен, когда транспортное средство прибывает на остановку. Вы можете уведомить Fleet Engine либо из Driver SDK , либо из серверной среды с помощью gRPC или REST. Не используйте оба метода, чтобы избежать гонок и сохранить единый источник истины.

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 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;
}

ОТДЫХ

Чтобы уведомить Fleet Engine о прибытии транспортного средства на остановку из серверной среды, выполните HTTP REST-вызов UpdateDeliveryVehicle :

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

<id> — это уникальный идентификатор средства доставки в вашем парке, для которого вы хотите обновить порядок заказа задач. Это идентификатор, который вы указали при создании автомобиля.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность DeliveryVehicle :

• Обязательные поля:

  Поле	Ценить
  оставшееся транспортное средствоJourneySegments	Остановка, на которую вы прибыли, с состоянием, установленным как State.ARRIVED, за которым следует список оставшихся остановок транспортных средств с их состояниями, отмеченными как State.NEW.

• Необязательные поля:

  • Никто

Все остальные поля сущности игнорируются при обновлении.

Пример команды curl :

Примечание. Эта команда перезаписывает все remainingVehicleJourneySegments , уже установленные в транспортном средстве доставки.

# 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 должен быть уведомлен, когда транспортное средство завершает остановку. Это приведет к тому, что все задачи, связанные с остановкой, будут переведены в состояние ЗАКРЫТО. Вы можете уведомить Fleet Engine либо из Driver SDK , либо из серверной среды с помощью gRPC или REST. Не используйте оба метода, чтобы избежать гонок и сохранить единый источник истины.

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 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;
}

ОТДЫХ

Чтобы уведомить Fleet Engine о завершении остановки из серверной среды, выполните HTTP REST-вызов UpdateDeliveryVehicle :

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

<id> — это уникальный идентификатор средства доставки в вашем парке, для которого вы хотите обновить порядок заказа задач. Это идентификатор, который вы указали при создании автомобиля.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — токен, выпущенный фабрикой токенов Fleet Engine .

Тело запроса должно содержать сущность DeliveryVehicle :

• Обязательные поля:

  Поле	Ценить
  rest_vehicle_journey_segments	Завершенная вами остановка больше не должна находиться в списке оставшихся остановок транспортного средства.

• Необязательные поля:

  • Никто

Все остальные поля сущности игнорируются при обновлении.

Пример команды curl :

Примечание. Эта команда перезаписывает все remainingVehicleJourneySegments , уже установленные в транспортном средстве доставки.

    # 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.

Закрыть задачу

Чтобы закрыть задачу, назначенную транспортному средству, либо уведомите Fleet Engine о том, что транспортное средство завершило остановку, на которой происходит задание , либо удалите его из списка остановок транспортного средства. Для этого можно настроить список оставшихся остановок транспортных средств так же, как при обновлении задания на транспортное средство.

Если задаче еще не назначен автомобиль и ее необходимо закрыть, обновите задачу до состояния ЗАКРЫТО. Однако вы не сможете повторно открыть ЗАКРЫТУЮ задачу.

Закрытие задачи не означает успех или неудачу. Это указывает на то, что задача больше не считается выполняемой. Для отслеживания доставки важно указать фактический результат задачи, чтобы можно было отобразить результат доставки.

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;
}

ОТДЫХ

Чтобы пометить задачу как закрытую из серверной среды, выполните HTTP REST-вызов UpdateTask :

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

<id> — уникальный идентификатор задачи.

Заголовок вашего запроса должен содержать поле Authorization со значением Bearer <token> , где <token> — это токен, выпущенный фабрикой токенов Fleet Engine .

Вы должны включить сущность Task в тело запроса:

• Обязательные поля:

  Поле	Ценить
  состояние	Состояние.ЗАКРЫТО

• Необязательные поля:

  Поле	Ценить
  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 Engine взимает плату только за задачи доставки со статусом УСПЕШНО.

Отмечая результат задачи, Fleet Engine автоматически заполняет местоположение результата задачи последним известным местоположением транспортного средства. Вы можете переопределить это поведение.

gRPC

У вас есть возможность установить местоположение результата задачи при настройке результата. Установка местоположения не позволяет Fleet Engine установить значение по умолчанию для последнего местоположения транспортного средства. Вы также можете перезаписать местоположение результата задачи, установленное Fleet Engine, позднее. Fleet Engine никогда не перезаписывает указанное вами местоположение результата задачи. Вы не можете установить местоположение результата задачи для задачи, для которой не установлен набор результатов задачи. Вы можете установить как результат задачи, так и местоположение результата задачи в одном запросе.

В следующем примере показано, как использовать библиотеку Java 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;
}

ОТДЫХ

Чтобы пометить задачу как выполненную из серверной среды, выполните HTTP REST-вызов UpdateTask :

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

<id> — уникальный идентификатор задачи.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <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, используйте track_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;
}

ОТДЫХ

Чтобы найти транспортное средство в серверной среде, выполните HTTP REST-вызов GetVehicle :

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

<id> — уникальный идентификатор задачи.

<vehicleId> — идентификатор автомобиля, который нужно найти.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <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. Driver SDK не поддерживает поиск задачи.

gRPC

В следующем примере показано, как использовать библиотеку Java 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;
}

ОТДЫХ

Чтобы найти задачу в серверной среде, выполните HTTP REST-вызов GetTask :

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

<id> — уникальный идентификатор задачи.

<taskId> — идентификатор задачи, которую нужно найти.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <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}"

Поиск информации о задаче доставки по идентификатору отслеживания.

Информацию о задаче по отгрузке можно найти следующими способами, каждый из которых имеет отдельную цель:

• по идентификатору задачи : используется такими пользователями, как операторы автопарка, которые имеют доступ к полному представлению данных задачи.
• по идентификатору отслеживания : используется вашим клиентским программным обеспечением для предоставления ограниченной информации конечному пользователю, например, когда посылка ожидается у него дома.

В этом разделе обсуждается поиск информации о задаче по идентификатору отслеживания. Если вы хотите найти задачу по идентификатору задачи, перейдите в раздел «Поиск задачи» .

Чтобы найти информацию по идентификатору отслеживания, вы можете использовать одно из следующих действий:

• Поиск с помощью Java с использованием gRPC
• Поиск с использованием HTTP

Требования к поиску

• Информация о доставке, предоставляемая идентификатором отслеживания, соответствует правилам видимости, указанным в разделе «Контроль видимости отслеживаемых местоположений» .

• Используйте Fleet Engine для поиска информации об отправке по идентификатору отслеживания. Driver SDK не поддерживает поиск информации по идентификатору отслеживания. Чтобы сделать это с помощью Fleet Engine, вы используете среду сервера или браузера.

• Используйте максимально узкий токен, чтобы ограничить риски безопасности. Например, если вы используете токен доставки потребителя, любые вызовы API Fleet Engine Delivery возвращают только информацию, относящуюся к этому конечному пользователю, например, об отправителе или получателе груза. Вся остальная информация в ответах удалена. Дополнительные сведения о токенах см. в разделе Создание веб-токена JSON (JWT) для авторизации .

Поиск с помощью Java с использованием gRPC

В следующем примере показано, как использовать библиотеку Java gRPC для поиска информации о задаче доставки по ее идентификатору отслеживания.

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

Чтобы найти задачу по доставке из браузера, выполните HTTP REST-вызов GetTaskTrackingInfo :

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

<tracking_id> — это идентификатор отслеживания, связанный с задачей.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <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 не поддерживает составление списков задач.

Листинг задач требует широкого доступа к задачам. Листинг задач предназначен только для доверенных пользователей. Используйте Delivery Fleet Reader или токены аутентификации суперпользователя доставки при отправке запросов на список задач.

В списке задач изменены следующие поля:

• VehicleStop.planned_location
• Транспортное средствоStop.state
• VehicleStop.TaskInfo.taskId

Перечисленные задачи можно фильтровать по большинству свойств задач. Синтаксис запроса фильтра см. в AIP-160 . В следующем списке показаны допустимые свойства задачи, которые можно использовать для фильтрации:

• атрибуты
• Delivery_vehicle_id
• состояние
• запланированное_местоположение
• Task_duration
• задача_результат
• Task_outcome_location
• Task_outcome_location_source
• Task_outcome_time
• Идентификатор отслеживания
• тип

Используйте следующие форматы полей на основе предложений по улучшению Google API:

Тип поля	Формат	Пример
Временная метка	RFC-3339	task_outcome_time = 2022-03-01T11:30:00-08:00
Продолжительность	Количество секунд, за которыми следует s	task_duration = 120s
Перечисление	Нить	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 и атрибута задачи. Успешный ответ все равно может быть пустым. Пустой ответ означает, что с предоставленным идентификатором доставкиVehicleId не связаны никакие задачи.

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;
}

ОТДЫХ

Чтобы вывести список задач из браузера, выполните HTTP REST-вызов ListTasks :

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

Чтобы применить фильтр к перечисленным задачам, включите параметр URL-адреса «filter» с фильтрующим запросом с экранированием URL-адреса в качестве его значения.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <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 не поддерживает перечисление средств доставки.

Листинг средств доставки требует широкого доступа к средствам доставки и предназначен только для доверенных пользователей. Используйте средство чтения парка доставки или токены аутентификации суперпользователя доставки при отправке запросов на список транспортных средств доставки.

Следующие поля в списке средств доставки удалены из-за их влияния на размер ответа:

• ТекущийRouteSegment
• Оставшиеся сегменты путешествия транспортного средства

Вы можете фильтровать список средств доставки по свойству их attributes . Например, чтобы запросить атрибут с ключом my_key и значением my_value , используйте attributes.my_key = my_value . Чтобы запросить несколько атрибутов, объедините запросы, используя логические операторы AND и OR , как в attributes.key1 = value1 AND attributes.key2 = value2 . См. AIP-160 для полного описания синтаксиса запроса фильтра.

Вы можете фильтровать перечисленные средства доставки по местоположению, используя параметр запроса viewport . Параметр запроса viewport определяет области просмотра с использованием двух ограничивающих координат: пары координат high (северо-восток) и low (юго-запад) широты и долготы. Запросы отклоняются, если они содержат высокую широту, которая географически ниже низкой широты.

Примечание. Если вы не укажете запрос фильтра или область просмотра, ответ будет включать все средства доставки.

Списки средств доставки по умолчанию разбиты на страницы с использованием разумного размера страницы. Если вы укажете размер страницы, запрос вернет только количество транспортных средств, указанное в лимите, или меньше. Если запрошенный размер страницы превышает внутреннее максимальное значение, используется внутренний максимум. Размер страницы по умолчанию и максимальный размер страницы — 100 автомобилей.

Список средств доставки может включать в себя токен для чтения следующей страницы результатов. Токен страницы присутствует в ответе только тогда, когда для получения доступны дополнительные страницы средств доставки. Чтобы получить следующую страницу задач, используйте токен страницы с запросом, который в остальном идентичен предыдущему запросу.

gRPC

В следующем примере показано, как использовать библиотеку Java 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;
}

ОТДЫХ

Чтобы вывести список задач из браузера, выполните HTTP REST-вызов ListDeliveryVehicles :

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

Чтобы применить фильтр к перечисленным задачам, включите параметр URL-адреса «filter» с фильтрующим запросом с экранированием URL-адреса в качестве его значения.

Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <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"

Отслеживание посылки

У вас есть два варианта использования API Fleet Engine Delivery для отслеживания поставок:

• Предпочтительно: используйте библиотеку отслеживания поставок JavaScript . Библиотека позволяет визуализировать местоположение транспортных средств и интересных мест, отслеживаемых в Fleet Engine. Он содержит компонент карты JavaScript, который является полной заменой стандартного объекта google.maps.Map, а также компоненты данных для подключения к Fleet Engine. Этот компонент позволяет вам обеспечить настраиваемое анимированное отслеживание доставки через веб-приложение или мобильное приложение.

• Внедрите собственное отслеживание отправлений поверх API Fleet Engine Deliveries.

Ключевым моментом является поиск задач по доставке по идентификатору отслеживания .

Если вы используете роль потребителя доставки, любые вызовы API Fleet Engine Delivery возвращают только информацию, имеющую отношение к отправителю или получателю. Вся остальная информация в ответах удалена. Вы несете ответственность за аутентификацию конечных пользователей. Кроме того, информация о местоположении фильтруется на основе уже выполняемой задачи. Во время задачи недоступности конечным пользователям не передается никакая информация о местоположении.

Ведение журнала

Вы можете настроить Fleet Engine на отправку журналов RPC в Cloud Logging. Дополнительную информацию см. в разделе Ведение журнала .

Роли авторизации и токены

Как описано в разделе «Управление жизненным циклом транспортных средств и задач» , а также примечаниях к авторизации для отдельных случаев использования , для вызовов Fleet Engine требуется проверка подлинности с помощью веб-токенов JSON, подписанных с использованием учетных данных учетной записи службы. Учетные записи служб, используемые для выдачи этих токенов, могут иметь одну или несколько ролей, причем каждая роль предоставляет свой набор разрешений.

Дополнительные сведения см. в разделе Аутентификация и авторизация .

Устранение распространенных проблем

Если у вас возникнут какие-либо проблемы, обратитесь к следующим разделам.

Устойчивость

Fleet Engine не считается источником истины. Вы несете ответственность за восстановление состояния вашей системы, если это необходимо, не полагаясь на Fleet Engine.

Потерянное состояние в Fleet Engine

При работе с Fleet Engine внедряйте клиенты, чтобы система восстанавливала себя в случае сбоя. Например, когда Fleet Engine пытается обновить транспортное средство, он может ответить ошибкой, указывающей, что транспортное средство не существует. Затем клиент должен воссоздать автомобиль в новом состоянии. Хотя эта проблема возникает редко, убедитесь, что ваша система достаточно устойчива, чтобы справиться с ней.

В крайне маловероятном сценарии катастрофического сбоя Fleet Engine вам может потребоваться воссоздать большую часть или все транспортные средства и задачи. Если скорость создания становится слишком высокой, некоторые запросы могут снова завершиться неудачно из-за проблем с квотами, поскольку проверки квот используются во избежание атак типа «отказ в обслуживании» (DOS). В этом случае замедлите скорость восстановления, используя стратегию отсрочки повторных попыток.

Потерянное состояние в приложении водителя

В случае сбоя приложения драйвера оно должно воссоздать текущее состояние в Driver SDK. Приложение должно попытаться воссоздать задачи, чтобы убедиться в их существовании и восстановить их текущее состояние. Приложение также должно воссоздать и явно задать список остановок для Driver SDK.

Примечание. Эти восстановления должны выполняться автономно, не полагаясь на информацию из Fleet Engine, за исключением ошибок, указывающих, существует ли объект в базе данных и когда он уже существует. Если объект уже существует, эту ошибку можно устранить и обновить объект, используя его идентификатор.

Часто задаваемые вопросы

Что, если водитель остановится из-за невыполнения задачи?

В этом случае сначала обновите порядок выполнения задач, а затем действуйте как обычно, отмечая прибытие на остановку, завершение задачи и другие детали. Если вы этого не сделаете, система может стать нестабильной, расчетное время прибытия может стать неверным, а также могут появиться сообщения о непредвиденных ошибках.