基本構造（ShipmentModel、Shipment、Vehicle）

ShipmentModel には、`Shipment` メッセージ タイプの `shipments` オブジェクトが 1 つと、`Vehicle` メッセージ タイプの `vehicles` オブジェクトが 1 つあります。

Route Optimization API の目的は、フリートの車両が複数の場所に立ち寄るルートを計画することです。OptimizeToursRequest オブジェクトは、これらの車両と位置のプロパティを表し、すべてのエンドポイントのリクエスト本文の主要な構造です。

OptimizeToursRequest オブジェクトの基本構造は次のとおりです。

  • model フィールドには、2 つのキー フィールド （
      ）を含む ShipmentModel メッセージが保持されます。
    • 1 つの shipments フィールド。1 つまたは複数の Shipment メッセージが含まれます。
    • 1 つの vehicles フィールド。1 つまたは複数の Vehicle メッセージが含まれます。

このドキュメントでは、次のメッセージ タイプについて説明します。

  • ShipmentModel: 配送、利用可能な車両、およびそれらの関係を記述するその他のオブジェクトのリストを保持します。
  • Shipment: 車両が訪問する場所を記述します。実際の荷物の集荷と配達、または車両の運転手がサービスを提供する場所を表すことができます。
  • Vehicle: 配送場所間の輸送手段を説明します。各車両は、実際の車両または徒歩で移動する人に相当します。

ShipmentModel

ShipmentModel には、ルート最適化問題の要素が格納されます。これには、一連の車両で実行される一連の配送が含まれます。制約を考慮しながら、全体的な費用を最小限に抑えます。

次の表に、ShipmentModel の関連するプロパティを示します。

プロパティ 説明
shipments、vehicles 1 つまたは複数の配送と車両の詳細を含む必須オブジェクト。
globalStartTime、globalEndTime すべての車両がすべての配送を完了する必要がある時間枠の開始と終了を示します。これらのプロパティは必須ではありませんが、オプティマイザーは時間制約を遵守すると最も効果的に機能するため、含めることをおすすめします。

ShipmentModel のプロパティの完全なリストについては、リファレンス ドキュメントをご覧ください。

ShipmentModel の例

この例では、犬のデイケア サービスを運営しており、リクエストの作成を開始しています。配送と車両は後で定義しますが、まずは営業時間と 1 時間あたりの運用コストを設定します。

この例では、リクエストの ShipmentModel プロパティ値は次のとおりです。

プロパティ 値 説明
globalStartTime 2024-02-13T00:00:00.000Z 営業時間開始の日時。
globalEndTime 2024-02-14T06:00:00.000Z 営業時間終了の日時。

次に、シナリオの例の値を組み込んだ ShipmentModel メッセージのコードサンプルを示します。

{
  "model": {
    "shipments": [
      ...
    ],
    "vehicles": [
      ...
    ],
   "globalStartTime": "2024-02-13T00:00:00.000Z",
   "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}

Shipment

Shipment メッセージ タイプは、ルート上で配送可能な配送または実行可能なサービスのプロパティ構造を定義します。

実際の配送は 1 つの「Shipment」メッセージに相当し、これは「shipments」オブジェクトに含まれます。

図に示すように:

  • Shipment メッセージには、実際の配送またはサービスに関するすべての情報が含まれています。
  • すべての Shipment メッセージは shipments フィールドで指定されます。
  • shipments フィールドには、1 つ以上の Shipment メッセージが含まれます。

Shipment メッセージには、pickups オブジェクトまたは deliveries オブジェクトが少なくとも 1 つ必要です。これらのオブジェクトの定義は次のとおりです。

  • pickups は、配送の集荷場所を定義します。
  • deliveries は、配送の配送先を定義します。
  • pickups と deliveries の両方には、場所やその他の詳細を定義する VisitRequest メッセージ タイプが含まれています。

次の表に、Shipment メッセージ内の pickups と deliveries の構成に基づくさまざまなシナリオを示します。

シナリオ 説明
pickups のみ 配送のみを回収することを前提としています。
deliveries のみ 配送物を事前に読み込んでいるか、サービスを提供していることを前提としています。
pickups と deliveries の両方 割り当てられた車両は、最初に集荷を完了し、次に配達を完了する必要があります。集荷を行った車両のみが配送を行うことができます。
複数の pickups または deliveries 1 つの配送に pickups または deliveries の複数の候補がリストされている場合、オプティマイザーは、コストを最小限に抑え、制約を満たすことに基づいて、使用する集荷オプション 1 つと配送オプション 1 つを選択します。

Shipment のプロパティの完全なリストについては、リファレンス ドキュメントをご覧ください。

Shipment の例

この例では、犬を自宅から引き取ってデイケアに連れて行く、犬のデイケア サービスを提供しています。2 匹の犬の集荷場所を設定し、配送場所をビジネスに設定するとします。

  • 最初の犬の家は、サンフランシスコのコイトタワーにあります。この場所の座標は、緯度 37.8024、経度 -122.4058 です。
  • 2 匹目の犬の家は、サンフランシスコのサウス サンセット プレイグラウンド パークにあります。この場所の座標は、緯度 37.7359、経度 -122.5011 です。
  • 犬の託児所はサンフランシスコのミッション ドロレス パークにあります。この場所の座標は、緯度 37.759773、経度 -122.427063 です。

以下は、Shipment メッセージのコードサンプルです。shipments オブジェクトには、座標の例を含む 2 つの Shipment メッセージ タイプが含まれています。

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
    ...
    ]
  }
}

Vehicle

Vehicle メッセージ タイプは、ルートで配送を実行できる車両のプロパティ構造を定義します。

現実の車両は 1 つの `Vehicle` メッセージに相当し、`vehicles` オブジェクトに含まれます。

図に示すように:

  • Vehicle メッセージには、実際の車両に関するすべての情報が含まれています。
  • すべての Vehicle メッセージは vehicles フィールドで指定されます。
  • vehicles フィールドには複数の Vehicle メッセージが含まれています。

次の表に、Vehicle の関連プロパティを示します。

プロパティ 説明
startLocation、endLocation 最終的な最適化されたルートの一部である車両の出発地と目的地。定義されていない場合、デフォルトは最初の荷物の集荷場所と最後の荷物の配達場所になります。
costPerHour、costPerKilometer、costPerTraveledHour 車両固有の費用パラメータ。API が最適化されたルートを返すようにするには、リクエストに少なくとも 1 つの費用パラメータを含めることをおすすめします。費用の詳細については、費用モデルの主なコンセプトをご覧ください。
startTimeWindows、endTimeWindows 車両がルートを走行できる期間を定義します。これらは、ShipmentModel で設定された globalStartTime と globalEndTime の時間枠内に収まる必要があります。このプロパティは必須ではありませんが、オプティマイザーは時間制約を遵守すると最も効果的に機能するため、含めることをおすすめします。

Vehicle の例

この例では、犬のデイケア サービスを運営しており、1 日の開始時と終了時の車両の位置と、消費するガソリン量を定義します。ShipmentModel オブジェクト内の globalStartTime プロパティと globalEndTime プロパティで定義した時間と一致するため、車両の稼働時間を指定する必要はありません。

この例では、リクエストの Vehicle プロパティの値は次のとおりです。

プロパティ 値 説明
startLocation latitude: 37.759773、longitude: -122.427063 車両のルートの開始座標。これらは、サンフランシスコのミッション ドロレス パークにある犬のデイケアの場所と一致します。
endLocation latitude: 37.759773、longitude: -122.427063 車両のルートの終了座標。これは、サンフランシスコのミッション ドロレス パークにある犬のデイケアの所在地と一致しています。
costPerHour 27 犬のデイケア車両の運転手への支払額。運転手には 1 時間あたり 27 ドルを支払います。

次のコードサンプルは、サンプル シナリオの値を組み込んだ Vehicle メッセージです。

{
  "model": {
    "shipments": [
    ...
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ]
  }
}

Vehicle のプロパティの完全なリストについては、リファレンス ドキュメントをご覧ください。

リクエストの完全な例

次のコードサンプルは、このドキュメントで説明した ShipmentModel、Shipment、Vehicle の例を組み合わせた完全なリクエストの例を示しています。

{
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.8024,
              "longitude": -122.4058
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      },
      {
        "pickups": [
          {
            "arrivalLocation": {
              "latitude": 37.7359,
              "longitude": -122.5011
            }
          }
        ],
        "deliveries": [
          {
            "arrivalLocation": {
              "latitude": 37.759773,
              "longitude": -122.427063
            }
          }
        ]
      }
    ],
    "vehicles": [
      {
        "startLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "endLocation": {
          "latitude": 37.759773,
          "longitude": -122.427063
        },
        "costPerHour": 27
      }
    ],
    "globalStartTime": "2024-02-13T00:00:00.000Z",
    "globalEndTime": "2024-02-14T06:00:00.000Z"
  }
}