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

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

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

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

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

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

gRPC keepalive

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

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

نموذج طلب 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)