タスクを検索する

このドキュメントでは、サーバーまたはブラウザからタスク情報を検索する方法について説明します。Fleet Engine では、タスクを見つける方法が 2 つあります。

  • タスクを検索する: 次の ID でタスクを検索できます。

    • タスク ID: タスクデータの完全なビューにアクセスできるフリート オペレーターなどのユーザーが使用します。
    • トラッキング ID: クライアント ソフトウェアが、荷物がいつ届くかなど、エンドユーザーに限定的な情報を提供するために使用します。

    タスク ID とタスク トラッキング ID の違いを理解してください。これらは同じではありません。スケジュールされたタスクのガイドの基本的なタスク フィールドをご覧ください。

  • タスクを一覧表示する: タスクへの広範なアクセス権。信頼できるユーザーのみを対象としています。

タスクを検索する

このセクションでは、タスク ID またはトラッキング ID でタスクを検索する方法について説明します。このテストには以下の要件があります。

  • トラッキング ID によるルックアップは、追跡対象オブジェクトの可視性ルールに記載されている可視性ルールに準拠する必要があります。

  • セキュリティ リスクを制限するために、可能な限り狭いトークンを使用します。たとえば、Delivery Consumer Token を使用すると、荷物の配送業者や受取人など、そのエンドユーザーに関連する情報のみが返されます。Fleet Engine は、レスポンス内の他のすべての情報を編集します。トークンの詳細については、JSON ウェブトークンをご覧ください。

タスク ID でタスクを検索する

gRPC または REST を使用して、サーバー環境からタスク ID でタスクを検索できます。次の例は、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;
 }

REST

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

  • <id> は、タスクの一意の ID です。
  • <taskId> は、ルックアップするタスクの ID です。
  • リクエスト ヘッダーには、値が Bearer <token> の Authorization フィールドが含まれている必要があります。ここで、<token> は、サービス アカウントのロールと JSON Web トークンに記載されているガイドラインに従ってサーバーによって発行されます。
  • リクエストの本文は空にする必要があります。
  • ルックアップが成功すると、レスポンスの本文にタスク エンティティが含まれます。

curl コマンドの例:

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

トラッキング ID でタスクを検索する

次の例は、gRPC または GetTaskTrackingInfo への HTTP REST 呼び出しを使用して、配送追跡 ID でタスクを検索する方法を示しています。

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

REST

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

  • <tracking_id> は、タスクに関連付けられたトラッキング ID です。

  • リクエスト ヘッダーには、値が Bearer <token> のフィールド Authorization が含まれている必要があります。ここで、<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 ライブラリと ListTasks への HTTP REST 呼び出しの両方で一覧表示する方法を示しています。

成功レスポンスが空になることもあります。空のレスポンスは、指定された 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;
 }

REST

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

リストに表示されるタスクにフィルタを適用するには、URL エスケープされたフィルタ クエリを値として含む「filter」URL パラメータを含めます。

リクエスト ヘッダーには、値が Bearer <token> のフィールド Authorization が含まれている必要があります。ここで、<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}"

次のステップ