اختيار نقطة نهاية

تتضمّن Route Optimization API نقاط النهاية التالية:

• OptimizeTours: نقطة نهاية حظر للطلبات الفردية.
• OptimizeToursLongRunning: نقطة نهاية غير حاصرة لطلبات فردية تستغرق وقتًا طويلاً لحلّها.
• ‫OptimizeToursUri: نقطة نهاية غير حظرية لطلبات فردية تتطلّب كميات كبيرة من البيانات.
• BatchOptimizeTours: نقطة نهاية غير حظرية لطلبات متعدّدة تتم معالجتها في الوقت نفسه.

يعتمد اختيار نقطة النهاية على حالة الاستخدام وحجم الطلب ووقت الحل المتوقّع وما إذا كنت بحاجة إلى معالجة طلبات متعددة في الوقت نفسه.

مقارنة نقاط النهاية

استخدِم الجدول التالي لتحديد نقطة النهاية المناسبة لاحتياجاتك:

نقطة النهاية	OptimizeTours	OptimizeToursLongRunning	OptimizeToursUri	BatchOptimizeTours
نوع التنفيذ	تؤدي إلى الحظر	لا يسبب الحظر	لا يسبب الحظر	لا يسبب الحظر
الطلبات التي تمت معالجتها	أعزب	أعزب	أعزب	متعدد
الحد الأقصى لحجم الطلب	صغير	متوسطة	كبير	كبير
وقت الحلّ	قصيرة	الصيغة الطويلة	الصيغة الطويلة	الصيغة الطويلة
يتطلّب Google Cloud Storage	لا	لا	نعم	نعم

فهم خصائص نقطة النهاية

يسرد الجدول السابق الخصائص التالية لمساعدتك في اختيار نقطة النهاية المناسبة:

• نوع التنفيذ: يحدّد كيفية تعامل تطبيقك مع اتصال الشبكة أثناء انتظار الرد. هناك نوعان:
  • حظر نقاط النهاية: يجب إبقاء الاتصال مفتوحًا إلى أن تعرض واجهة برمجة التطبيقات استجابة.
  • نقاط النهاية غير الحظر: تعالج الطلبات في الخلفية. تعرض واجهة برمجة التطبيقات على الفور معرّف عملية طويلة الأمد (LRO) يمكنك التحقّق منه لاحقًا لاسترداد النتائج.
• الطلبات التي تمت معالجتها: تحدِّد هذه السمة ما إذا كانت نقطة النهاية تعالج طلب توجيه واحدًا أو تعالج طلبات متعددة في الوقت نفسه.
• الحد الأقصى لحجم الطلب: يتم إرسال الطلبات الصغيرة والمتوسطة الحجم مباشرةً ضمن السطر، وتخضع لحدود من جهة الخادم. تتجاوز الطلبات الكبيرة هذه الحدود باستخدام Google Cloud Storage. يمكنك الاطّلاع على حدود حجم الطلب الدقيقة في أقسام تفاصيل نقاط النهاية.
• وقت الحل: يمكن حلّ الطلبات البسيطة في وقت قصير، بينما تستغرق الطلبات المعقّدة وقتًا أطول. بما أنّ وقت الحل يحدّد المدة التي يجب أن يظل فيها الاتصال مفتوحًا، يعتمد اختيار نقطة النهاية على حدود المهلة المحدّدة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة ضبط المهلات والمواعيد النهائية.
• يتطلّب Google Cloud Storage: تستخدم نقاط النهاية التي تعالج الطلبات والردود الكبيرة Google Cloud Storage مباشرةً لقراءة البيانات وكتابتها. بدلاً من إرسال البيانات في طلب HTTP، يمكنك تحميل طلبك إلى حزمة Cloud Storage وتمرير معرّف الموارد المنتظم (URI) إلى واجهة برمجة التطبيقات.

تفاصيل نقطة النهاية

تتضمّن واجهة Route Optimization API أربع نقاط نهاية. توضّح الأقسام التالية طريقة عمل كل نقطة نهاية وتتضمّن مثالاً على الطلب.

OptimizeTours

OptimizeTours هي نقطة نهاية حظر مخصّصة للطلبات الفردية التي تتطلّب وقتًا قصيرًا لحلّها. تعرض مسارًا محسّنًا مباشرةً في الردّ. بما أنّها نقطة نهاية حظر، يجب إبقاء اتصال الشبكة مفتوحًا إلى أن تنتهي واجهة برمجة التطبيقات من معالجة الطلب لكي تعرض ردًا. يقبل نقطة النهاية هذه طلبات مضمّنة يصل حجمها إلى 4 ميغابايت تقريبًا.

الاطّلاع على OptimizeTours مثال على الطلب

{
  "model": {
    "shipments":[
      {
        "pickups":[
          {
            "arrivalLocation": {
              "latitude": 37.425062,
              "longitude": -122.095355
            }
          }
        ],
        "deliveries":[
          {
            "arrivalLocation": {
              "latitude": 37.424215,
              "longitude": -122.095260
            }
          }
        ]
      }
    ],
    "vehicles":[
      {
        "travelMode": "DRIVING",
        "costPerKilometer": 1.0
      }
    ]
  }
}
    

OptimizeToursLongRunning

OptimizeToursLongRunning هي نقطة نهاية غير حاصرة للطلبات الفردية التي تستغرق وقتًا طويلاً لحلّها. تعرض هذه الطريقة رقم تعريف عملية التشغيل لفترة طويلة (LRO). يمكنك طلب هذا المعرّف باستخدام نقطة النهاية GetOperation للتحقّق من حالة الطلب واسترداد المسارات المحسّنة النهائية. تقبل نقطة النهاية هذه الطلبات المضمّنة التي يصل حجمها إلى 8 ميغابايت تقريبًا.

الاطّلاع على OptimizeToursLongRunning مثال على الطلب

{
  "model": {
    "shipments":[
      {
        "pickups":[
          {
            "arrivalLocation": {
              "latitude": 37.425062,
              "longitude": -122.095355
            }
          }
        ]
      }
    ],
    "vehicles":[
      {
        "travelMode": "DRIVING",
        "costPerKilometer": 1.0
      }
    ]
  }
}
    

OptimizeToursUri

OptimizeToursUri هي نقطة نهاية غير حاصرة مخصّصة للطلبات الفردية التي تستغرق وقتًا طويلاً في حلّها وتتطلّب كميات كبيرة من البيانات (أكثر من 8 ميغابايت). تعرض هذه الطريقة معرّف عملية التشغيل لفترة طويلة (LRO). يمكنك طلب هذا المعرّف باستخدام نقطة النهاية GetOperation للاطّلاع على حالة الطلب.

بدلاً من إرسال الحمولة مضمّنة، يمكنك تحميل OptimizeToursRequest إلى Google Cloud Storage. بعد ذلك، يمكنك تمرير معرّفات الموارد المنتظمة (URI) الخاصة بـ Cloud Storage لكل من طلب الإدخال ووجهة الإخراج إلى واجهة برمجة التطبيقات. يقرأ الخادم البيانات من معرّف الموارد المنتظم (URI) الذي أدخلته ويكتب OptimizeToursResponse النهائي مباشرةً في معرّف الموارد المنتظم (URI) الناتج. يمكنك قراءة المسارات المحسّنة من معرّف الموارد المنتظم (URI) الناتج هذا بعد اكتمال العملية.

الاطّلاع على OptimizeToursUri مثال على الطلب

{
  "input": {
    "uri": "gs://your-bucket/path/input/object.json"
  },
  "output": {
    "uri": "gs://your-bucket/path/output/object.json"
  }
}
    

BatchOptimizeTours

‫BatchOptimizeTours هو نقطة نهاية غير حظر مخصّصة لمعالجة طلبات متعدّدة ومستقلة لتحسين الأداء في الوقت نفسه. تعرض هذه الطريقة رقم تعريف عملية التشغيل لفترة طويلة (LRO). يمكنك طلب هذا المعرّف باستخدام نقطة النهاية GetOperation للاطّلاع على حالة الطلب واسترداد المسارات النهائية المحسّنة.

بدلاً من إرسال الحمولة مضمّنة، يمكنك تحميل عدة OptimizeToursRequest إلى Google Cloud Storage. بعد ذلك، يمكنك تمرير معرّفات الموارد الموحّدة (URI) الخاصة بـ Cloud Storage إلى واجهة برمجة التطبيقات. يقرأ الخادم البيانات من معرّفات الموارد المنتظمة التي أدخلتها ويكتب OptimizeToursResponse لكل طلب مباشرةً في معرّفات الموارد المنتظمة الخاصة بالناتج.

الاطّلاع على BatchOptimizeTours مثال على الطلب

{
  "modelConfigs": [
    {
      "inputConfig": {
        "gcsSource": {
          "uri": "gs://your-bucket/path/input/request_1.json"
        },
        "dataFormat": "JSON"
      },
      "outputConfig": {
        "gcsDestination": {
          "uri": "gs://your-bucket/path/output/response_1.json"
        },
        "dataFormat": "JSON"
      }
    },
    {
      "inputConfig": {
        "gcsSource": {
          "uri": "gs://your-bucket/path/input/request_2.json"
        },
        "dataFormat": "JSON"
      },
      "outputConfig": {
        "gcsDestination": {
          "uri": "gs://your-bucket/path/output/response_2.json"
        },
        "dataFormat": "JSON"
      }
    }
  ]
}