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

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

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

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

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

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

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

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

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

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

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

OptimizeTours

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

{
  "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 ميغابايت تقريبًا.

{
  "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) الناتج هذا بعد اكتمال العملية.

{
  "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 إلى واجهة برمجة التطبيقات. يقرأ الخادم البيانات من معرّفات الموارد المنتظمة (URI) للإدخال ويكتب OptimizeToursResponse لكل طلب مباشرةً في معرّفات الموارد المنتظمة (URI) للإخراج.

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