ضبط المهلات والمواعيد النهائية

يوضّح هذا المستند كيفية ضبط إعدادات المهلة والموعد النهائي لطلبات Route Optimization API. قد يؤدي عدم ضبط هذه القيم أو ضبطها بشكل غير صحيح إلى حدوث مشاكل في الاتصال أو جودة الردود.

يمكنك تحديد المهلة في نص الطلب والموعد النهائي في عنوان الطلب. تعالج Route Optimization API الطلب خلال المهلة المحدّدة من خلال هاتَين المَعلمتَين، مع مراعاة أقصر قيمة للوقت.

يتيح لك ضبط المهلات والمواعيد النهائية إدارة وقت المعالجة بالطرق التالية:

• زيادة وقت المعالجة:
  • حلّ الطلبات عالية التعقيد
  • الحصول على ردّ أعلى جودة
• تقليل وقت المعالجة:
  • حلّ الطلبات منخفضة التعقيد بشكل أسرع من الإعدادات التلقائية
  • حلّ الطلب في وقت أقل ولكن الحصول على ردّ أقل جودة

ملاحظة: لا تنطبق مَعلمات المهلة والموعد النهائي إلا عندما يتم ضبط solvingMode على قيمته التلقائية DEFAULT_SOLVE. لا تتطلّب خيارات solvingMode الأخرى، مثل VALIDATE_ONLY أو DETECT_SOME_INFEASIBLE_SHIPMENTS أو TRANSFORM_AND_RETURN_REQUEST عادةً تعديلات على المهلة لأنّها أسرع بكثير.

فهم احتياجاتك من المهلة والموعد النهائي

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

يمكن أن تساعدك الإرشادات التالية في التأكّد مما إذا كنت تستخدم الإعدادات المناسبة لأهدافك.

• استخدِم نقاط نهاية غير حظر للطلبات المستمرة والمتكررة والطلبات المعقدة التي تستفيد من أوقات الحلّ الأطول.
• استخدِم نقاط نهاية الحظر للطلبات الصغيرة والتسليم السريع للنتائج، مع قبول مقايضة الجودة.
• استخدِم gRPC لسير عملك اليومي، خاصةً للتطبيقات الإنتاجية.
• استخدِم REST للاختبارات أو التجارب أو الطلبات لمرة واحدة.

انقر على الزر أدناه للاطّلاع على رسم بياني يمكن أن يساعدك في تحديد أقسام هذا المستند الأكثر صلة بإعداداتك.

فتح المخطّط البياني في علامة تبويب منفصلة

ضبط المَعلمة timeout

اضبط قيمة المَعلمة timeout في نص الطلب لتحديد الحد الأقصى للوقت الذي يعمل فيه الخادم على طلب قبل عرض ردّ. قد يكون الوقت الفعلي المستغرَق أقصر من الوقت المخصّص إذا عثرت واجهة برمجة التطبيقات على حلّ أمثل قبل الوصول إلى الحد الأقصى للوقت المخصّص.

اضبط المَعلمة timeout باستخدام مخزن البروتوكول المؤقت للمدة، وهو مدة بالثواني يمكن أن تتراوح بين ثانية واحدة و1800 ثانية. يمكنك زيادة هذه القيمة إلى 3600 ثانية باستخدام allowLargeDeadlineDespiteInterruptionRisk.

القيم المقترَحة للمَعلمة timeout

يعرض الجدول التالي القيم المقترَحة للمَعلمة timeout استنادًا إلى مدى تعقيد الطلب وعدد الشحنات والمركبات.

عدد الشحنات والمركبات	بدون قيود	فترات زمنية وقيود على الحمولة غير صارمة أو مسارات طويلة	فترات زمنية وقيود على الحمولة وقيود معقدة أو مسارات طويلة جدًا
من 1 إلى 8	2 ث	2 ث	5 ث
من 9 إلى 32	5 ث	10 ث	20 ث
من 33 إلى 100	15 ث	30 ث	60 ث
من 101 إلى 1,000	45 ث	90 ث	180 ث
من 1,001 إلى 10,000	120 ث	360 ث	900 ث
10,001 أو أكثر	60 ثانية + 120 ثانية لكل 10 آلاف شحنة	360 ثانية لكل 10 آلاف شحنة	900 ثانية لكل 10 آلاف شحنة

ضبط الموعد النهائي

اضبط الموعد النهائي في عنوان الطلب لتحديد الحد الأقصى للوقت الذي تستغرقه Route Optimization API في معالجة الطلب. توضّح الأقسام الفرعية التالية كيفية ضبط المواعيد النهائية لطلبات REST وgRPC.

طلبات REST

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

يمكنك تمديد الموعد النهائي إلى ما بعد القيمة التلقائية البالغة 60 ثانية من خلال ضبط عنوان الطلب X-Server-Timeout. بخلاف نص الطلب، تكون قيمة العنوان هي عدد الثواني، ولكن بدون اللاحقة "s". يتوافق الحد الأقصى للقيمة التي يمكنك ضبطها لهذا العنوان مع القيود المفروضة على المَعلمة timeout's.

يعرض نموذج الرمز البرمجي التالي عنوان HTTP تم ضبط X-Server-Timeout فيه على 1800 ثانية.

curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/:optimizeTours' \
-H "Content-Type: application/json" \
-H "X-Server-Timeout: 1800" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
--data @- << EOM
{
  "model": {
    ...
  }
}
EOM

مكتبات العملاء وطلبات gRPC

لا تحتاج إلى ضبط موعد نهائي عند استخدام مكتبات العملاء أو gRPC. الموعد النهائي التلقائي عند استخدامها هو 3600 ثانية، وهو الحد الأقصى لوقت الطلب لواجهة برمجة التطبيقات هذه. يمكنك ضبط وقت الحلّ من خلال ضبط سمة المهلة فقط في نص الطلب.

المَعلمات التي تؤثر في المهلات والمواعيد النهائية

تؤثر المَعلمات التالية في طريقة عمل كل من المهلات والمواعيد النهائية:

• يمكنك التحكّم في الحد الأقصى للموعد النهائي للطلب باستخدام allowLargeDeadlineDespiteInterruptionRisk.
• يمكنك تحديد سلوك البحث، مع تحقيق التوازن بين جودة الحلّ ووقت الاستجابة باستخدام searchMode.

allowLargeDeadlineDespiteInterruptionRisk

تزيد المَعلمة allowLargeDeadlineDespiteInterruptionRisk الحد الأقصى للموعد النهائي للطلب إلى 3600 ثانية. إذا لم يتم ضبط هذه المَعلمة، يكون الحد الأقصى لقيمتَي المَعلمتَين المهلة والموعد النهائي هو 1800 ثانية.

اضبط allowLargeDeadline DespiteInterruptionRisk على true لـ زيادة قيمة مَعلمتَي المهلة والموعد النهائي إلى ما يصل إلى 3600 ثانية.

ملاحظة: يؤدي ضبط allowLargeDeadline DespiteInterruptionRisk على true إلى الإقرار بأنّ الطلبات الأطول تحمل خطرًا أكبر بالانقطاع، ما قد يؤدي إلى حدوث خطأ بدلاً من الحصول على نتيجة صالحة.

القيم المسموح بها لـ allowLargeDeadline DespiteInterruptionRisk هي الـ تالية:

• true: تزيد الحد الأقصى لقيمتَي مَعلمتَي المهلة والموعد النهائي إلى 3600 ثانية مع الإقرار بخطر الانقطاع.
• false (تلقائي): تحافظ على الحد الأقصى لقيمتَي مَعلمتَي المهلة والموعد النهائي البالغ 1800 ثانية.

إذا كنت تعتقد أنّك بحاجة إلى مهلة أطول من 3600 ثانية، يُرجى التواصل مع ممثل Google الذي تتعامل معه.

searchMode

تتحكّم المَعلمة searchMode في طريقة بحث أداة التحسين عن الحلول، ما يسمح لك بتحديد الأولوية إما لردّ أسرع (وقت استجابة أقل) أو لحلّ أعلى جودة.

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

القيم المسموح بها لـ searchMode هي التالية:

• SEARCH_MODE_UNSPECIFIED (تلقائي): وضع بحث غير محدّد، مكافئ لـ RETURN_FAST.
• RETURN_FAST: يتم إيقاف البحث بعد العثور على أول حلّ جيد.
• CONSUME_ALL_AVAILABLE_TIME: يتم استغراق كل الوقت المتاح للبحث عن حلول أفضل. لا تستخدم واجهة برمجة التطبيقات كل الوقت المتاح إذا عثرت على حلّ أمثل في وقت مبكر.

تفعيل رسائل التحقّق من الاتصال

عند إرسال طلبات إلى نقاط نهاية الحظر بمهلة أطول من 60 ثانية، تساعد رسائل التحقّق من الاتصال في منع فقدان الاتصال أثناء انتظار الردّ. رسائل التحقّق من الاتصال هي حِزم صغيرة يتم إرسالها للحفاظ على نشاط الاتصال، ولرصد فقدان الاتصال ومنعه.

اضبط هذه المَعلمات استنادًا إلى بروتوكول واجهة برمجة التطبيقات الذي تستخدمه:

• REST: اضبط رسالة التحقّق من الاتصال على مستوى اتصال TCP.
• gRPC: اضبط رسائل التحقّق من الاتصال على مقبس TCP الأساسي أو مباشرةً في بروتوكول gRPC.

توضّح الأقسام التالية كيفية إعداد رسائل التحقّق من الاتصال لكلا البروتوكولَين.

طلبات التحقّق من الاتصال في REST

يعتمد ضبط رسائل التحقّق من الاتصال عند استخدام REST على مكتبة عميل HTTP. قد توفّر مكتبات العملاء والأدوات، مثل curl، خيارات ضبط محدّدة أو تفعّل طلبات التحقّق من الاتصال تلقائيًا.

إذا كانت مكتبتك تعرض مقبس TCP الأساسي، يمكنك ضبط رسائل التحقّق من الاتصال مباشرةً على مقبس TCP باستخدام خيارات مثل SO_KEEPALIVE. يمكنك إجراء ذلك باستخدام دوال مثل setsockopt() أو ما يعادلها.

توضّح هذه الدالة المستضافة على GitHub كيفية إعداد ذلك بشكل صحيح لعميل HTTP المضمّن في Python.

يمكنك العثور على مزيد من التفاصيل عن رسالة تحقّق من الاتصال على مستوى TCP في نظرة عامة على رسالة تحقّق من الاتصال في TLDP أو في مستندات مكتبة عميل HTTP.

رسالة تحقّق من الاتصال في gRPC

يوفّر gRPC آلية مدمجة خاصة به لرسائل التحقّق من الاتصال كجزء من البروتوكول. يُرجى الاطّلاع على دليل طلبات التحقّق من الاتصال في gRPC للحصول على تعليمات حول كيفية إعداد ذلك بلغة العميل.

ملاحظة: قد ترفض خوادم gRPC العملاء الذين يرسلون عددًا كبيرًا جدًا من طلبات التحقّق من الاتصال. يُرجى تجنُّب ضبط وتيرة طلبات التحقّق من الاتصال على قيمة عالية جدًا.

نموذج لطلب gRPC مع طلبات التحقّق من الاتصال

يوضّح المثال التالي كيفية إرسال طلب optimizeTours باستخدام مكتبة عميل Python ورسائل التحقّق من الاتصال على مستوى gRPC.

from google.maps import routeoptimization_v1 as ro
from google.maps.routeoptimization_v1.services.route_optimization.transports import grpc as grpc_transport
import sys

_REQUEST_TIMEOUT_SECONDS = 1800
_KEEPALIVE_PING_SECONDS = 30

def create_channel(*args, **kwargs):
  raw_options = kwargs.pop("options", ())
  options = dict(raw_options)
  options["grpc.keepalive_time_ms"] = _KEEPALIVE_PING_SECONDS * 1000
  options["grpc.keepalive_timeout_ms"] = 5000
  # Allow any number of pings between the request and the response.
  options["grpc.http2.max_pings_without_data"] = 0
  print(f"Using options: {options}", file=sys.stderr)
  return grpc_transport.RouteOptimizationGrpcTransport.create_channel(
      *args,
      options=list(options.items()),
      **kwargs,
  )

def create_grpc_transport(*args, **kwargs):
  if "channel" in kwargs:
    raise ValueError(
        "`channel` is overridden by this function, and must not be provided."
    )
  return grpc_transport.RouteOptimizationGrpcTransport(
      *args,
      channel=create_channel,
      **kwargs,
  )

def run_optimize_tours(request):
  client = ro.RouteOptimizationClient(transport=create_grpc_transport)
  return client.optimize_tours(request, timeout=_REQUEST_TIMEOUT_SECONDS)