پیکربندی زمان‌های اتمام و مهلت‌ها

این سند نحوه پیکربندی تنظیمات مهلت و زمان اتمام برای درخواست‌های 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 را بااستفاده از میان‌گیر پروتکل مدت تنظیم کنید، که مدت‌زمان برحسب ثانیه است و می‌تواند از ۱ ثانیه تا ۱۸۰۰ ثانیه باشد. این مقدار را بااستفاده از allowLargeDeadlineDespiteInterruptionRisk تا ۳۶۰۰ ثانیه افزایش دهید.

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

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

تعداد محموله‌ها و خودروها	بدون محدودیت	ازدست دادن بازه‌های زمانی و محدودیت‌های بار یا مسیرهای طولانی	پنجره‌های زمانی تنگ، محدودیت‌های بار، محدودیت‌های پیچیده، یا مسیرهای بسیار طولانی
۱ - ۸	‫۲ ثانیه	‫۲ ثانیه	‫۵ ثانیه
۹ - ۳۲	‫۵ ثانیه	‫۱۰ ثانیه	۲۰ ثانیه
‫۳۳ تا ۱۰۰	‫۱۵ ثانیه	‫۳۰ ثانیه	۶۰ ثانیه
‫۱۰۱ تا ۱٬۰۰۰	‫۴۵ ثانیه	دهه ۹۰	‫۱۸۰ ثانیه
۱٬۰۰۱ تا ۱۰٬۰۰۰	‫۱۲۰ ثانیه	۳۶۰ درجه	۹۰۰ ثانیه
‫۱۰٬۰۰۱ یا بیشتر	۶۰ ثانیه + ۱۲۰ ثانیه به‌ازای هر ۱۰ هزار محموله	‫۳۶۰ در هر ۱۰ هزار محموله	‫۹۰۰ ثانیه به‌ازای هر ۱۰ هزار محموله

تنظیم مهلت

مهلت را در سرایند درخواست تنظیم کنید تا حداکثر زمانی را که Route Optimization 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 است. زمان حل را فقط با تنظیم ویژگی زمان‌اتمام در بدنه درخواست پیکربندی کنید.

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

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

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

allowLargeDeadlineDespiteInterruptionRisk

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

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

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

مقادیر مجاز برای allowLargeDeadline DespiteInterruptionRisk عبارت‌اند از:

• true: حداکثر مقدار پارامترهای مهلت و وقفه را به ۳۶۰۰ ثانیه افزایش می‌دهد و درعین‌حال خطر وقفه را تأیید می‌کند.
• false (پیش‌فرض): مقدار حداکثر را برای پارامترهای مهلت و زمان اتمام ۱۸۰۰ ثانیه نگه می‌دارد.

اگر فکر می‌کنید به زمان استراحت بیشتر از ۳۶۰۰ ثانیه نیاز دارید، با نماینده Google تماس بگیرید.

searchMode

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

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

مقادیر مجاز برای searchMode عبارت‌اند از:

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

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

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

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

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

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

REST keepalive

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

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

این تابع میزبانی‌شده در GitHub نشان می‌دهد که چگونه این را به‌درستی برای کارخواه HTTP داخلی Python راه‌اندازی کنید.

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

زنده نگه داشتن gRPC

‫gRPC به‌عنوان بخشی از پروتکل، سازوکار داخلی پایداری اتصال خود را ارائه می‌دهد. برای دریافت دستورالعمل‌های مربوط به نحوه راه‌اندازی این ویژگی در زبان کارخواه، راهنمای keepalive در gRPC را ببینید.

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

درخواست نمونه gRPC با زنده‌نگهداری

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