Membuat permintaan Route Optimization pertama Anda... dengan

Developer Wilayah Ekonomi Eropa (EEA)

Dokumen ini menunjukkan cara membuat permintaan pertama ke Route Optimization API menggunakan skenario kasus penggunaan di dunia nyata.

Agar lebih mudah, contoh ini menggunakan HTTP dan JSON untuk mendemonstrasikan REST API. Namun, untuk lingkungan produksi, rekomendasi keseluruhannya adalah menggunakan gRPC karena manfaat performanya. Namun, gRPC memerlukan beberapa penginstalan. Untuk informasi selengkapnya, lihat Library klien Route Optimization API.

Skenario

Peta San Francisco dengan pin untuk Coit Tower, Mission Dolores Park, dan South Sunset Playground Park

Anda menjalankan layanan penitipan dari pukul 07.00 hingga 19.00 di San Francisco. Pagi ini, Anda ingin menjemput tiga dari berbagai lokasi di kota dan membawanya ke pusat penitipan hewan peliharaan Anda.

gunung Bernese dan Chihuahua adalah klien reguler yang membuat janji temu minggu lalu. German shepherd adalah permintaan baru yang mendadak. Anda ingin mengakomodasi German shepherd jika memungkinkan, tetapi tidak dengan mengorbankan klien reguler Anda.

Anda memiliki satu mobil van untuk pekerjaan tersebut, dan Anda membayar pengemudi $27 per jam. Pengemudi dan van memulai hari di pusat penitipan anak Anda pada pukul 07.00 dan harus kembali dari penjemputan pagi pada siang hari untuk istirahat makan siang.

Hari ini adalah 13 Februari 2024. Semua waktu dalam skenario ini adalah waktu lokal San Francisco, yaitu Waktu Standar Pasifik (UTC-8) pada bulan Februari. Driver memiliki tugas berikut:

  • Jemput Bernese Mountain di dekat Coit Tower. Pemilik meminta periode penjemputan yang ketat antara pukul 08.00 dan 08.20.
  • Menjemput Chihuahua di South Sunset Playground Park. Pemilik menawarkan periode pengambilan yang lebih fleksibel antara pukul 07.30 dan 09.30.
  • Jemput German shepherd di Land's End. Pemilik juga meminta periode pengambilan yang ketat antara pukul 08.00 dan 08.20.
  • Turunkan di pusat penitipan anak di Mission Dolores Park. Tempat penitipan anak mengharuskan pengantaran antara pukul 09.30 dan 11.30.

Setiap kunjungan penjemputan dan pengantaran memerlukan waktu 5 menit untuk menaikkan atau menurunkan.

Karena Land's End jauh dari Coit Tower dan periode penjemputannya bertentangan, pengemudi tidak dapat melakukan ketiga penjemputan. Pengoptimal harus memilih mana yang akan dilewati untuk meminimalkan total biaya (upah pengemudi dan denda karena melewatkan).

Sebelum memulai

Untuk menjalankan kode dalam contoh skenario ini, Anda harus menyelesaikan petunjuk di bagian Menyiapkan Route Optimization API terlebih dahulu.

1. Memilih pendekatan pengoptimalan rute

Route Optimization API memiliki beberapa metode yang dapat Anda pilih, bergantung pada kompleksitas masalah pengoptimalan Anda.

Karena skenario penitipan ini adalah permintaan yang kecil dan sederhana, gunakan metode pemblokiran, seperti optimizeTours, yang dengan cepat memberikan hasil untuk permintaan kecil. Untuk mengetahui informasi selengkapnya tentang endpoint Route Optimization API, lihat Memilih endpoint.

Gunakan URL berikut untuk membuat permintaan POST HTTP ke metode optimizeTours:

https://routeoptimization.googleapis.com/v1/projects/PROJECT_OR_ID:optimizeTours

Anda juga perlu menetapkan setelan waktu tunggu dan batas waktu yang singkat untuk mengurangi waktu tunggu yang tidak perlu. Untuk skenario penitipan ini, pengoptimal tidak memerlukan banyak waktu untuk merespons permintaan Anda, jadi gunakan setelan berikut:

  • Tetapkan parameter timeout ke 2 detik.
  • Biarkan setelan batas waktu pada default, yaitu 60 detik untuk permintaan REST.

2. Membuat isi pesan permintaan

Setelah memilih metode optimizeTours pemblokiran dan menentukan setelan waktu tunggu dan batas waktu, langkah berikutnya adalah membuat isi pesan permintaan.

Untuk skenario ini, permintaannya adalah pesan OptimizeToursRequest yang dienkode sebagai JSON di REST API.

Untuk membuat pesan permintaan, ikuti langkah-langkah berikut:

  1. Mulailah dengan struktur permintaan dasar, seperti berikut:

    {
  "timeout": ...,
  "model": {
    "shipments": [...],
    "vehicles": [...],
    "globalStartTime": "...",
    "globalEndTime": "..."
  }
}

    Untuk mengetahui informasi selengkapnya tentang struktur, lihat panduan konsep utama untuk Struktur dasar (ShipmentModel, Shipment, dan Vehicle).

  2. Tentukan pengiriman. Di kolom shipments, tambahkan pesan Shipment untuk setiap yang perlu dijemput dan diantar pada pagi hari. Di sinilah Anda menentukan lokasi dan waktu penjemputan yang diinginkan setiap pemilik, serta lokasi dan waktu pusat penitipan untuk mengantarkan.

    1. Untuk setiap, buat VisitRequest untuk penjemputan dan satu lagi untuk pengantaran, yang, untuk skenario ini, disebut sebagai pengantaran ke tempat penitipan hewan peliharaan.

      • Di penjemputan, tetapkan arrivalWaypoint ke lokasi penjemputan (Coit Tower untuk gunung Bernese, South Sunset Playground Park untuk Chihuahua, atau Land's End untuk German shepherd). Tetapkan timeWindows ke waktu penjemputan yang diminta pemilik (pukul 08.00 hingga 08.20 untuk gunung Bernese dan German shepherd, serta pukul 07.30 hingga 09.30 untuk Chihuahua).

      • Dalam pengiriman, tetapkan arrivalWaypoint ke pusat penitipan anak dan timeWindows untuk waktu pengantaran yang diperlukan (09.30 hingga 11.30).

      • Untuk semua penjemputan dan pengantaran, tetapkan duration ke 5 menit (300s) untuk memperhitungkan waktu menaikkan dan menurunkan.

      Untuk mengetahui informasi selengkapnya tentang periode waktu, lihat Periode waktu.

    2. Untuk memprioritaskan klien reguler, Anda menetapkan penaltyCost ke 1000 untuk gunung Bernese dan Chihuahua, serta 100 untuk German shepherd. Dengan biaya penalti yang ditetapkan, pengoptimal dapat melewati mana pun, tetapi akan mempertimbangkan untuk melewati German shepherd (yang memiliki penalti lebih rendah) terlebih dahulu jika batasan membuat semua penjemputan tidak mungkin dilakukan.

    3. Anda dapat menggunakan kolom label untuk menambahkan ID untuk setiap pengiriman, seperti "Bernese mountain dog", "Chihuahua", dan "German shepherd". Hal ini dapat membantu Anda mengidentifikasi pengiriman dalam respons.

    Untuk mengetahui informasi selengkapnya tentang cara menentukan pengiriman, lihat Pengiriman.

  3. Tentukan kendaraan. Di kolom vehicles, tambahkan pesan Vehicle untuk satu van Anda dengan pusat penitipan anak sebagai titik awal dan akhir, biaya upah pengemudi, dan jam buka untuk van.

    1. Tetapkan startWaypoint dan endWaypoint untuk van ke lokasi awal dan akhir hari, yaitu pusat penitipan anak di dekat Mission Dolores Park.

    2. Untuk meminimalkan biaya operasi, Anda harus menentukan batasan biaya bisnis Anda. Tetapkan parameter biaya costPerHour ke 27, yang merupakan jumlah yang Anda bayarkan kepada pengemudi untuk mengemudikan van penitipan. Untuk mengetahui informasi selengkapnya tentang parameter biaya, lihat Model biaya.

    3. Untuk memastikan pengoptimal membuat rute dalam jam operasional mobil van, tentukan periode operasi untuk kendaraan. Periode ini menetapkan batasan waktu mulai dan berakhir untuk rute. Dengan hanya menentukan setengah dari setiap periode waktu, Anda akan memberi pengoptimal fleksibilitas untuk memulai rute lebih lambat atau mengakhirinya lebih awal:

      • Menyetel startTime di startTimeWindows ke pukul 07.00 berarti pengemudi dapat memulai shiftnya paling awal pukul 07.00. Mereka juga dapat memulai lebih lambat jika tidak ada penjemputan di pagi hari.

      • Menyetel endTime di endTimeWindows ke siang hari berarti pengemudi harus mengakhiri shift mereka pada siang hari. Mereka juga dapat mengakhiri shift segera setelah menyelesaikan pengiriman terakhir.

      Menghilangkan separuh periode lainnya akan meminimalkan waktu tunggu dan pengalihan rute pengemudi. Untuk mengetahui informasi selengkapnya tentang periode waktu, lihat Periode waktu.

    Untuk mengetahui informasi selengkapnya tentang cara menentukan kendaraan, lihat Kendaraan.

  4. Tetapkan periode waktu global. Jendela waktu global menunjukkan jangka waktu kapan van dapat melakukan penjemputan dan pengantaran untuk tempat penitipan anak Anda sepanjang hari. Untuk skenario ini, tetapkan globalStartTime ke pukul 07.00 dan globalEndTime ke pukul 19.00 untuk 13 Februari 2024, yang mewakili jam buka penitipan Anda.

3. Kirim permintaan

Berikut adalah permintaan curl sederhana berdasarkan skenario penitipan dan menggunakan metode optimizeTours pemblokiran.

Sebelum Anda mengirim permintaan, ganti PROJECT_NUMBER_OR_ID dalam kode contoh dengan project ID Google Cloud Anda.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "timeout": "2s",
  "model": {
    "shipments": [
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.802395,
                  "longitude": -122.405822
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Bernese mountain dog",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00-08:00",
                "endTime": "2024-02-13T09:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "Chihuahua",
        "penaltyCost": 1000
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.78018,
                  "longitude": -122.51194
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T08:00:00-08:00",
                "endTime": "2024-02-13T08:20:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.759719,
                  "longitude": -122.42798
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00-08:00",
                "endTime": "2024-02-13T11:30:00-08:00"
              }
            ],
            "duration": "300s"
          }
        ],
        "label": "German shepherd",
        "penaltyCost": 100
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.759719,
              "longitude": -122.42798
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00-08:00"
          }
        ],
        "endTimeWindows": [
          {
            "endTime": "2024-02-13T12:00:00-08:00"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00-08:00",
    "globalEndTime": "2024-02-13T19:00:00-08:00"
  }
}
EOM

Parameter permintaan yang digunakan dalam permintaan

Tabel berikut menjelaskan parameter permintaan yang digunakan dalam isi permintaan skenario contoh. Anda dapat memfilter konten menurut induk atau penelusuran teks.

Orang tua Parameter Jenis Properti Deskripsi
OptimizeToursRequest model objek (ShipmentModel) Ini adalah inti dari permintaan Anda. Ini adalah satu objek tempat Anda menentukan seluruh masalah, termasuk semua yang perlu Anda jemput dan antar (shipments) dan van dalam armada Anda (vehicles). Anggap saja sebagai cetak biru lengkap untuk masalah yang perlu Anda optimalkan.
timeout Durasi Parameter ini menentukan waktu maksimum server mengerjakan permintaan sebelum menampilkan respons. Gunakan parameter ini untuk mempersingkat waktu tunggu Anda. Untuk permintaan kecil dan cepat, seperti skenario penitipan ini, tetapkan nilai ini ke 2 dtk.
ShipmentModel shipments[] array objek (Shipment) Ini adalah array objek yang setiap objeknya mewakili yang perlu dijemput atau diantar.
vehicles[] array objek (Vehicle) Ini adalah array objek yang setiap objeknya menentukan kendaraan dalam armada Anda. Di sinilah Anda mendeskripsikan resource, seperti van yang melakukan pengambilan dan pengantaran. Anda harus menentukan setidaknya satu kendaraan untuk mendapatkan rute yang dioptimalkan.
globalStartTime Stempel waktu Ini adalah waktu paling awal yang memungkinkan untuk terjadinya peristiwa apa pun di seluruh model Anda. Parameter ini mempersempit masalah pengoptimalan dalam waktu, yang sangat penting untuk penghitungan rute dan traffic yang akurat. Untuk skenario penitipan ini, tetapkan ke waktu paling awal pengemudi dapat mengoperasikan van untuk hari itu, yaitu pukul 07.00 untuk 13 Februari 2024.
globalEndTime Stempel waktu Ini adalah waktu paling lambat yang memungkinkan untuk terjadinya peristiwa apa pun di seluruh model Anda. Untuk skenario penitipan ini, tetapkan ini ke waktu mobil van diperkirakan akan mengakhiri operasinya, yaitu pukul 19.00 pada 13 Februari 2024.
Shipment pickups[] array objek (VisitRequest) Ini adalah daftar semua opsi pengambilan yang memungkinkan untuk pengiriman. Pengoptimal akan memilih yang terbaik untuk menyelesaikan masalah Anda. Untuk skenario penitipan ini, cantumkan lokasi penjemputan dan periode waktu yang diberikan setiap pemilik untuk setiap.
deliveries[] array objek (VisitRequest) Ini adalah daftar semua kemungkinan opsi pengantaran untuk pengiriman. Pengoptimal akan memilih yang terbaik untuk menyelesaikan masalah Anda. Untuk skenario penitipan ini, cantumkan lokasi fasilitas penitipan dan periode waktu saat pengemudi harus kembali untuk makan siang untuk setiap.
label string Ini adalah ID untuk pengiriman tertentu dalam permintaan Anda. Anda dapat menentukan label dalam permintaan untuk mempermudah pembacaan respons. Untuk skenario penitipan ini, gunakan string deskriptif seperti "Chihuahua", "Bernese mountain dog", atau nama untuk mencocokkan solusi dengan input Anda saat Anda menerima respons API.
penaltyCost double Ini adalah biaya penalti yang dikenakan jika pengoptimal melewati pengiriman ini. Secara default, pengiriman bersifat wajib—pengoptimal memprioritaskan meminimalkan pengiriman wajib yang dilewati dan hanya melewatinya jika tidak ada opsi lain. Dengan menetapkan biaya penalti, pengoptimal dapat melewati pengiriman jika tidak memungkinkan atau terlalu mahal untuk dilakukan, dan memungkinkan Anda mempertimbangkan prioritas antar-pengiriman. Dalam skenario ini, Anda menetapkan biaya penalti yang lebih tinggi (1000) untuk klien reguler (Bernese mountain dog dan Chihuahua) dan biaya penalti yang lebih rendah (100) untuk permintaan German shepherd di menit terakhir. Hal ini memberi tahu pengoptimal untuk memprioritaskan klien reguler, sehingga pengoptimal akan mempertimbangkan untuk melewati German shepherd terlebih dahulu jika tidak dapat melakukan semua penjemputan.
VisitRequest arrivalWaypoint objek (Waypoint) Ini adalah lokasi kunjungan tertentu di rute. Anda dapat menentukannya menggunakan koordinat lintang dan bujur, ID tempat, atau judul. Dalam skenario penitipan ini, tetapkan ini ke lokasi yang diberikan oleh pemilik untuk pickups dan ke alamat pusat penitipan untuk deliveries.
timeWindows[] array objek (TimeWindow) Ini adalah array objek yang menentukan batasan waktu untuk pengambilan atau pengiriman. Untuk skenario ini, gunakan ini untuk menentukan periode penjemputan untuk setiap dan periode yang dapat diterima untuk mengantarkan ke pusat penitipan hewan.
duration Durasi Parameter ini menentukan durasi kunjungan (misalnya, waktu pemuatan atau pembongkaran). Dalam skenario ini, Anda menetapkan buffer 5 menit (300s) untuk semua penjemputan dan pengantaran guna memperhitungkan waktu yang dibutuhkan pengemudi untuk menaikkan dan menurunkan.
Vehicle startWaypoint objek (Waypoint) Ini adalah lokasi awal rute kendaraan, yang ditentukan dengan koordinat lintang dan bujur atau ID tempat. Parameter ini memberi tahu pengoptimal tempat kendaraan harus memulai rute. Jika Anda tidak menentukan titik jalan ini, pengoptimal akan memilih salah satu pengambilan atau pengiriman sebagai lokasi awal. Untuk skenario penitipan ini, karena pengemudi memulai hari di fasilitas penitipan, gunakan koordinat untuk Mission Dolores Park.
endWaypoint objek (Waypoint) Ini adalah tujuan akhir untuk rute kendaraan, yang ditentukan dengan koordinat lintang dan bujur atau ID tempat. Parameter ini memberi tahu pengoptimal tempat kendaraan harus mengakhiri rute. Jika Anda tidak menentukan titik jalan ini, pengoptimal akan memilih salah satu pengambilan atau pengiriman sebagai akhir rute. Untuk skenario penitipan ini, karena pengemudi harus mengakhiri hari di fasilitas penitipan, gunakan koordinat untuk Mission Dolores Park.
costPerHour angka Ini adalah biaya yang dikeluarkan untuk setiap jam kendaraan digunakan, terlepas dari apakah kendaraan sedang berjalan atau berhenti. Untuk skenario penitipan ini, gunakan ini untuk membuat model upah per jam pengemudi.
startTimeWindows[] array objek (TimeWindow) Ini adalah periode waktu yang dapat diterima saat pengemudi dapat memulai shift mereka. Untuk skenario penitipan ini, tentukan startTime sebagai pukul 07.00, tetapi hilangkan endTime. Hal ini memungkinkan pengoptimal menunda dimulainya shift jika penjemputan pertama dilakukan lebih siang. Perlu diperhatikan bahwa meskipun Anda tidak memberikan endTime untuk startTimeWindows, waktu mulai secara implisit dibatasi oleh endTimeWindows. Kendaraan harus memulai rute sebelum rute berakhir.
endTimeWindows[] array objek (TimeWindow) Ini adalah periode waktu yang dapat diterima bagi pengemudi untuk menyelesaikan rute. Untuk skenario penitipan ini, tentukan endTime sebagai siang hari, tetapi hilangkan startTime. Hal ini memungkinkan pengemudi untuk segera kembali ke pusat penitipan anak setelah pengantaran terakhir.

Berikutnya

Menafsirkan respons