ラスト ワンマイルのフリート ソリューションは現在、一部のお客様のみご利用いただけます。詳しくは、営業担当者までお問い合わせください。

Fleet Engine のスタートガイド

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

Fleet Engine Deliveries API を使用すると、配送の最初と最後のマイルのためのフリートのアクティビティをモデル化できます。Deliveries API は、Android および iOS 向けのドライバ SDK を介して公開され、HTTP REST または gRPC 呼び出しを介して直接使用することもできます。

初期設定

Fleet Engine Deliveries API は Google Cloud Console で構成します。コンソール内で行う手順や、認証用の JSON ウェブトークンを作成する方法については、認証と認可をご覧ください。コンソールの使用方法については、Google Cloud Console のドキュメントをご覧ください。

設定を確認する

サービス アカウントを作成したら、設定が完了し、配送車両を作成できることを確認します。ワークフローのこの段階で確認を行うことで、プロジェクトを設定する際に発生し得る一般的な承認の問題に対処できます。設定を確認するガイドをご覧ください。 このガイドでは、gcloud コマンドライン ユーティリティを使用して、設定の 2 つの主要部分(認証トークンの署名と車両車両の作成)をテストする方法について詳しく説明します。

また、Fleet Engine Auth サンプル スクリプトを使用して設定をテストすることもできます。

クライアント ライブラリ

Google では、複数の一般的なプログラミング言語でクライアント ライブラリを公開しています。これらのライブラリを使用すると、未加工の REST や gRPC よりも優れたデベロッパー エクスペリエンスを提供できます。サーバー アプリケーションのクライアント ライブラリを取得する方法については、クライアント ライブラリをご覧ください。

このドキュメントの Java の例は、gRPC に精通していることを前提としています。

データ構造

Deliveries API は、2 つのデータ構造を使用して配送の集荷と配送をモデル化します。

  • 貨物の輸送に使用される配達手段。
  • 集荷と配送のタスク。

また、タスクを使用して、1 日を通してドライバーの休憩や予定された停車地をモデル化することもできます。

配達手段

配送車両は、デポから配送場所、および受け取り場所からデポまで、輸送します。場合によっては、集荷場所から配送場所に直接配送することもできます。

Driver SDK を使用すると、Fleet Engine に DeliveryVehicle オブジェクトを作成し、配送とフリートの追跡のために位置情報の更新を送信できます。

タスク

各車両にはタスクが割り当てられています。たとえば、集荷や配達のタスク、運転手への必須の休憩時間、ドロップボックスやお客様の立ち寄り場所などを指定できます。受け取りタスクと配送タスクは、異なる配送手段に割り当てられる可能性が高くなります。各タスクには一意のタスク ID が必要ですが、同じトラッキング ID を共有できます。各タスクの到着予定時刻を計算するために、タスクとそれらのスケジュールの順序が使用されます。

Driver SDK タスク マネージャーを使用して Fleet Engine でタスクを作成します。

配送タスク

配送タスクは、荷物の集配に関連するものです。 配送タスクを作成する際には、荷物追跡番号または ID を指定する必要があります。 また、タスクの完了、駐車場の検索、ハンドオフの場所までの追加時間を考慮して、滞留時間を指定する必要があります。

  • 荷物の集荷のための集荷タスクを作成し、集荷場所と荷物追跡番号または ID を指定します。
  • 配送場所と追跡番号または ID を指定して、配送納品タスクを作成します。

利用できないタスク

車両が集荷または配送できない期間に利用できないタスクを作成します。これは、車両への給油の休憩や、運転席の休憩になります。

タスクを作成するときに休憩の長さを指定します。特定の場所で休憩を取る必要はありませんが、場所を指定すると、1 日を通じて正確な到着予定時刻が表示されます。

予定されていた停止タスク

配達車両による停止をモデル化するために、スケジュールされた停止タスクを作成します。たとえば、特定の場所での毎日の集荷の停止予定タスクを、同じ場所での他の配達や集荷とは別に作成できます。ドロップ ボックスからの収集のスケジュール設定された停止タスクを作成したり、サービス センターやサービス ポイントでのフィーダー車両の乗り換えや停車地をモデル化したりすることもできます。

各データ構造に含まれる具体的なフィールドは、DeliveryVehiclegRPCREST)と TaskgRPCREST)の API リファレンス ドキュメントで確認できます。

タスク ID に関するガイドライン

タスク ID は一意である必要があります。個人を特定できる情報(PII)やクリアテキスト データを公開することはできません。

タスク ID は次の形式要件を満たす必要があります。

  • ID は有効な Unicode 文字列である必要があります。
  • ID は 64 文字以下にしてください。
  • ID は、Unicode 正規化フォーム C に従って正規化されます。
  • ID に "/"、":"、"\"、"?"、"#" の ASCII 文字は使用できません。

有効なタスク ID の例を以下に示します。

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

次の表に、無効なタスク ID の例を示します。

タスク ID が無効です 理由
2019/8/31 - 20:48 - 46.70746、-130.10807、-85.17909、61.33680 個人情報(PII)と文字の要件(カンマ、ピリオド、コロン、スラッシュ)に違反しています。
JohnDoe-577b484da26f-クパチーノ-サンタクルス PII の要件に違反している。
4R0oXLToF”112 Summer Dr. East Hartford、CT06118”577b484da26f8a 個人情報(PII)と文字の要件(空白文字、カンマ、引用符)に違反している64 文字を超える。

自動車のライフサイクル

DeliveryVehicle オブジェクトは、ファースト ワンマイルまたはラスト ワンマイルの配達手段を表します。DeliveryVehicle オブジェクトを作成するには、以下を使用します。

  • Fleet Engine API の呼び出しに使用されるサービス アカウントを含む Google Cloud プロジェクトのプロジェクト ID。
  • お客様所有の車両 ID。

車両 ID は車両ごとに一意である必要があります。車両にアクティブなタスクがない限り、別の車両で再利用しないでください。

UpdateDeliveryVehicle を呼び出すときは必ず NOT_FOUND エラーを確認し、必要に応じて CreateDeliveryVehicle を呼び出して新しい車両を作成してください。UpdateDeliveryVehicle で更新されていない DeliveryVehicle オブジェクトは、7 日後に自動的に削除されます。すでに存在するプロジェクト ID と車両 ID のペアで CreateDeliveryVehicle を呼び出すと、エラーが発生します。

車両の属性

DeliveryVehicle エンティティには、DeliveryVehicleAttribute の繰り返しフィールドが含まれています。これらの属性は、フリート エンジンで解釈されません。ListDeliveryVehicles API には、返された DeliveryVehicle のエンティティを、指定された属性を持つエンティティに制限できる filter フィールドが含まれています。

attributes フィールドは Fleet Engine に対して不透明ですが、このフィールドにはユーザーに表示される可能性があるため、属性に個人情報や機密情報を含めないでください。

タスクのライフサイクル

Fleet Engine のタスクは、Deliveries API gRPC インターフェースまたは REST インターフェースを使用して作成、更新、調査できます。

Task オブジェクトには、ライフサイクルを通じた状態の進行状況を追跡するための state フィールドがあります。値は OPEN から CLOSED に移行します。OPEN 状態で新しいタスクが作成され、次のいずれかを示します。

  • タスクはまだ配送車両に割り当てられていません。
  • タスクに割り当てた車両停車地がまだ配送されていない。

タスクは、ステータスが OPEN の車両にのみ割り当てることができます。

タスクは、車両停止のリストから削除することでキャンセルできます。そのステータスは自動的に CLOSED に設定されます。

タスクの車両がタスクの車両停止を完了したら、タスクの出力フィールドを SUCCEEDED または FAILED に更新し、イベントのタイムスタンプを指定します。タスクの結果は、タスクが完了する前後にいつでも設定できますが、設定できるのは 1 回だけです。

JavaScript Shipment Tracking ライブラリは、タスクの結果を示すことができます。タスクのステータスは自動的に CLOSED に設定されます。詳しくは、JavaScript Shipment Tracking Library を使用して配送を追跡するをご覧ください。

車両の場合と同様に、7 日後に更新されていないタスクは削除され、すでに存在する ID でタスクを作成しようとするとエラーが返されます。

注: Fleet Engine では、タスクを明示的に削除することはできません。このサービスは、更新なしで 7 日後にタスクを自動的に削除します。タスクデータを 7 日間を超えて保持する場合は、この機能を自分で実装する必要があります。

Deliveries API の統合

Deliveries API は、信頼できないモデルまたは信頼できるモデルを使用して統合できます。これにより、Driver SDK を使用して実施できる更新が決まります。信頼できないモデルをおすすめします。信頼できるモデルはプレビュー版です。

信頼できないモデル

信頼できないモデルでは、Fleet Engine Delivery の信頼されていないドライバ ユーザーのロールを使用して、配送車両の位置情報を更新する権限を付与します。通常、このロールを持つサービス アカウントによって発行されたトークンは、デリバリー ドライバのモバイル デバイスから使用されます。

信頼できないモデル

信頼できるモデル

プレビュー版の信頼できるモデルでは、Fleet Engine Delivery の信頼できるドライバ ユーザーのロールを使用して、配送車両とタスクの作成および更新(配送車両の場所とタスクのステータスまたは結果の更新を含む)に対する権限を付与します。このロールを持つサービス アカウントによって発行されたトークンは通常、デリバリー ドライバのモバイル デバイスまたはバックエンド サーバーから使用されます。

信頼できるモデル

信頼できるモデルと信頼できないモデルに対して Google Maps Platform のラスト ワンマイル フリート ソリューションが使用するロールの詳細については、Cloud プロジェクトの設定をご覧ください。

モバイル デバイスからの完全な統合は、デバイスを所有および管理している場合にのみ行ってください。それにより、完全に信用することができます。 その後、Driver SDK から直接車両やタスクを作成できます。

注: セキュリティ上の理由により、バックエンド サーバーでのみトークンを発行し、クライアントと共有する必要があります。

勤務日のモデリング

次の表に、配送会社と物流会社で、ファースト ワンマイル ドライバーとラスト ワンマイル ドライバーの 1 日の業務の流れを示します。会社によって詳細が異なる場合がありますが、就業日のモデル化の方法を確認できます。

時間アクティビティモデリング
1 日の始まりから 24 時間以内 作業手配者が配送車両やルートに荷物を割り当てます。 配送、集荷、休憩などのタスクは、事前に Fleet Engine で作成できます。たとえば、配送受け取りタスク配送タスクスケジュール不可予定停止などを作成できます。

タスクは、配送パッケージのセットと配達順序が確定したら、車両に割り当てる必要があります。
1 日の始まり ドライバーは、ドライバー アプリにログインして現場からスタートします。 Delivery Driver API を初期化します。 必要に応じて、Fleet Engine に配送車両を作成します。
ドライバーが配送車両に荷物を積み込み、配送をスキャンする。 配送タスクが事前に作成されていない場合は、スキャン時に配送タスクを作成します
ドライバーが、実行するタスクの順序を確認する。 事前に作成されていない場合は、配送集荷タスクスケジュール不可予定停車を作成します。
ドライバはデポを残し、次に実行されるタスク数にコミットします。 実行順序を commit して、すべてのタスクまたはタスクのサブセットを車両に割り当てます。
ドライバーが荷物を配達します。 停留所に到着したら、停車地に到着した車両に関連する操作を行います。配送後、配送タスクを終了します。必要に応じて、配送ステータスとその他のメタ情報を表示します。 停車地ですべてのタスクを完了し、次の停車地に移動する前に、車両で停車地を完了および車両で次の停車地に到着に関連するアクションを実行します。
ドライバーがフィーダー車両と出会い、その他の荷物を配達車両に引き継ぐ。 フィーダー車両と配送車両間の乗り換えの待ち合わせ場所は、所定の停留所としてモデル化する必要があります。

配送の転送とスキャンが済んでいない場合は、配送タスクを作成します(まだ作成されていない場合)。次に、車両にタスクを割り当ててタスクの順序を更新して、タスクの実行順序を更新します。
ドライバーが集荷リクエストの通知を受け取ります。 受け取りリクエストを承認したら、配送の受け取りタスクを作成します。 次に、車両にタスクを割り当ててタスクの順序を更新して、タスクの実行順序を更新します。
正午 ドライバーが昼食休憩をとる。 利用できないタスクに関連付けられたビジネス情報は、他のタスクと同様に扱います。停車地に到着する車両車両で停車地を完了車両が次の停車地に向かう経路に関連するアクションを実行する。

次のタスクと残りのタスクを確認し、タスクの順序を更新して、タスクを削除します。
ドライバーが荷物を引き取ります。 これは配送の停止地点と同様にモデル化されています。停車地に到着する車両タスクの終了に関連するアクションを実行します。必要に応じて、配送ステータスやその他のメタ情報の保存も可能です。 停車地ですべてのタスクを完了した後、次の停車地に移動する前に、車両で停車地を完了し、車両で次の停車地にナビゲートする操作を実行します。
ドライバーが直送便に集荷するための集荷を予定している。 他の駅 / 停留所と同様にモデル化されています。停車地に到着する車両タスクの終了に関連するアクションを実行します。停車地ですべてのタスクを完了し、次の停車地での運転を開始したら、車両で停車地を完了し、次の停車地に車両で経路を設定する操作を実行します。
ドライバーが、荷物が別の場所に転用されたという通知を受信する。 元の配送タスクのステータスを COMPLETED に設定し、新しい配送場所に対して新しい配送タスクを作成します。詳しくは、配送のルート変更をご覧ください。
ドライバーが荷物を配達しようとしたが、配達できなかった。 これは、配送中止の成功と同様にモデル化され、配送タスクが完了としてマークされます。停車地に到着する車両に関連するアクションを実行します。配送に失敗した場合は、タスクを終了します。必要に応じて、配送ステータスとその他のメタ情報を保存します。 停車地ですべてのタスクを完了した後、次の停車地に移動する前に、車両で停車地を完了し、車両で次の停車地にナビゲートする操作を実行します。
ドライバーに配送を保留にするよう通知されました(配達はしません)。 通知を受信して確認したら、タスクのステータスを COMPLETED に設定します。
次に、特定の荷物を配達するようドライバーに伝え、確約した配達注文を変更しました。 タスクの順序を更新する
ドライバーが荷物を順不同で配送することを選択。 タスクの順序を更新し、通常どおり続行します。
ドライバーが 1 か所に複数の配送を行っている。 これは、1 回の配送の停止地点と同様にモデル化されています。 停車地に到着したら、停車地に到着する車両に関連する操作を行います。各配送が完了したら、各タスクを終了します。必要に応じて、配送ステータスとその他のメタ情報を保存します。停車地ですべてのタスクを完了した後、次の停車地に移動する前に、車両で停車地を完了し、車両で次の停車地にナビゲートする操作を実行します。
1 日の終わり ドライバーが倉庫に戻ります。 モデリングは不要です。オプションで、デポのスケジュールされた停止を作成できます。その後、車両をデポに戻し、到着予定時刻を確認できます。

位置情報の更新について

位置情報の更新は、配送車両が停車地から(ルート案内を含む)移動中、次の駅に到着するまで、Fleet Engine に送信されます。これらのイベントは自動検出されないため、プログラムによって設定する必要があります。移動手段の変更を検出するライブラリを使用して、必要な通知を Fleet Engine に送信する。

建物内に人がいると、位置情報の信号品質が大幅に低下するため、運転者がいないときは位置情報の更新を停止する必要があります。

位置情報の更新頻度は Driver SDK 内で設定できます。デフォルトでは、更新は 10 秒ごとに送信されます。

車両の停留所と配達場所

車両の停留所では、配送車両が発送タスクやその他のタスクを実行します。読み込みホルダーやアクセス スナップ型アクセスなどのアクセス ポイントの場合があります。

配送場所とは、配送または集荷が行われる場所です。配達場所への移動には、車両停留所まで歩くことが必要になる場合があります。

たとえば、ドライバーがショッピング モールの店舗に配送する場合、配達用の車両は最寄りの店舗入口付近のモールの駐車場で停止します。車両の停留所です。ドライバーは車両の停留所から、店舗があるモール内の場所まで歩いていきます。こちらが配送先です。

ユーザーが荷物の配達状況を把握しやすいように、配送タスクの車両への割り当て方法を検討し、配送タスクの残りの車両停止回数は、配送の進行状況を確認できるようにユーザーに報告されることに注意してください。

たとえば、ドライバーが 1 つのオフィスビルに多数の配送を行っている場合は、すべての配送タスクを 1 つの車両停留所に割り当てることを検討してください。各配達タスクがそれぞれの車両停車地に割り当てられている場合、追跡は、車両が配送先までの限られた車両数の制限に達しないと追跡できなくなるため、ユーザーにとっては配送状況の把握が難しくなります。短期間に多数の車両の停止が完了したため、配達状況を追跡するための時間がユーザーに与えられません。

モバイル SDK を使用する

Driver SDK を呼び出す前に、必ず SDK を初期化してください。

Delivery Driver API を初期化する

Driver SDK で Delivery Driver API を初期化する前に、Navigation SDK を初期化します。次に、次の例のように Delivery Driver API を初期化します。

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

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

     @Override
     public void onError(int errorCode) {
       Log.e("TAG", String.format("Error loading Navigator instance: %s", errorCode));
     }
   });

ユースケース

このセクションでは、Deliveries API を使用して一般的なユースケースをモデル化する方法を説明します。

車両の作成

車両は、Driver SDK またはサーバー環境から作成できます。

gRPC

新しい車両を作成するには、Fleet Engine に対して CreateDeliveryVehicle 呼び出しを行います。CreateDeliveryVehicleRequest オブジェクトを使用して、新しい配送車両の属性を定義します。Name フィールドで指定された値は、ユーザー指定 ID の API ガイダンスに従って無視されます。車両 ID を設定するには、DeliveryVehicleId フィールドを使用する必要があります。

DeliveryVehicle を作成するときに、必要に応じて次の 2 つのフィールドを指定できます。

  • 属性
  • 前回の場所

他のフィールドは設定しないでください。設定すると、フィールドは読み取り専用であるか、UpdateDeliveryVehicle 呼び出しを介してのみ更新できるため、Fleet Engine はエラーを返します。

オプション フィールドを設定せずに車両を作成するには、CreateDeliveryVehicleRequestDeliveryVehicle フィールドを未設定のままにします。

次の例は、Java gRPC ライブラリを使用して車両を作成する方法を示しています。

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

サーバー環境から車両を作成するには、CreateDeliveryVehicle に対して HTTP REST 呼び出しを行います。

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

<id> は、フリート内の配送車両の一意の識別子です。

リクエスト ヘッダーには、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 では、ユーザー指定 ID の API ガイダンスに従って DeliveryVehicle エンティティの name フィールドは無視されます。他のフィールドは設定しないでください。設定すると、フィールドは読み取り専用であるか、UpdateDeliveryVehicle 呼び出しを介してのみ更新できるため、Fleet Engine はエラーを返します。

フィールドを設定せずに車両を作成するには、POST リクエストの本文を空のままにします。新しく作成した車両には、POST URL の deliveryVehicleId パラメータから抽出された車両 ID が含まれます。

curl コマンドの例:

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

集荷タスクを作成する

配送の受け取りタスクは、Driver SDK またはサーバー環境から作成できます。

gRPC

次の例は、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))
  .build();

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

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

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

REST

サーバー環境から配送の受け取りタスクを作成するには、CreateTask に対して HTTP REST 呼び出しを行います。

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

<id> はタスクの一意の識別子です。荷物追跡番号は使用しないでください。システムにタスク ID がない場合は、UUID(Universally Unique Identifier)を生成することができます。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には Task エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    type Type.PICKUP
    state 状態。OPEN
    trackingId 配送状況を追跡するために使用している番号または識別子。
    PlannerLocation タスクが完了する場所。この場合は、集荷場所です。
    taskDuration 受け取り場所での集荷にかかる時間(秒)。

  • 省略可能フィールド:

    • なし

エンティティの他のフィールドはすべて、作成のために無視されます。割り当てられた deliveryVehicleId がリクエストに含まれている場合、Fleet Engine は例外をスローします。タスクの割り当てUpdateVehicleRequests を通じて行われます。

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

配送タスクの作成

配送タスクは、Driver SDK またはサーバー環境から作成できます。

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))
  .build();

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

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

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

REST

サーバー環境から配送タスクを作成するには、CreateTask に対して HTTP REST 呼び出しを行います。

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

<id> はタスクの一意の識別子です。荷物追跡番号は使用しないでください。システムにタスク ID がない場合は、UUID(Universally Unique Identifier)を生成することができます。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には Task エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    type Type.DELIVERY
    state 状態。OPEN
    trackingId 配送状況を追跡するために使用している番号または識別子。
    PlannerLocation タスクが完了する場所。この場合は、この配送の配達場所です。
    taskDuration 配送先に荷物が発送されるまでの時間(秒)。

  • 省略可能フィールド:

    • なし

エンティティの他のフィールドはすべて、作成のために無視されます。割り当てられた deliveryVehicleId がリクエストに含まれている場合、Fleet Engine は例外をスローします。タスクの割り当てUpdateVehicleRequests を通じて行われます。

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

タスクの一括作成

サーバー環境からタスクのバッチを作成できます。

gRPC

次の例は、Java gRPC ライブラリを使用して、2 つのタスク(配達用と同一場所の集荷用)を作成する方法を示しています。

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

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

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

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

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

REST

サーバー環境から配送タスクと集荷タスクを作成するには、BatchCreateTasks に対して HTTP REST 呼び出しを行います。

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

リクエスト ヘッダーには、Bearer <token> の値を持つ Authorization フィールドを含める必要があります。<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には BatchCreateTasksRequest エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    リクエスト 配列 <CreateTasksRequest>

  • 省略可能フィールド:

    Field
    header DeliveryRequestHeader

requests 内の各 CreateTasksRequest 要素は、parent フィールドと header フィールドは省略可能ですが、CreateTask リクエストと同じ検証ルールを渡す必要があります。設定する場合、それらはトップレベル BatchCreateTasksRequest の対応するフィールドと同じにする必要があります。それぞれに固有の検証ルールについては、配送の受け取りタスクの作成と、配送タスクの作成をご覧ください。

詳細については、BatchCreateTasksgRPCREST)の API リファレンス ドキュメントをご覧ください。

curl コマンドの例:

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

予約不可

Driver SDK またはサーバー環境から、利用できない状況(ドライバーの休憩や車両の燃料補充など)を示すタスクを作成できます。スケジュール不可のタスクにトラッキング ID を含めることはできません。必要に応じて、場所を指定することもできます。

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

REST

サーバー環境から使用不可のタスクを作成するには、CreateTask に対して HTTP REST 呼び出しを行います。

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

<id> はタスクの一意の識別子です。システムにタスク ID がない場合は、UUID(Universally Unique Identifier)を生成することができます。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には Task エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    type タイプ: 対応不可
    state 状態。OPEN
    taskDuration ブレークの長さ(秒)。

  • オプション フィールド:

    Field
    PlannerLocation 休憩の場所(特定の場所で休憩を取る必要がある場合)。

エンティティの他のフィールドはすべて、作成のために無視されます。割り当てられた deliveryVehicleId がリクエストに含まれている場合、Fleet Engine は例外をスローします。タスクの割り当てUpdateVehicleRequests を通じて行われます。

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 またはサーバー環境から作成できます。スケジュール設定された停止タスクに、トラッキング ID を含めることはできません。

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

REST

サーバー環境からスケジュールされた停止タスクを作成するには、CreateTask に対して HTTP REST 呼び出しを行います。

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

<id> はタスクの一意の識別子です。システムにタスク ID がない場合は、UUID(Universally Unique Identifier)を生成することができます。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には Task エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    type タイプ: SCHEDULED_STOP
    state 状態。OPEN
    PlannerLocation 停車地の場所。
    taskDuration 停車地の予想所要時間(秒単位)。

  • 省略可能フィールド:

    • なし

エンティティの他のフィールドはすべて、作成のために無視されます。割り当てられた deliveryVehicleId がリクエストに含まれている場合、Fleet Engine は例外をスローします。タスクの割り当てUpdateVehicleRequests を通じて行われます。

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

車両にタスクを割り当てる

タスクは、車両のタスク順序を更新して配送車両に割り当てられます。車両のタスク順序は、デリバリー車両の車両リストのリストによって決まります。各車両停車地には 1 つ以上のタスクを割り当てることができます。

以前に別の車両に割り当てられていたタスクのタスクの順序を更新すると、エラーが発生します。

ある車両から別の車両に配送を変更するには、元のタスクを終了してから、新しい車両を割り当てる前に再作成します。

タスクの順序の更新

車両に割り当てられたタスクの実行順序は、Driver SDK またはサーバー環境から更新できます。競合状態を避けるため、2 つのメソッドを混在させないでください。

タスクの順序を更新すると、車両に割り当てられていなかった場合に車両にタスクが割り当てられ、以前に車両に割り当てられ、更新された注文から除外されたタスクが終了します。以前に別の車両に割り当てられていたタスクを別の車両に割り当てると、エラーが発生します。既存のタスクを閉じてから、新しい車両に割り当てる前に新しいタスクを作成します。

タスクの順序は随時更新できます。

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();

// 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 {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

サーバー環境から車両のタスクの順序を更新するには、UpdateDeliveryVehicle に HTTP REST 呼び出しを行います。

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

<id>: フリート内の配送車両の一意の識別子。タスクの順序を更新します。これは、車両の作成時に指定した識別子です。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には DeliveryVehicle エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    leftVehicleJourneySegments タスクの順番に沿って実行されるタスクのリスト。リストの最初のタスクが最初に実行されます。
    leftVehicleJourneySegments[i].stop リスト内のタスク i の停止。
    leftVehicleJourneySegments[i].stop.plannedLocation 停車地の計画場所。
    leftVehicleJourneySegments[i].stop.tasks この車両の停留所で実施するタスクのリスト。
    leftVehicleJourneySegments[i].stop.state 都道府県(NEW)

  • 省略可能フィールド:

    • なし

エンティティの他のフィールドはすべて更新で無視されます。

curl コマンドの例:

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

次の目的地まで車が案内中

車両が駅 / 停留所を出発したときや、ナビゲーションを開始したときに、Fleet Engine に通知する必要があります。Fleet Engine には、ドライバ SDK またはサーバー環境から通知できます。競合状態を回避し、信頼できる唯一の情報源を維持するために、この 2 つのメソッドを混在させないでください。

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();

// 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 {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

サーバー環境から次の停車地まで車両が走行することを Fleet Engine に通知するには、UpdateDeliveryVehicle に HTTP REST 呼び出しを行います。

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

<id>: フリート内の配送車両の一意の識別子。タスクの順序を変更します。これは、車両の作成時に指定した識別子です。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には DeliveryVehicle エンティティを含める必要があります。

  • 必須フィールド:

    Field
    leftVehicleJourneySegments State が State.NEW とマークされている残りの車両停止のリスト。リスト内の最初の停車地には、State.ENROUTE のマークが必要です。

  • 省略可能フィールド:

    • なし

エンティティの他のフィールドはすべて、通知で無視されます。

curl コマンドの例:

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

車両が停留所に到着

車両が停車地に到着したら、Fleet Engine に通知する必要があります。Fleet Engine には、ドライバ SDK またはサーバー環境から通知できます。競合状態を回避し、信頼できる唯一の情報源を維持するために、2 つのメソッドを混在させないでください。

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();

// 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 {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

サーバー環境から離れた停車地に車両が到着することを Fleet Engine に通知するには、UpdateDeliveryVehicle に HTTP REST 呼び出しを行います。

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

<id>: フリート内の配送車両の一意の識別子。タスクの順序を変更します。これは、車両の作成時に指定した識別子です。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には DeliveryVehicle エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    leftVehicleJourneySegments 到着した停車地は State が State.ARRIVED で、車両の停車地のリストが State.NEW とマークされています。

  • 省略可能フィールド:

    • なし

エンティティの他のフィールドはすべて更新で無視されます。

curl コマンドの例:

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

車両の停止

車両の停止が完了したときに、Fleet Engine に通知する必要があります。これにより、その停車地に関連するすべてのタスクが CLOSED 状態に設定されます。Fleet Engine に通知するには、ドライバ SDK またはサーバー環境を使用します。 競合状態を回避し、信頼できる唯一の情報源を維持するために、2 つのメソッドを混在させないでください。

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();

// 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 {
  DeliveryVehicle updatedDeliveryVehicle =
      deliveryService.updateDeliveryVehicle(updateDeliveryVehicleRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

サーバー環境からの停止が完了したことを Fleet Engine に通知するには、UpdateDeliveryVehicle に HTTP REST 呼び出しを行います。

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

<id>: フリート内の配送車両の一意の識別子。タスクの順序を変更します。これは、車両の作成時に指定した識別子です。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には DeliveryVehicle エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    残りのセグメント 完了した停留所は、残りの車両停止リストに表示されなくなります。

  • 省略可能フィールド:

    • なし

エンティティの他のフィールドはすべて更新で無視されます。

curl コマンドの例:

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

タスクを更新する

ほとんどのタスク フィールドは不変です。ただし、タスク エンティティを直接更新することで、状態、タスクの結果、タスクの結果の時間、タスク結果の場所を変更できます。たとえば、タスクが車両に割り当てられていない場合は、状態を直接更新してタスクを閉じることができます。

gRPC

これは、gRPC でタスクを更新する例です。

REST

これは、REST を使用してタスクを更新する例です。

タスクを閉じる

車両に割り当てられているタスクを閉じるには、タスクが行われる停車地を車両が完了したことをフリート エンジンに通知するか、車両停止のリストから削除します。これを行うには、車両のタスクの順序を更新するときと同様に、残りの車両のリストを設定します。

タスクにまだ車両が割り当てられておらず、クローズする必要がある場合は、タスクを CLOSED の状態に更新します。ただし、CLOSED タスクを再開することはできません。

タスクを閉じても、成功または失敗を示すわけではありません。これは、タスクが進行中とみなされなくなったことを示します。配送の追跡では、配送の結果を表示できるように、タスクの実際の結果を示すことが重要です。

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) // It's only possible to directly CLOSE a
  .build();                    // task which 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();

// 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 updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

サーバー環境からタスクに完了マークを付けるには、UpdateTask に対して HTTP REST 呼び出しを行います。

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

<id> はタスクの一意の識別子です。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には Task エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    state 状態。CLOSED

  • オプション フィールド:

    Field
    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

タスクの結果と結果のロケーションを設定する

タスクの終了は、成功または失敗を示すのではなく、タスクが進行中とみなされなくなったことを示します。配送の追跡では、タスクの実際の結果を示し、配送結果を表示して適切な課金が行われるようにすることが重要です。一度設定すると、タスクの結果を変更できません。タスクの結果時間とタスク結果のロケーションは、設定後に変更できます。

CLOSED 状態のタスクでは、結果に SUCCEEDED または FAILED を設定できます。ステータスが SUCCEEDED の集荷タスクと配送タスクのみが請求されます。

タスクの結果にマークを付けると、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();

// 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 updatedTask = deliveryService.updateTask(updateTaskRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;
     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

サーバー環境からタスクを完了としてマークするには、UpdateTask に対して HTTP REST 呼び出しを行います。

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

<id> はタスクの一意の識別子です。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

リクエストの本文には Task エンティティを含める必要があります。

  • 必須項目は次のとおりです。

    Field
    taskOutcome(タスクの結果) Outcome.SUCCEEDED または Outcome.FAILED
    taskOutcomeTime プロバイダからタスクの結果が設定されたときのタイムスタンプ。 これは、タスクが完了した時刻です。

  • オプション フィールド:

    Field
    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=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

配送のルートを変更する

配送タスクの作成後に、配送予定日を変更することはできません。 配送を再ルーティングするには、結果を設定せずに配送タスクを終了してから、計画した場所を更新して新しいタスクを作成します。新しいタスクを作成したら、同じ車両にタスクを割り当てます

フィーダーと配送車を利用する

フィーダー車両を使用して 1 日を通して配送車両を配送する場合、配送車両の計画停車タスクとして配送のモデル化を行います。正確な位置情報の追跡を可能にするには、配送された荷物を配送車両に積み込んだ後に、その配送タスクを割り当てる必要があります。

店舗の配送ステータスとその他のメタ情報

配送タスクが完了すると、タスクの状態と結果がタスクに記録されます。ただし、配送に固有の他のメタ情報を更新することもできます。Fleet Engine サービスの外部で参照できる他のメタ情報を保存するには、タスクに関連付けられている Tracking_id を外部テーブルのキーとして使用します。

詳細については、タスクのライフサイクルをご覧ください。

車両を検索

車両は、Driver SDK またはサーバー環境から検索できます。

gRPC

次の例は、Java gRPC ライブラリを使用して車両を検索する方法を示しています。

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

REST

サーバー環境から車両を検索するには、「GetVehicle」に対して HTTP REST 呼び出しを行います。

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

<id> はタスクの一意の識別子です。

<vehicleId> は検索する車両の ID です。

リクエスト ヘッダーには、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}"

タスクを検索

サーバー環境からタスクを検索できます。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;
}

REST

サーバー環境からタスクを検索するには、「GetTask」に対して HTTP REST 呼び出しを行います。

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

<id> はタスクの一意の識別子です。

<taskId> は、検索するタスクの ID です。

リクエスト ヘッダーには、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}"

配送タスクを追跡 ID で検索

サーバーまたはブラウザ環境のトラッキング ID によって配送タスクを検索できます。Driver SDK では荷物追跡 ID による配送タスクの検索はサポートされていません。

配送タスクをブラウザ環境から検索する場合は、セキュリティ リスクを抑えるために、可能な限り小さいトークンを使用してください。たとえば、デリバリー コンシューマ トークンを使用する場合、Fleet Engine Deliveries API の呼び出しは、配送業者や配送受領者など、そのエンドユーザーに関連する情報のみを返します。レスポンスの他のすべての情報が削除されます。トークンの詳細については、認可用の JSON ウェブトークン(JWT)の作成をご覧ください。

配送タスクでは、特定のフィールドが編集されます。次の特長があります。

  • 車両が配送不可タスクの間、配送追跡情報はすべて編集されます。唯一の例外は、車両が最後の停留所にいて、その停止地点には利用不可タスクと別のタスクタイプがある場合だけです。
  • 車両がタスクの場所から 5 か所以上離れると、配送追跡情報は削除されます。

gRPC

次の例は、Java gRPC ライブラリを使用して、配送 ID を追跡 ID で検索する方法を示しています。トラッキング ID の正常なレスポンスは空のままです。空のレスポンスは、指定されたトラッキング ID にタスクが関連付けられていないことを示します。

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

try {
  SearchTasksResponse searchTasksResponse = deliveryService.searchTasks(searchTasksRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

ブラウザから配送タスクを検索するには、「SearchTasks」に HTTP REST 呼び出しを行います。

GET https://fleetengine.googleapis.com/v1/providers/<project_id>/tasks:search?trackingId=<tracking_id>

<id> はタスクの一意の識別子です。

リクエスト ヘッダーには、Authorization の値として Bearer <token> を指定する必要があります。ここで、<token>Fleet Engine トークン ファクトリによって発行されたトークンです。

検索が成功すると、レスポンスの本文に次の構造のデータが含まれます。

// JSON representation
{
  "tasks": [
    {
      object (Task)
    }
  ]
}

トラッキング ID の正常なレスポンスは、空の場合もあります。空のレスポンスは、指定されたトラッキング ID にタスクが関連付けられていないことを示します。

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}/tasks:search?trackingId=${TRACKING_ID}"

タスクの一覧表示

サーバーまたはブラウザ環境からタスクを一覧表示できます。Driver SDK はタスクの一覧表示をサポートしていません。

タスクの一覧表示では、タスクに対する広範なアクセス権がリクエストされます。タスクの一覧表示は、信頼できるユーザーのみを対象としています。リストのタスクをリクエストする場合は、配信フリート リーダーまたは配信スーパー ユーザー認証トークンを使用します。

リストされたタスクでは、次のフィールドが秘匿化されています。

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

リストされたタスクは、ほとんどのタスク プロパティによりフィルタできます。フィルタクエリの構文については、AIP-160 をご覧ください。次のリストは、フィルタリングに使用できる有効なプロパティを示しています。

  • delivery_vehicle_id [配送車両 ID]
  • state
  • 計画済みロケーション
  • task_duration
  • task_outcome
  • task_outcome_location
  • task_outcome_location_source
  • task_outcome_time
  • トラッキング ID
  • type

Google API の改善案に基づく次のフィールド形式を使用します。

フィールド タイプ 形式
タイムスタンプ RFC-3339 task_outcome_time = 2022-03-01T11:30:00-08:00
所要時間 秒数に続けて「s」を入力する task_duration = 120s
列挙型 String state = CLOSED AND type = PICKUP
場所 point.latitudepoint.longitude planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0

フィルタクエリ オペレーターの一覧については、AIP-160 をご覧ください。

フィルタクエリが指定されていない場合、すべてのタスクが一覧表示されます。

タスクリストはページ分けされます。ページサイズは、リストタスクのリクエストで指定できます。ページサイズが指定されている場合、返されるタスクの数は、指定されたページサイズを超えません。ページサイズが存在しない場合は、適切なデフォルトが使用されます。リクエストされたページサイズが内部最大値を超える場合は、内部最大値が使用されます。

タスクリストには、結果の次のページを読み取るためのトークンを含めることができます。タスクの次のページを取得するには、前のリクエストと同じリクエストでページトークンを使用します。返されたページトークンが空の場合、取得できるタスクはもうありません。

gRPC

次の例は、Java gRPC ライブラリを使用して deliveryVehicleId のタスクを一覧表示する方法を示しています。成功した場合のレスポンスは空のままです。空のレスポンスは、指定された deliveryVehicleId にタスクが関連付けられていないことを示します。

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

ブラウザからタスクを一覧表示するには、ListTasks に対して HTTP REST 呼び出しを行います。

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

リストされたタスクにフィルタを適用するには、URL でエスケープされたフィルタクエリをフィルタとして使用する 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 は配達車両のリスティングをサポートしていません。

配送車両のリスティングは、配送車両への広範なアクセス権をリクエストし、信頼できるユーザーのみを対象としています。配送車両をリクエストする場合は、デリバリー フリート リーダーまたはデリバリー スーパー ユーザー認証トークンを使用します。

リストに記載されているデリバリー車両では、レスポンス サイズに影響するため、次のフィールドが削除されています。

  • 現在のルート セグメント
  • 残りの車両の移動経路

リスト配信車両は、attributes プロパティでフィルタできます。たとえば、キー my_key と値 my_value を持つ属性をクエリするには、attributes.my_key = my_value を使用します。複数の属性に対してクエリを実行するには、attributes.key1 = value1 AND attributes.key2 = value2 のように、論理 AND 演算子と OR 演算子を使用してクエリを結合します。フィルタクエリ構文の詳細については、AIP-160 をご覧ください。

viewport リクエスト パラメータを使用すると、リストされた配送車両をロケーションでフィルタできます。viewport リクエスト パラメータは、2 つの境界座標(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;
}

REST

ブラウザからタスクを一覧表示するには、ListDeliveryVehicles に対して HTTP REST 呼び出しを行います。

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"

荷物の追跡

Fleet Engine Deliveries API を使用して配送のトラッキングを有効にするには、次の 2 つの方法があります。

  • JavaScript Shipment Tracking ライブラリを使用します。このライブラリでは、車両の位置情報と、Fleet Engine で追跡されている関心領域を可視化できます。標準の google.maps.Map オブジェクトの代替となる JavaScript マップ コンポーネントと、Fleet Engine に接続するデータ コンポーネントが含まれています。これにより、ウェブまたはモバイルアプリで、カスタマイズ可能な配送追跡機能を提供できます。

  • Fleet Engine Deliveries API の上に独自の配送追跡を実装します。重要なのは、トラッキング ID で配送タスクを探すことです。 この検索では、トラッキング ID に関連する複数のタスクが返されることがあります。CLOSED SUCCESSFUL 配信タスクは、荷物の配達が完了したことを配送トラッキング ページのユーザーに知らせます。未完了のタスクが複数ある場合は、ファースト ワンマイル配送の追跡に使用する集荷タスクを選択します。それ以外の場合、ラスト ワンマイルの配送追跡で配送タスクは 1 つだけにする必要があります。

宅配ユーザーロールを使用する場合、Fleet Engine Deliveries API の呼び出しは配送業者または受信者に関連する情報のみを返します。レスポンスのその他の情報はすべて削除されます。エンドユーザーの認証はお客様の責任となります。さらに、位置情報は、現在実行されているタスクに基づいてフィルタリングされます。利用できないタスクの間、位置情報はエンドユーザーと共有されません。

タスクの車両位置が、タスクの場所から 5 段階以内であれば、配送の追跡が可能になります。車両がタスクから 5 か所以上離れている場合、SearchTasks API から返されるタスクには配送追跡情報は含まれません。これはシステムレベルの事前構成です。

ロギング

有効にすると、Fleet Engine が Cloud Logging に RPC ログを送信できるようになります。詳細については、ロギングをご覧ください。

認可のロールとトークン

Deliveries API の統合と個々のユースケースの承認に関するメモで説明したように、Fleet Engine を呼び出すには、サービス アカウントの認証情報を使用して署名された JSON Web Token で認証を行う必要があります。これらのトークンを作成するために使用されるサービス アカウントには、1 つ以上のロールがあり、各ロールに異なる権限セットが付与されている場合があります。

詳細については、認証と承認をご覧ください。

トラブルシューティング

復元性

Fleet Engine は信頼できる情報源とみなされません。必要に応じて、お客様は Fleet Engine に依存せずにシステムの状態を復元できます。

Fleet Engine で状態が失われる

Fleet Engine を使用する場合は、障害が発生した場合にシステムが自己修復するようにクライアントを実装します。たとえば、Fleet Engine が車両を更新しようとすると、車両が存在しないことを示すエラーが返されることがあります。その後、クライアントは車両を新しい状態で再作成する必要があります。このような状況はめったに発生しませんが、発生した場合でも復元力を備えている必要があります。

Fleet Engine の致命的な障害の非常にまれなシナリオでは、ほとんどまたはすべての車両とタスクの再作成が必要になることがあります。作成率が高くなりすぎると、割り当ての問題により、サービス拒否(DOS)攻撃を回避するために割り当てチェックが行われるため、一部のリクエストが再び失敗することがあります。この場合は、再試行のバックオフ戦略を使用して再作成率を遅くします。

ドライバアプリで状態が失われる

ドライバ アプリがクラッシュした場合、アプリは Driver SDK 内で現在の状態を再作成する必要があります。アプリは、タスクが再作成され、現在の状態が復元されるようにする必要があります。また、Driver SDK の停止リストを再作成して明示的に設定する必要があります。

これらの復元は、エンティティがデータベースにすでに存在するかどうかと、いつ存在するかを示すエラーを除き、Fleet Engine からの情報に依存せずに自律的に行われる必要があります。エンティティがすでに存在する場合は、そのエラーを吸収し、その ID を使用してエンティティを更新できます。

よくある質問

ドライバーがタスクの順不同で停止した場合はどうなりますか。

この場合は、まずタスクの順序を更新してから、通常どおりに処理を開始し、停止の到着やタスクの完了などを記述します。そうしないと、システムの不整合が生じる可能性があります。到着予定時刻が誤っている場合や、予期しないエラーが報告される場合があります。

SearchTasks の呼び出しで、受け取りまたは配送のオープン タスクが 3 つ以上返された。どのような問題がありますか?

タスクに「閉じる」のマークを付けなかったか、車両停止のリストから削除したか、タスクをクローズとしてマークしようとしたときにネットワーク障害が発生しました。どのタスクが CLOSED としてマークされていないかを、独自の信頼できる情報源から確認する必要があります。ネットワーク障害を検出し、更新オペレーションが失敗した場合は再試行します。