تایم اوت ها و ضرب الاجل ها

این سند نحوه پیکربندی تنظیمات زمان‌بندی و مهلت برای درخواست‌های API بهینه‌سازی مسیر را توضیح می‌دهد. عدم تنظیم این مقادیر یا تنظیم نادرست آنها می‌تواند باعث ایجاد مشکلات کیفیت اتصال یا پاسخ شود.

شما زمان انقضا را در بدنه درخواست و مهلت را در هدر درخواست تعریف می‌کنید. API بهینه‌سازی مسیر، درخواست را در محدوده زمانی تعریف شده توسط این پارامترها، با رعایت کوتاه‌ترین مقدار زمان، پردازش می‌کند.

پیکربندی مهلت‌ها و ضرب‌الاجل‌ها به شما امکان می‌دهد زمان پردازش را به روش‌های زیر مدیریت کنید:

• افزایش زمان پردازش:
  • درخواست‌های با پیچیدگی بالا را حل کنید.
  • پاسخی با کیفیت بالاتر دریافت کنید.
• کاهش زمان پردازش:
  • درخواست‌های با پیچیدگی کم را سریع‌تر از حالت پیش‌فرض حل کنید.
  • یک درخواست را در زمان کمتری حل کنید اما پاسخی با کیفیت پایین‌تر دریافت کنید.

توجه: پارامترهای زمان اتمام و مهلت فقط زمانی اعمال می‌شوند که solvingMode روی مقدار پیش‌فرض خود یعنی DEFAULT_SOLVE تنظیم شده باشد. سایر گزینه‌های solvingMode ، مانند VALIDATE_ONLY ، DETECT_SOME_INFEASIBLE_SHIPMENTS یا TRANSFORM_AND_RETURN_REQUEST معمولاً نیازی به تنظیمات زمان اتمام ندارند زیرا به طور قابل توجهی سریع‌تر هستند.

نیازهای مربوط به مهلت و مهلت زمانی خود را درک کنید

قبل از پیکربندی مهلت‌ها و مهلت‌های زمانی، این بخش را مرور کنید تا مطمئن شوید که می‌دانید انتخاب‌های نقطه پایانی و پروتکل شما چگونه بر این تنظیمات تأثیر می‌گذارند.

دستورالعمل‌های زیر می‌توانند به شما کمک کنند تا مطمئن شوید که از تنظیمات مناسب برای اهداف خود استفاده می‌کنید.

• برای درخواست‌های مداوم و مکرر و برای درخواست‌های پیچیده‌ای که نیاز به زمان حل طولانی‌تری دارند، از نقاط پایانی غیر مسدودکننده استفاده کنید.
• از نقاط انتهایی مسدودکننده برای درخواست‌های کوچک و تحویل سریع نتایج استفاده کنید و در عین حال، کیفیت را نیز در نظر بگیرید.
• از gRPC: برای گردش کار روزانه خود، به ویژه برای برنامه‌های تولیدی، استفاده کنید.
• از REST برای تست، آزمایش یا درخواست‌های تک‌مرحله‌ای استفاده کنید.

برای دیدن نموداری که می‌تواند به شما در تعیین بخش‌هایی از این سند که بیشترین ارتباط را با تنظیمات شما دارند، کمک کند، روی دکمه زیر کلیک کنید.

نمودار را در برگه جداگانه باز کنید

پارامتر timeout را تنظیم کنید

مقدار پارامتر timeout را در بدنه درخواست تنظیم کنید تا حداکثر زمانی که سرور قبل از بازگشت پاسخ، روی یک درخواست کار می‌کند را مشخص کند. اگر API قبل از رسیدن به حداکثر زمان اختصاص داده شده، یک راه حل بهینه پیدا کند، زمان واقعی صرف شده ممکن است کمتر از زمان اختصاص داده شده باشد.

پارامتر timeout را با استفاده از duration protocol buffer تنظیم کنید، که مدت زمانی بر حسب ثانیه است که می‌تواند از ۱ ثانیه تا ۱۸۰۰ ثانیه متغیر باشد. این مقدار را با استفاده از allowLargeDeadlineDespiteInterruptionRisk تا ۳۶۰۰ ثانیه افزایش دهید.

مقادیر توصیه شده timeout

جدول زیر مقادیر توصیه‌شده‌ی timeout بر اساس پیچیدگی درخواست و تعداد محموله‌ها و وسایل نقلیه فهرست می‌کند.

تعداد محموله‌ها و وسایل نقلیه	بدون محدودیت	پنجره‌های زمانی آزاد و محدودیت‌های بار یا مسیرهای طولانی	پنجره‌های زمانی تنگ، محدودیت‌های بار، محدودیت‌های پیچیده یا مسیرهای بسیار طولانی
۱ - ۸	۲ ثانیه	۲ ثانیه	5s
۹ - ۳۲	5s	ده‌ها	دهه بیست زندگی
۳۳ - ۱۰۰	۱۵ ثانیه	دهه 30 میلادی	دهه ۶۰ میلادی
۱۰۱ - ۱۰۰۰	۴۵ ثانیه	دهه ۹۰ میلادی	دهه ۱۸۰ میلادی
۱۰۰۱ تا ۱۰۰۰۰	دهه ۱۲۰ میلادی	۳۶۰s	دهه ۹۰۰ میلادی
۱۰،۰۰۱ یا بیشتر	۶۰ تا ۱۲۰ شیلینگ به ازای هر ۱۰ هزار محموله	۳۶۰ سنت به ازای هر ۱۰ هزار محموله	۹۰۰ شیلینگ به ازای هر ۱۰ هزار محموله

مهلت تعیین کنید

برای تعریف حداکثر زمانی که API بهینه‌سازی مسیر صرف پردازش یک درخواست می‌کند، مهلت را در هدر درخواست تنظیم کنید. بخش‌های زیر نحوه تعیین مهلت برای درخواست‌های REST و gRPC را شرح می‌دهند.

درخواست‌های REST

هنگام استفاده از REST برای فراخوانی یک نقطه پایانی مسدودکننده، می‌توانید مهلت را فراتر از مقدار پیش‌فرض ۶۰ ثانیه افزایش دهید، که اغلب برای درخواست‌های پیچیده بسیار کوتاه است. حتی اگر قبلاً مهلت طولانی‌تری را در بدنه درخواست مشخص کرده باشید، باید این کار را انجام دهید، زیرا مهلت پیش‌فرض، هر مقدار timeout تعیین‌شده در بدنه درخواست که بزرگتر از ۶۰ ثانیه باشد را لغو می‌کند.

با تنظیم هدر درخواست X-Server-Timeout مهلت را فراتر از ۶۰ ثانیه‌ی پیش‌فرض افزایش دهید. برخلاف بدنه‌ی درخواست، مقدار هدر، تعداد ثانیه‌ها است، اما بدون پسوند "s". حداکثر مقداری که می‌توانید برای این هدر تنظیم کنید، با محدودیت‌های پارامتر timeout همسو است.

نمونه کد زیر یک هدر HTTP را نشان می‌دهد که در آن X-Server-Timeout روی ۱۸۰۰ ثانیه تنظیم شده است.

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 نیازی به پیکربندی مهلت ندارید. مهلت پیش‌فرض هنگام استفاده از آنها ۳۶۰۰ ثانیه است که حداکثر زمان درخواست برای این API است. زمان حل مسئله را تنها با تنظیم ویژگی timeout در بدنه درخواست پیکربندی کنید.

پارامترهایی که بر مهلت‌ها و ضرب‌الاجل‌ها تأثیر می‌گذارند

پارامترهای زیر بر نحوه عملکرد مهلت‌ها و مهلت‌ها تأثیر می‌گذارند:

• حداکثر مهلت درخواست را با allowLargeDeadlineDespiteInterruptionRisk کنترل کنید.
• رفتار جستجو را تعریف کنید و کیفیت راه‌حل را در مقابل تأخیر با searchMode متعادل کنید.

allowLargeDeadlineDespiteInterruptionRisk

پارامتر allowLargeDeadlineDespiteInterruptionRisk حداکثر مهلت درخواست را به ۳۶۰۰ ثانیه افزایش می‌دهد. اگر این پارامتر تنظیم نشود، حداکثر مقدار برای هر دو پارامتر timeout و deadline برابر با ۱۸۰۰ ثانیه است.

برای افزایش مقدار پارامترهای timeout و deadline تا ۳۶۰۰ ثانیه، allowLargeDeadline DespiteInterruptionRisk روی true تنظیم کنید.

نکته: تنظیم allowLargeDeadline DespiteInterruptionRisk روی مقدار true ، تأیید می‌کند که درخواست‌های طولانی‌تر، خطر وقفه بیشتری را به همراه دارند که می‌تواند به جای نتیجه‌ی معتبر، منجر به خطا شود.

مقادیر مجاز برای allowLargeDeadline DespiteInterruptionRisk به شرح زیر است:

• true : حداکثر مقدار برای پارامترهای timeout و deadline را به ۳۶۰۰ ثانیه افزایش می‌دهد، ضمن اینکه ریسک وقفه را نیز در نظر می‌گیرد.
• false (پیش‌فرض): حداکثر مقدار را برای پارامترهای timeout و deadline یعنی ۱۸۰۰ ثانیه نگه می‌دارد.

اگر فکر می‌کنید به مدت زمان بیشتری (بیش از ۳۶۰۰ ثانیه) برای وقفه نیاز دارید، با نماینده گوگل خود تماس بگیرید.

searchMode

پارامتر searchMode نحوه جستجوی راه‌حل‌ها توسط بهینه‌ساز را کنترل می‌کند و به شما این امکان را می‌دهد که یا پاسخ سریع‌تر (تأخیر کمتر) یا راه‌حل با کیفیت بالاتر را در اولویت قرار دهید.

وقتی کیفیت بالاتر راه‌حل را در اولویت قرار می‌دهید، بهینه‌ساز زمان نسبتاً زیادی را برای یافتن راه‌حل با کیفیت بالا صرف می‌کند. برای این درخواست‌های طولانی‌تر، تنظیم زمان انتظار طولانی‌تر و استفاده از نقاط پایانی غیر مسدودکننده را برای جلوگیری از مشکلات اتصال در نظر بگیرید.

مقادیر مجاز برای searchMode به شرح زیر است:

• SEARCH_MODE_UNSPECIFIED (پیش‌فرض): یک حالت جستجوی نامشخص، معادل RETURN_FAST .
• RETURN_FAST : جستجو را پس از یافتن اولین راه‌حل خوب متوقف می‌کند.
• CONSUME_ALL_AVAILABLE_TIME : تمام زمان موجود را صرف جستجوی راه‌حل‌های بهتر می‌کند. اگر API زودتر به یک راه‌حل بهینه برسد، از تمام زمان موجود استفاده نمی‌کند.

پینگ‌های keepalive را فعال کنید

وقتی درخواست‌هایی به نقاط انتهایی مسدودکننده با زمان انتظار بیش از ۶۰ ثانیه ارسال می‌کنید، پینگ‌های keepalive به جلوگیری از قطع اتصال در حین انتظار برای پاسخ کمک می‌کنند. پینگ‌های keepalive بسته‌های کوچکی هستند که برای حفظ فعالیت اتصال و شناسایی و جلوگیری از قطع اتصال ارسال می‌شوند.

این پارامترها را بر اساس پروتکل API مورد استفاده خود پیکربندی کنید:

• REST: پیکربندی keepalive در سطح اتصال TCP.
• gRPC: پینگ‌های keepalive را روی سوکت TCP زیرین یا مستقیماً در پروتکل gRPC پیکربندی کنید.

بخش‌های بعدی نحوه تنظیم پینگ‌های keepalive برای هر دو پروتکل را توضیح می‌دهند.

استراحت، زنده نگه‌داشتن

پیکربندی پینگ‌های keepalive هنگام استفاده از REST به کتابخانه کلاینت HTTP شما بستگی دارد. کتابخانه‌ها و ابزارهای کلاینت، مانند curl ، ممکن است گزینه‌های پیکربندی خاصی را ارائه دهند یا پینگ‌ها را به طور خودکار فعال کنند.

اگر کتابخانه شما سوکت TCP زیرین را در معرض دید قرار می‌دهد، می‌توانید پینگ‌های keepalive را مستقیماً روی سوکت TCP با استفاده از گزینه‌هایی مانند SO_KEEPALIVE پیکربندی کنید. این کار را با استفاده از توابعی مانند setsockopt() یا معادل آنها انجام دهید.

این تابع که در گیت‌هاب میزبانی می‌شود، نحوه‌ی تنظیم صحیح این مورد را برای کلاینت HTTP داخلی پایتون نشان می‌دهد.

جزئیات بیشتر در مورد keepalive در سطح TCP را در مرور کلی keepalive در TLDP یا در مستندات کتابخانه کلاینت HTTP خود بیابید.

gRPC را نگه دارید

gRPC مکانیزم keepalive داخلی خود را به عنوان بخشی از پروتکل ارائه می‌دهد. برای دستورالعمل‌های مربوط به نحوه تنظیم این قابلیت در زبان کلاینت خود ، به راهنمای keepalive gRPC مراجعه کنید.

نکته: سرورهای gRPC ممکن است کلاینت‌هایی که پینگ زیادی ارسال می‌کنند را رد کنند. از تنظیم فرکانس پینگ keepalive روی مقادیر خیلی بالا خودداری کنید.

درخواست نمونه gRPC با keepalive

مثال زیر نحوه ایجاد یک درخواست optimizeTours را با استفاده از کتابخانه کلاینت پایتون و پینگ‌های keepalive در سطح 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)