रास्ते के ऑप्टिमाइज़ेशन के लिए अपना पहला अनुरोध करें

यूरोपियन इकनॉमिक एरिया (ईईए) के डेवलपर

इस दस्तावेज़ में, असल दुनिया के इस्तेमाल के उदाहरण के ज़रिए, Route Optimization API के लिए पहला अनुरोध करने का तरीका बताया गया है.

आसानी से समझने के लिए, इस उदाहरण में REST API को दिखाने के लिए एचटीटीपी और JSON का इस्तेमाल किया गया है. हालांकि, आपके प्रोडक्शन एनवायरमेंट के लिए, gRPC का इस्तेमाल करने का सुझाव दिया जाता है, क्योंकि इससे परफ़ॉर्मेंस बेहतर होती है. हालांकि, gRPC को इंस्टॉल करना ज़रूरी है. ज़्यादा जानकारी के लिए, Route Optimization API की क्लाइंट लाइब्रेरी देखें.

स्थिति

सैन फ़्रैंसिस्को का मैप. इसमें कोइट टॉवर, मिशन डोलोरेस पार्क, और साउथ सनसेट प्लेग्राउंड पार्क के लिए पिन मौजूद हैं

आपने सैन फ़्रांसिस्को में पालतू कुत्तों के लिए, सुबह 7:00 बजे से शाम 7:00 बजे तक डेकेयर की सेवा शुरू की है. आज सुबह, आपको शहर की अलग-अलग जगहों से दो कुत्तों को पिक अप करना है. कुत्ते के दोनों मालिकों ने आपको सुबह 7:30 बजे से 9:30 बजे के बीच पिकअप करने का समय दिया है.

आपके पास काम के लिए एक वैन है और ड्राइवर को हर घंटे के हिसाब से 27 डॉलर का पेमेंट किया जाता है. ड्राइवर और वैन, सुबह 7:00 बजे आपके डेकेयर सेंटर से दिन की शुरुआत करते हैं. उन्हें दोपहर 12:00 बजे तक, सुबह बच्चों को पिकअप करने के बाद वापस आना होता है, ताकि वे दोपहर के खाने के लिए ब्रेक ले सकें.

आज 13 फ़रवरी, 2024 है और ड्राइवर को ये टास्क पूरे करने हैं:

  • कोइट टावर के पास बर्नीज़ माउंटेन डॉग को उठाओ.
  • चिहुआहुआ को साउथ सनसेट प्लेग्राउंड पार्क से ले आओ.
  • दोनों कुत्तों को मिशन डोलोरेस पार्क में मौजूद डॉगी डेकेयर सेंटर पर छोड़ दो.

आपको ऐसा रास्ता चाहिए जिससे कुत्तों को वैन में कम से कम समय बिताना पड़े. साथ ही, पिकअप और ड्रॉपऑफ़ की ज़रूरी शर्तें भी पूरी हों.

शुरू करने से पहले

उदाहरण के तौर पर दिए गए इस कोड को चलाने के लिए, आपको सबसे पहले Route Optimization API सेट अप करें में दिए गए निर्देशों को पूरा करना होगा.

1. रास्ते को ऑप्टिमाइज़ करने का तरीका चुनना

Route Optimization API में कई तरीके उपलब्ध हैं. इनमें से किसी एक को चुना जा सकता है. यह इस बात पर निर्भर करता है कि ऑप्टिमाइज़ेशन की समस्या कितनी जटिल है.

डॉग डेकेयर के इस उदाहरण में, अनुरोध छोटा और आसान है. इसलिए, optimizeTours जैसे ब्लॉकिंग तरीके का इस्तेमाल करें. इससे छोटे अनुरोधों के नतीजे तुरंत मिलते हैं. Route Optimization API के तरीकों के बारे में ज़्यादा जानने के लिए, सिंक्रोनस और एसिंक्रोनस एंडपॉइंट देखें.

optimizeTours तरीके के लिए, एचटीटीपी पोस्ट अनुरोध करने के लिए, इस यूआरएल का इस्तेमाल करें:

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

आपको टाइम आउट और समयसीमा की सेटिंग को भी कम पर सेट करना होगा, ताकि इंतज़ार का समय कम हो. डॉग डेकेयर के इस उदाहरण में, ऑप्टिमाइज़र को आपके अनुरोध का जवाब देने के लिए ज़्यादा समय की ज़रूरत नहीं है. इसलिए, इन सेटिंग का इस्तेमाल करें:

  • timeout पैरामीटर को 2 सेकंड पर सेट करें.
  • समयसीमा की सेटिंग को डिफ़ॉल्ट पर छोड़ दें. REST अनुरोधों के लिए, यह 60 सेकंड होती है.

2. अनुरोध के मैसेज का मुख्य हिस्सा बनाना

ब्लॉक करने की optimizeTours विधि चुनने और टाइम आउट और समयसीमा की सेटिंग तय करने के बाद, अगला चरण अनुरोध मैसेज का मुख्य हिस्सा बनाना है.

इस उदाहरण में, अनुरोध एक OptimizeToursRequest मैसेज है, जिसे REST API में JSON के तौर पर कोड में बदला गया है.

अनुरोध का मैसेज बनाने के लिए, यह तरीका अपनाएं:

  1. अनुरोध के बुनियादी स्ट्रक्चर से शुरुआत करें. यह स्ट्रक्चर इस तरह से होता है:

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

    स्ट्रक्चर के बारे में ज़्यादा जानने के लिए, बुनियादी स्ट्रक्चर (ShipmentModel, Shipment, और Vehicle) के बारे में मुख्य कॉन्सेप्ट गाइड देखें.

  2. शिपमेंट तय करें. shipments फ़ील्ड में, हर उस कुत्ते के लिए Shipment मैसेज जोड़ें जिसे सुबह पिक अप और ड्रॉप ऑफ़ करना है. यहां आपको कुत्ते के मालिक की पसंदीदा पिकअप लोकेशन और समय के साथ-साथ, डेकेयर सेंटर की लोकेशन और कुत्तों को छोड़ने का समय तय करना होता है.

    1. हर कुत्ते के लिए, पिकअप के लिए VisitRequest और डिलीवरी के लिए दूसरा VisitRequest बनाएं. इस उदाहरण में, डिलीवरी को डेकेयर ड्रॉपऑफ़ कहा गया है.

      • पिकअप में, कुत्ते के पिकअप की जगह (बर्नीज़ माउंटेन डॉग के लिए कॉइट टावर या चिहुआहुआ के लिए साउथ सनसेट प्लेग्राउंड पार्क) के हिसाब से arrivalWaypoint और मालिक के अनुरोध किए गए पिकअप के समय (सुबह 7:30 बजे से 9:30 बजे) के हिसाब से timeWindows सेट करें.

      • डिलीवरी के लिए, arrivalWaypoint को डेकेयर सेंटर और timeWindows को ड्रॉपऑफ़ के लिए ज़रूरी समय (सुबह 9:30 बजे से 11:30 बजे तक) पर सेट करें.

      टाइम विंडो के बारे में ज़्यादा जानने के लिए, टाइम विंडो देखें.

    2. label फ़ील्ड का इस्तेमाल करके, हर शिपमेंट के लिए एक आइडेंटिफ़ायर जोड़ा जा सकता है. जैसे, "बर्नीज़ माउंटेन डॉग" और "चिहुआहुआ". इससे आपको जवाब में मौजूद शिपमेंट की पहचान करने में मदद मिल सकती है.

    शिपमेंट तय करने के बारे में ज़्यादा जानकारी के लिए, शिपमेंट देखें.

  3. वाहनों के बारे में जानकारी दें. vehicles फ़ील्ड में, अपनी एक वैन के लिए Vehicle मैसेज जोड़ें. इसमें डेकेयर सेंटर को शुरुआती और आखिरी पॉइंट के तौर पर शामिल करें. साथ ही, ड्राइवर के वेतन और वैन के चलने के समय की जानकारी दें.

    1. वैन के लिए, दिन की शुरुआत और आखिर की जगहों के तौर पर startWaypoint और endWaypoint सेट करें. ये जगहें, मिशन डोलोरेस पार्क के पास मौजूद डेकेयर सेंटर हैं.

    2. अपने बिज़नेस के लिए, ऑपरेशन की लागत को कम करने के लिए, आपको अपने बिज़नेस की लागत की सीमाएं तय करनी होंगी. लागत पैरामीटर costPerHour को 27 पर सेट करें. यह वह रकम है जो आपने कुत्ते को डेकेयर ले जाने वाले ड्राइवर को दी है. लागत के पैरामीटर के बारे में ज़्यादा जानने के लिए, लागत मॉडल देखें.

    3. यह पक्का करने के लिए कि ऑप्टिमाइज़र, वैन के कामकाजी घंटों के दौरान रूट बनाए, startTimeWindows को उस मान्य सीमा के तौर पर तय करें जिसमें ड्राइवर वैन चलाना शुरू कर सकता है. साथ ही, endTimeWindows को उस मान्य सीमा के तौर पर तय करें जिसमें ड्राइवर को डेकेयर सेंटर वापस लौटना होगा. टाइम विंडो के बारे में ज़्यादा जानने के लिए, टाइम विंडो देखें.

    वाहनों को तय करने के बारे में ज़्यादा जानकारी के लिए, वाहन देखें.

  4. ग्लोबल टाइम विंडो सेट करें. ग्लोबल टाइम विंडो से पता चलता है कि वैन, पूरे दिन में किस समयावधि के दौरान आपके डेकेयर से बच्चों को पिकअप और ड्रॉप ऑफ़ कर सकती है. इस उदाहरण के लिए, 13 फ़रवरी, 2024 के लिए globalStartTime को सुबह 7:00 बजे और globalEndTime को शाम 7:00 बजे पर सेट करें. यह आपके डॉगी डेकेयर के खुलने और बंद होने का समय है.

3. अनुरोध भेजें

यहां कुत्ते की देखभाल करने वाले डेकेयर के उदाहरण के आधार पर, curl का एक सामान्य अनुरोध दिया गया है. इसमें, optimizeTours को ब्लॉक करने के तरीके का इस्तेमाल किया गया है.

अनुरोध भेजने से पहले, सैंपल कोड में मौजूद PROJECT_NUMBER_OR_ID की जगह अपना Google Cloud प्रोजेक्ट आईडी डालें.

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-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Bernese mountain dog"
      },
      {
        "pickups": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.738067,
                  "longitude": -122.498593
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T07:30:00Z",
                "endTime": "2024-02-13T09:30:00Z"
              }
            ]
          }
        ],
        "deliveries": [
          {
            "arrivalWaypoint": {
              "location": {
                "latLng": {
                  "latitude": 37.760202,
                  "longitude": -122.426796
                }
              }
            },
            "timeWindows": [
              {
                "startTime": "2024-02-13T09:30:00Z",
                "endTime": "2024-02-13T11:30:00Z"
              }
            ]
          }
        ],
        "label": "Chihuahua"
      }
    ],
    "vehicles": [
      {
        "startWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "endWaypoint": {
          "location": {
            "latLng": {
              "latitude": 37.760202,
              "longitude": -122.426796
            }
          }
        },
        "costPerHour": 27,
        "startTimeWindows": [
          {
            "startTime": "2024-02-13T07:00:00Z",
            "endTime": "2024-02-13T07:15:00Z"
          }
        ],
        "endTimeWindows": [
          {
            "startTime": "2024-02-13T11:45:00Z",
            "endTime": "2024-02-13T12:00:00Z"
          }
        ]
      }
    ],
    "globalStartTime": "2024-02-13T07:00:00Z",
    "globalEndTime": "2024-02-13T19:00:00Z"
  }
}
EOM

अनुरोध में इस्तेमाल किए गए अनुरोध पैरामीटर

यहां दी गई टेबल में, उदाहरण के तौर पर दिए गए अनुरोध के मुख्य हिस्से में इस्तेमाल किए गए अनुरोध पैरामीटर के बारे में बताया गया है. कॉन्टेंट को पैरंट के हिसाब से या टेक्स्ट खोज के हिसाब से फ़िल्टर किया जा सकता है.

Parent पैरामीटर प्रॉपर्टी का टाइप ब्यौरा
OptimizeToursRequest model ऑब्जेक्ट (ShipmentModel) यह आपके अनुरोध का मुख्य हिस्सा है. यह एक ऐसा ऑब्जेक्ट है जिसमें आपको अपनी पूरी समस्या के बारे में बताना होता है. इसमें उन सभी कुत्तों के बारे में जानकारी शामिल होती है जिन्हें पिक अप और ड्रॉप ऑफ़ करना है (shipments). साथ ही, इसमें आपके फ़्लीट में मौजूद वैन (vehicles) के बारे में जानकारी शामिल होती है. इसे उस समस्या के पूरे ब्लूप्रिंट के तौर पर देखा जा सकता है जिसे आपको ऑप्टिमाइज़ करना है.
timeout कुल समय यह पैरामीटर, सर्वर के लिए ज़्यादा से ज़्यादा समय तय करता है. इस समय के अंदर, सर्वर को किसी अनुरोध पर काम करके जवाब देना होता है. इस पैरामीटर का इस्तेमाल करके, इंतज़ार का समय कम करें. छोटे और तुरंत पूरे किए जाने वाले अनुरोधों के लिए, इस वैल्यू को 2 सेकंड पर सेट करें. जैसे, कुत्ते की देखभाल करने वाले डेकेयर के बारे में जानकारी देने का अनुरोध.
ShipmentModel shipments[] ऑब्जेक्ट का कलेक्शन (Shipment) यह ऑब्जेक्ट का एक ऐसा कलेक्शन है जिसमें हर ऑब्जेक्ट, पिक अप या ड्रॉप ऑफ़ किए जाने वाले कुत्ते के बारे में बताता है.
vehicles[] ऑब्जेक्ट का कलेक्शन (Vehicle) यह ऑब्जेक्ट की एक कैटगरी है. इसमें मौजूद हर ऑब्जेक्ट, आपकी फ्लीट में मौजूद किसी वाहन के बारे में बताता है. इसमें आपको अपने संसाधनों के बारे में बताना होता है. जैसे, पिकअप और ड्रॉपऑफ़ करने वाली वैन. ऑप्टिमाइज़ किया गया रूट पाने के लिए, आपको कम से कम एक वाहन की जानकारी देनी होगी.
globalStartTime टाइमस्टैम्प यह आपके पूरे मॉडल में किसी भी इवेंट के होने का सबसे पहला समय है. यह पैरामीटर, ऑप्टिमाइज़ेशन की समस्या को कम समय में हल करता है. यह ट्रैफ़िक और राउटिंग की सटीक जानकारी का हिसाब लगाने के लिए ज़रूरी है. कुत्ते की डेकेयर सेवा के इस उदाहरण के लिए, इसे उस समय पर सेट करें जब ड्राइवर दिन में सबसे पहले वैन चला सकता है. 13 फ़रवरी, 2024 के लिए यह समय सुबह 7:00 बजे है.
globalEndTime टाइमस्टैम्प यह आपके पूरे मॉडल में किसी भी इवेंट के होने का सबसे नया समय है. डॉग डेकेयर के इस उदाहरण के लिए, इस फ़ील्ड में वह समय डालें जब वैन अपनी सेवा खत्म करेगी. 13 फ़रवरी, 2024 के लिए यह समय शाम 7:00 बजे है.
Shipment pickups[] ऑब्जेक्ट का कलेक्शन (VisitRequest) यह शिपमेंट के लिए, पिकअप के सभी संभावित विकल्पों की सूची है. ऑप्टिमाइज़र, आपकी समस्या को हल करने के लिए सबसे सही तरीका चुनता है. कुत्ते की देखभाल करने वाले इस डेकेयर के लिए, पिकअप करने की जगहों और समय की जानकारी दें. यह जानकारी, हर मालिक ने हर कुत्ते के लिए दी है.
deliveries[] ऑब्जेक्ट का कलेक्शन (VisitRequest) यह शिपमेंट के लिए, ड्रॉपऑफ़ के सभी संभावित विकल्पों की सूची है. ऑप्टिमाइज़र, आपकी समस्या को हल करने के लिए सबसे सही तरीका चुनता है. इस डॉगी डेकेयर के उदाहरण के लिए, डॉगी डेकेयर की जगह की जानकारी और हर कुत्ते के लिए, ड्राइवर के दोपहर के खाने के लिए लौटने का समय बताएं.
label स्ट्रिंग यह आपकी अनुरोध में मौजूद किसी शिपमेंट के लिए आइडेंटिफ़ायर है. जवाब को आसानी से पढ़ने के लिए, अपने अनुरोध में लेबल तय किए जा सकते हैं. डॉग डेकेयर के इस उदाहरण के लिए, "चिहुआहुआ", "बर्नीज़ माउंटेन डॉग" या कुत्ते के नाम जैसी जानकारी देने वाली स्ट्रिंग का इस्तेमाल करें, ताकि एपीआई से मिले जवाब में आपके इनपुट से मिलता-जुलता समाधान मिल सके.
VisitRequest arrivalWaypoint[] ऑब्जेक्ट (Waypoint) यह रूट पर किसी खास जगह की यात्रा की जानकारी है. इसे अक्षांश और देशांतर निर्देशांक, जगह का आईडी या हेडिंग का इस्तेमाल करके तय किया जा सकता है. पालतू जानवरों के देखभाल केंद्र के इस उदाहरण में, pickups के लिए इसे मालिक की दी गई जगह की जानकारी पर सेट करें. साथ ही, deliveries के लिए इसे देखभाल केंद्र के पते पर सेट करें.
timeWindows[] ऑब्जेक्ट का कलेक्शन (TimeWindow) यह ऑब्जेक्ट का एक ऐसा कलेक्शन है जो पिकअप या डिलीवरी के लिए समयसीमा तय करता है. इस उदाहरण के लिए, इस फ़ील्ड का इस्तेमाल करके हर कुत्ते को पिकअप करने का समय और उन्हें डेकेयर सेंटर पर छोड़ने का समय तय करें.
Vehicle startWaypoint[] ऑब्जेक्ट (Waypoint) यह वाहन के रास्ते की शुरुआती जगह है. इसे अक्षांश और देशांतर निर्देशांक या जगह के आईडी से तय किया जाता है. इस पैरामीटर से ऑप्टिमाइज़र को पता चलता है कि वाहन को यात्रा कहां से शुरू करनी है. अगर आपने इस वेपॉइंट को तय नहीं किया है, तो ऑप्टिमाइज़र, पिकअप या डिलीवरी की किसी एक जगह को शुरुआती जगह के तौर पर चुनता है. इस डॉगी डेकेयर के उदाहरण में, ड्राइवर दिन की शुरुआत डेकेयर फ़ैसिलिटी से करता है. इसलिए, मिशन डेलोरस पार्क के कोऑर्डिनेट का इस्तेमाल करें.
endWaypoint[] ऑब्जेक्ट (Waypoint) यह वाहन के रूट की आखिरी मंज़िल होती है. इसे अक्षांश और देशांतर निर्देशांकों या जगह के आईडी के साथ तय किया जाता है. इस पैरामीटर से ऑप्टिमाइज़र को पता चलता है कि वाहन को रूट कहां खत्म करना है. अगर आपने इस वेपॉइंट को तय नहीं किया है, तो ऑप्टिमाइज़र, पिकअप या डिलीवरी की किसी एक जगह को रास्ते के आखिर में मौजूद जगह के तौर पर चुनता है. कुत्ते की डेकेयर सेवा के इस उदाहरण में, ड्राइवर को दिन के आखिर में डेकेयर फ़ैसिलिटी पर पहुंचना होता है. इसलिए, मिशन डेलोरस पार्क के निर्देशांकों का इस्तेमाल करें.
costPerHour संख्या यह वाहन के इस्तेमाल का हर घंटे का शुल्क है. इससे कोई फ़र्क़ नहीं पड़ता कि वाहन चल रहा है या रुका हुआ है. कुत्ते की देखभाल करने वाले इस डेकेयर के लिए, ड्राइवर की हर घंटे की मजदूरी का मॉडल बनाने के लिए इसका इस्तेमाल करें.
startTimeWindows[] ऑब्जेक्ट का कलेक्शन (TimeWindow) यह वह समयसीमा है जिसमें ड्राइवर, सुबह कुत्तों को पिकअप करने के लिए वैन चला सकता है.
endTimeWindows[] ऑब्जेक्ट का कलेक्शन (TimeWindow) यह वह समयसीमा है जिसमें ड्राइवर को वैन चलाकर वापस डॉगी डेकेयर सेंटर पहुंचना होता है.

अगला

जवाब को समझना