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

يوضّح هذا المستند كيفية ضبط إعدادات المهلة والموعد النهائي لطلبات 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	ثانيتان	ثانيتان	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)