このページは Cloud Translation API によって翻訳されました。

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 日を通じて正確な到着予定時刻が表示されます。

利用できないタスクの間、位置情報はエンドユーザーと共有されません。たとえば、Fleet Tracking Library を使用しているフリート管理者は、配達車両の位置情報を非表示にできます。

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

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

各データ構造に含まれる具体的なフィールドは、DeliveryVehicle（gRPC、REST）と Task（gRPC、REST）の 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 フリートトラッキングライブラリはタスクの結果を示します。タスクのステータスは自動的に CLOSED に設定されます。詳細については、JavaScript フリートトラッキングライブラリを使用してフリートを追跡するをご覧ください。

車両の場合と同様に、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 はエラーを返します。

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

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

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

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

REST

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

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

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

リクエストヘッダーには、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）を生成することができます。

リクエストの本文には 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>

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

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

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

省略可能フィールド:
- なし

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

Field	価値
リクエスト	配列<`CreateTasksRequest`>

Field	価値
header	DeliveryRequestHeader

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

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

curl コマンドの例:

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

予約不可

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）を生成することができます。

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

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

Field 価値

type タイプ: 対応不可

state 状態。OPEN

taskDuration ブレークの長さ（秒）。
オプションフィールド:

Field 価値

PlannerLocation 休憩の場所（特定の場所で休憩を取る必要がある場合）。

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

Field	価値
PlannerLocation	休憩の場所（特定の場所で休憩を取る必要がある場合）。

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）を生成することができます。

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

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

Field 価値

type タイプ: SCHEDULED_STOP

state 状態。OPEN

PlannerLocation 停車地の場所。

taskDuration 停車地の予想所要時間（秒単位）。
省略可能フィールド:
- なし

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

curl コマンドの例:

# Set $JWT, $PROJECT_ID, and $TASK_ID in the local environment
curl -X POST "https://fleetengine.googleapis.com/v1/providers/${PROJECT_ID}/tasks?taskId=${TASK_ID}" \
  -H "Content-type: application/json" \
  -H "Authorization: Bearer ${JWT}" \
  --data-binary @- << EOM
{
  "type": "SCHEDULED_STOP",
  "state": "OPEN",
  "plannedLocation": {
     "point": {
        "latitude": -6.195139,
        "longitude": 106.820826
     }
  },
  "taskDuration": "600s"
}
EOM

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

タスクは、車両のタスクの順序を更新して配送車両に割り当てられます。車両のタスク順序は、デリバリー車両の車両リストのリストによって決まります。各車両停車地には 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>: フリート内の配送車両の一意の識別子。タスクの順序を更新します。これは、車両の作成時に指定した識別子です。

リクエストの本文には 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}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

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

車両が停車地から出発したり、ナビを開始したりした場合は、Fleet Engine に通知する必要があります。Fleet Engine への通知は、 Driver 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>: フリート内の配送車両の一意の識別子。タスクの順序を変更します。これは、車両の作成時に指定した識別子です。

リクエストの本文には 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}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

車両が停留所に到着

車両が停車地に到着したときに、Fleet Engine に通知する必要があります。 Driver 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>: フリート内の配送車両の一意の識別子。タスクの順序を変更します。これは、車両の作成時に指定した識別子です。

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

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

Field 価値

leftVehicleJourneySegments 到着した停車地は State が State.ARRIVED で、車両の停車地のリストが State.NEW とマークされています。
省略可能フィールド:
- なし

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}"
          }
        ]
      }
    },
    {
      "stop": {
        "state": "NEW",
        "plannedLocation": {
          "point": {
            "latitude": 37.3382,
            "longitude": 121.8863
          }
        },
        "tasks": [
          {
            "taskId": "${TASK2_ID}"
          }
        ]
      }
    }
  ]
}
EOM

車両の停止

車両の停止時には、Fleet Engine に通知する必要があります。これにより、その停車地に関連するすべてのタスクが CLOSED 状態に設定されます。Fleet Engine への通知は、 Driver 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>: フリート内の配送車両の一意の識別子。タスクの順序を変更します。これは、車両の作成時に指定した識別子です。

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

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

Field 価値

残りのセグメント完了した停留所は、残りの車両停止リストに表示されなくなります。
省略可能フィールド:
- なし

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

タスクを更新する

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

タスクにまだ車両が割り当てられておらず、クローズする必要がある場合は、タスクを 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> は、タスクの一意の識別子です。

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

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

Field 価値

state 状態。CLOSED

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> は、タスクの一意の識別子です。

リクエストの本文には 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 です。

リクエストの本文は空にする必要があります。

検索が成功した場合、レスポンスの本文には車両エンティティが含まれます。

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 です。

リクエストの本文は空にする必要があります。

検索が成功した場合、レスポンスの本文にはタスクエンティティが含まれます。

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。タスクデータの完全なビューにアクセスできるフリートオペレーターなどのユーザーが使用します。
トラッキング ID: クライアントソフトウェアがエンドユーザーに限られた情報（荷物が家に到着したときなど）を提供するために使用します。

このセクションでは、トラッキング ID を使用してタスク情報を検索する方法について説明します。タスク ID でタスクを検索する場合は、タスクの検索をご覧ください。

トラッキング ID で情報を検索するには、次のいずれかを使用します。

gRPC を使用した Java 検索
HTTP を使用した検索

ルックアップの要件

トラッキング ID で提供される配送情報は、トラッキングする場所の公開設定の管理に記載されている公開設定ルールに準拠しています。
Fleet Engine を使用して、配送 ID を追跡して配送情報を検索する。Driver SDK ではトラッキング ID による情報検索はサポートされていません。Fleet Engine でこれを行うには、サーバー環境またはブラウザ環境を使用します。
セキュリティリスクを制限するには、可能な限り狭いトークンを使用します。たとえば、デリバリーコンシューマトークンを使用する場合、Fleet Engine Deliveries API の呼び出しは、配送業者や配送受領者など、そのエンドユーザーに関連する情報のみを返します。レスポンスの他のすべての情報が削除されます。トークンの詳細については、認可用の JSON ウェブトークン（JWT）の作成をご覧ください。

gRPC を使用した Java 検索

次の例は、Java gRPC ライブラリを使用して、配送タスクに関する情報をそのトラッキング ID で検索できます。

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

try {
  TaskTrackingInfo taskTrackingInfo = deliveryService.getTaskTrackingInfo(getTaskTrackingInfoRequest);
} catch (StatusRuntimeException e) {
  Status s = e.getStatus();
  switch (s.getCode()) {
     case NOT_FOUND:
       break;

     case PERMISSION_DENIED:
       break;
  }
  return;
}

HTTP を使用した検索

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

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

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

リクエストヘッダーには、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 はタスクの一覧表示をサポートしていません。

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

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

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.latitude`、`point.longitude`	`planned_location.point.latitude > 36.1 AND planned_location.point.longitude < -122.0`

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

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

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

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

gRPC

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

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

DeliveryServiceBlockingStub deliveryService =
  DeliveryServiceGrpc.newBlockingStub(channel);

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

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

     case PERMISSION_DENIED:
       break;
  }
  return;
}

REST

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

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

リストされたタスクにフィルタを適用するには、URL でエスケープされたフィルタクエリをフィルタとして使用する URL パラメータを指定します。

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

// 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 パラメータを含めます。

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

// 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 フリートトラッキングライブラリを使用します。このライブラリでは、車両の位置情報と、Fleet Engine で追跡されている関心領域を可視化できます。標準の google.maps.Map オブジェクトの代替となる JavaScript マップコンポーネントと、Fleet Engine に接続するデータコンポーネントが含まれています。これにより、ウェブまたはモバイルアプリから、カスタマイズ可能なアニメーションフリートを追跡できるようになります。
Fleet Engine Deliveries 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 を使用してエンティティを更新できます。

よくある質問

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

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

Fleet Engine のスタートガイド

初期設定

設定を確認する

クライアント ライブラリ

データ構造

配達手段

タスク

配送タスク

利用できないタスク

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

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

自動車のライフサイクル

車両の属性

タスクのライフサイクル

Deliveries API の統合

信頼できないモデル

信頼できるモデル

勤務日のモデリング

位置情報の更新について

車両の停留所と配達場所

モバイル SDK を使用する

Delivery Driver API を初期化する

ユースケース

車両の作成

gRPC

REST

集荷タスクを作成する

gRPC

REST

配送タスクの作成

gRPC

REST

タスクの一括作成

gRPC

REST

予約不可

gRPC

REST

予定がある停留所

gRPC

REST

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

タスクの順序の更新

gRPC

REST

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

gRPC

REST

車両が停留所に到着

gRPC

REST

車両の停止

gRPC

REST

タスクを更新する

gRPC

REST

タスクを閉じる

gRPC

REST

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

gRPC

REST

配送のルートを変更する

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

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

車両を検索

gRPC

REST

タスクを検索

gRPC

REST

配送タスク情報をトラッキング ID で検索

ルックアップの要件

gRPC を使用した Java 検索

HTTP を使用した検索

タスクの一覧表示

gRPC

REST

配達手段のリストを表示する

クライアントライブラリ

フリートトラッキング