Temel yapı (ShipmentModel, Shipment ve Vehicle)

Route Optimization API'nin amacı, bir araç filosunun belirli konumları ziyaret etmesi için rotalar planlamaktır. OptimizeToursRequest nesnesi, bu araçların ve konumların özelliklerini açıklar ve her uç noktanın istek gövdesinin birincil yapısıdır.

OptimizeToursRequest nesnesinin temel yapısı aşağıdaki gibidir:

• model alanı, iki anahtar alan içeren bir ShipmentModel mesajı barındırır:
  • Bir veya daha fazla Shipment mesajı içeren bir shipments alanı.
  • Bir veya daha fazla Vehicle mesajı içeren bir vehicles alanı.

Bu belgede aşağıdaki mesaj türleri açıklanmaktadır:

• ShipmentModel: Gönderilerin, kullanılabilir araçların ve aralarındaki ilişkiyi açıklayan diğer nesnelerin listesini içerir.
• Shipment: Bir aracın ziyaret edeceği konumları açıklar. Bunlar, alınacak ve teslim edilecek gerçek paketleri veya araç sürücüsünün hizmet verdiği yerleri temsil edebilir.
• Vehicle: Gönderim konumları arasındaki ulaşım aracını açıklar. Her araç, gerçek bir araca veya yaya olarak hareket eden bir kişiye karşılık gelir.

ShipmentModel

ShipmentModel, rota optimizasyonu sorununun öğelerini içerir. Kısıtlamaları dikkate alıp toplam maliyeti en aza indirirken bir grup araç tarafından gerçekleştirilebilecek bir grup sevkiyat içerir.

Aşağıdaki tabloda ShipmentModel ile ilgili bazı özellikler açıklanmaktadır:

Özellikler	Açıklama
shipments ve vehicles	Bir veya daha fazla gönderi ve aracın ayrıntılarını içeren zorunlu nesneler.
globalStartTime ve globalEndTime	Tüm araçların tüm sevkiyatları tamamlaması gereken zaman aralığının başlangıcını ve bitişini belirtir. Bu özellikler zorunlu olmasa da optimizasyon aracı zaman kısıtlamalarına uyduğunda en iyi şekilde çalıştığından bunları eklemeniz önerilir.

ShipmentModel içindeki özelliklerin tam listesi için referans belgelerine bakın.

ShipmentModel Örneği

Bu örnekte, köpekler için kreş hizmeti sunuyorsunuz ve isteğinizi oluşturmaya başlıyorsunuz. Sevkiyatları ve araçları daha sonra tanımlayacaksınız ancak çalışma saatlerinizi ve saatlik işletme maliyetinizi ayarlayarak başlamak istiyorsunuz.

Bu örnekte, isteğinizdeki ShipmentModel özellik değerleri aşağıdaki gibidir:

Mülk	Değer	Açıklama
globalStartTime	2024-02-13T00:00:00.000Z	Çalışma saatlerinin başlangıç tarihi ve saati.
globalEndTime	2024-02-14T06:00:00.000Z	Çalışma saatlerinin bitiş tarihi ve saati.

Aşağıda, örnek senaryo değerlerini içeren bir ShipmentModel mesajının kod örneği verilmiştir.

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

Shipment

Shipment mesaj türü, teslim edilebilecek bir gönderinin veya bir rotada gerçekleştirilebilecek hizmetin özellik yapısını tanımlar.

Diyagramda gösterildiği gibi:

• Shipment mesajı, gerçek hayattaki bir gönderi veya hizmetle ilgili tüm bilgileri içerir.
• Tüm Shipment mesajları shipments alanında belirtilir.
• shipments alanı bir veya daha fazla Shipment mesajı içerir.

Shipment mesajı için en az bir pickups veya deliveries nesnesi gerekir. Bu nesnelerin tanımı aşağıdaki gibidir:

• pickups, gönderinin teslim alma konumunu tanımlar.
• deliveries, gönderinin teslimat konumunu tanımlar.
• Hem pickups hem de deliveries, konumları ve diğer ayrıntıları tanımlayan bir VisitRequest mesaj türü içerir.

Aşağıdaki tabloda, bir Shipment mesajındaki pickups ve deliveries yapılandırmasına göre farklı senaryolar açıklanmaktadır.

Senaryo	Açıklama
Yalnızca pickups	Yalnızca gönderimi tahsil ettiğiniz varsayılır.
Yalnızca deliveries	Gönderiyi önceden yüklediğiniz veya bir hizmet sunduğunuz varsayılır.
Hem pickups hem de deliveries	Atanan araç önce teslim alma, ardından teslimat işlemini tamamlamalıdır. Teslimatı yalnızca teslim alma işlemini gerçekleştiren araç yapabilir.
Birden fazla pickups veya deliveries	Bir gönderide pickups veya deliveries için birden fazla olasılık listeleniyorsa optimize edici, maliyeti en aza indirmeye ve kısıtlamaları karşılamaya göre bir teslim alma seçeneği ve bir teslimat seçeneği belirler.

Shipment içindeki özelliklerin tam listesi için referans belgelerine bakın.

Shipment Örneği

Bu örnekte, köpekleri evlerinden alıp kreşinize götürdüğünüz bir köpek kreşi hizmetiniz var. İki köpeğin teslim alma konumunu ve teslimat konumunu işletmeniz olarak ayarlamak istiyorsunuz:

• İlk köpeğin evi San Francisco'daki Coit Kulesi'nde. Bu konumun koordinatları 37,8024 enlem ve -122,4058 boylamdır.
• İkinci köpeğin evi, San Francisco'daki South Sunset Playground Park'ta. Bu konumun koordinatları 37,7359 enlem ve -122,5011 boylamdır.
• Köpek bakım merkeziniz Mission Dolores Park, San Francisco'da. Bu konumun koordinatları 37,759773 enlem ve -122,427063 boylamdır.

Aşağıda, shipments nesnesinin örnek koordinatlara sahip iki Shipment mesaj türü içerdiği bir Shipment mesajının kod örneği verilmiştir.

{
  "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 mesaj türü, bir rotada sevkiyat yapabilen bir aracın özellik yapısını tanımlar.

Diyagramda gösterildiği gibi:

• Vehicle mesajı, gerçek bir araçla ilgili tüm bilgileri içerir.
• Tüm Vehicle mesajları vehicles alanında belirtilir.
• vehicles alanı birden fazla Vehicle mesajı içeriyor.

Aşağıdaki tabloda, Vehicle ile ilgili bazı özellikler açıklanmaktadır.

Özellikler	Açıklama
startLocation ve endLocation	Nihai optimize edilmiş rotanın parçası olan araçların başlangıç ve bitiş konumu. Tanımlanmazsa varsayılan olarak ilk gönderi teslim alma ve son gönderi teslimat konumları kullanılır.
costPerHour, costPerKilometer ve costPerTraveledHour	Araca özel maliyet parametreleri. API'nin optimize edilmiş bir rota döndürmesi için isteğinizde en az bir maliyet parametresi bulunması önerilir. Maliyetler hakkında daha fazla bilgi edinmek için Maliyet modeli temel kavramına bakın.
startTimeWindows ve endTimeWindows	Bir aracın rotada çalışabileceği zaman aralıklarını tanımlayın. Bu zaman aralıkları, ShipmentModel içinde ayarlanan globalStartTime ve globalEndTime zaman aralığına denk gelmelidir. Bu özellik zorunlu olmasa da optimizasyon aracı zaman kısıtlamalarına uyduğunda en iyi şekilde çalıştığından bu özelliğin eklenmesi önerilir.

Vehicle Örneği

Bu örnekte, köpek bakım hizmeti sunuyorsunuz ve günün başında ve sonunda aracınızın konumunu ve ne kadar yakıt harcadığını tanımlamak istiyorsunuz. Aracın çalışma saatlerini belirtmeniz gerekmez. Bu saatler, ShipmentModel nesnesindeki globalStartTime ve globalEndTime özelliklerinde tanımladığınız saatlerle eşleşir.

Bu örnekte, isteğinizdeki Vehicle özellik değerleri aşağıdaki gibidir:

Mülk	Değer	Açıklama
startLocation	latitude: 37.759773, longitude: -122.427063	Aracınızın rotasının başlangıç koordinatları. Bu konumlar, San Francisco'daki Mission Dolores Park'ta bulunan köpek bakım merkezinizin konumuyla eşleşir.
endLocation	latitude: 37.759773, longitude: -122.427063	Aracınızın rotasının bitiş koordinatları. Bu konumlar, San Francisco'daki Mission Dolores Park'ta bulunan köpek bakım merkezinizin konumuyla eşleşir.
costPerHour	27	Köpek kreşi aracınızı kullanması için bir sürücüye ödediğiniz tutar. Şoföre saatte 27 ABD doları ödersiniz.

Aşağıda, örnek senaryo değerlerini içeren bir Vehicle mesajının kod örneği verilmiştir.

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

Vehicle içindeki özelliklerin tam listesi için referans belgelerine bakın.

Tam istek örneği

Aşağıdaki kod örneği, bu dokümanda gösterilen ShipmentModel, Shipment ve Vehicle örneklerini birleştiren eksiksiz bir istek örneği sunar.

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