基本構造（ShipmentModel、Shipment、Vehicle）

ShipmentModel には、`Shipment` メッセージタイプの `shipments` オブジェクトと、`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` オブジェクト内に含まれます。

図に示すように:

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

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

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

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

シナリオ	説明
`pickups` のみ	配送のみを収集すると想定されます。
`deliveries` のみ	配送を事前にロードしているか、サービスを提供していると想定されます。
`pickups` と `deliveries` の両方	割り当てられた車両は、まず集荷を完了してから配送する必要があります。配送を行えるのは、集荷を行った車両のみです。
複数の `pickups` または `deliveries`	配送で `pickups` または `deliveries` の候補が複数リストされている場合、オプティマイザは、費用を最小限に抑え、制約を満たすように、1 つの集荷オプションと 1 つの配送オプションを選択します。

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

`Shipment` の例

この例では、犬の保育サービスを利用しており、犬を自宅に迎車し、保育園に送ります。2 匹の犬の集荷場所を設定し、配送先をビジネスに設定します。

1 匹目の犬の家 は、サンフランシスコのコイトタワーにあります。この場所の座標は、緯度 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` オブジェクト内に含まれます。

図に示すように:

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

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

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

`Vehicle` の例

この例では、犬の保育サービスを利用しており、1 日の開始時と終了時の車両の位置と、ガソリンの使用量を定義します。車両の業務時間を指定する必要はありません。これは、 globalStartTime および globalEndTime プロパティ内の ShipmentModel オブジェクトで定義した時間と一致するためです。

この例では、リクエストの 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"
  }
}

基本構造（ShipmentModel、Shipment、Vehicle） コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

ShipmentModel

ShipmentModel の例

Shipment

Shipment の例

Vehicle

Vehicle の例