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

يوضّح هذا المستند كيفية ضبط إعدادات المهلة والوقت النهائي لطلبات 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	2s	2s	5 ثوانٍ
‫9 - 32	5 ثوانٍ	10 ث	20 ث
‫33 - 100	‫15 ثانية	30 ثانية	‫60 ثانية
من 101 إلى 1,000	‫45 ثانية	موسيقى التسعينيات	‫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.

يعرض نموذج الرمز التالي عنوان 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: يقضي كل الوقت المتاح في البحث عن حلول أفضل. لا تستخدم واجهة برمجة التطبيقات كل الوقت المتاح إذا عثرت على حلّ أمثل في وقت مبكر.

تفعيل إشارات keepalive

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

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

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

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

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

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

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

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

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

gRPC keepalive

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

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

نموذج طلب gRPC مع keepalive

يوضّح المثال التالي كيفية إرسال طلب optimizeTours باستخدام مكتبة برامج Python للعميل وعمليات ping لإبقاء الاتصال نشطًا على مستوى 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)