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

يشرح هذا المستند كيفية ضبط إعدادات المهلة والموعد النهائي لطلبات بيانات من واجهة برمجة التطبيقات 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 ثانية	900s
‫10,001 أو أكثر	‫60 ثانية + 120 ثانية لكل 10,000 شحنة	عدد عمليات الإرجاع لكل 10 آلاف شحنة	‫900 ثانية لكل 10,000 شحنة

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

اضبط الموعد النهائي في عنوان الطلب لتحديد الحد الأقصى للوقت الذي تستغرقه 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 ثانية.

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

searchMode

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

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

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

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

تفعيل اختبارات الاتصال المستمر

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

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

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

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

REST keepalive

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

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

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

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

gRPC keepalive

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

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

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

يوضّح المثال التالي كيفية إجراء طلب 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)