Найти задачи

В этом документе описаны способы поиска информации о задаче на сервере или в браузере. Fleet Engine поддерживает два способа поиска задач:

  • Поиск задач . Вы можете искать задачи по следующим идентификаторам:

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

    Обязательно поймите разницу между идентификатором задачи и идентификатором отслеживания задачи. Они не одинаковы. См. поля основных задач в руководстве по запланированным задачам.

  • Список задач : широкий доступ к задачам, предназначенный только для доверенных пользователей.

Поиск задач

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

  • Поиск по идентификатору отслеживания должен соответствовать правилам видимости, указанным в разделе «Правила видимости для отслеживаемых объектов» .

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

Поиск задачи по идентификатору задачи

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

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

ОТДЫХ

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

  • <id> — уникальный идентификатор задачи.
  • <taskId> — идентификатор задачи, которую нужно найти.
  • Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> выдается вашим сервером в соответствии с рекомендациями, описанными в разделе Роли учетной записи службы и веб-токены JSON .
  • Тело запроса должно быть пустым.
  • Если поиск успешен, тело ответа содержит объект задачи.

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

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

В следующих примерах показано, как выполнять поиск задач по идентификатору отслеживания доставки с помощью gRPC или HTTP REST-вызова GetTaskTrackingInfo .

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

ОТДЫХ

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

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

  • Заголовок запроса должен содержать поле Authorization со значением Bearer <token> , где <token> соответствует правильной роли учетной записи службы. См. Роли учетной записи службы .

  • Если поиск успешен, тело ответа содержит объект 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}"

Список задач

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

Списки с разбивкой на страницы

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

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

Поля при перечислении задач

Fleet Engine редактирует следующие поля при перечислении задач:

  • VehicleStop.planned_location
  • VehicleStop.state
  • VehicleStop.TaskInfo.taskId

Используйте следующие форматы полей на основе предложений по улучшению 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 . Если запрос фильтра не указан, отображаются все задачи.

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

Свойства задачи для списков фильтрации
  • type
  • attributes
  • tracking_id
  • delivery_vehicle_id
  • state
  • planned_location
  • task_duration
  • task_duration_outcome
  • task_outcome
  • task_outcome_location
  • task_outcome_time

Полный список операторов запроса фильтра см. в AIP-160 .

Перечислить примеры задач

В следующем примере показано, как составить список задач для deliveryVehicleId и атрибута задачи как с помощью библиотеки Java gRPC , так и с помощью HTTP REST-вызова ListTasks .

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

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

ОТДЫХ

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

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

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

Успешный поиск предоставляет тело ответа следующей структуры:

    // 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}"

Что дальше