הגדרת פסק זמן ומועדים

במאמר הזה מוסבר איך להגדיר את הזמן הקצוב לתפוגה ואת המועד האחרון לבקשות ל-Route Optimization API. אם לא תגדירו את הערכים האלה או תגדירו אותם בצורה שגויה, יכולות להיות בעיות בחיבור או באיכות התשובות.

מגדירים את הזמן הקצוב לתפוגה בגוף הבקשה ואת המועד האחרון בכותרת הבקשה. ‫Route Optimization API מעבד את הבקשה במסגרת מגבלת הזמן שמוגדרת בפרמטרים האלה, בהתאם לערך הזמן הקצר ביותר.

הגדרת זמן קצוב לתפוגה ומועדים אחרונים מאפשרת לכם לנהל את זמן העיבוד בדרכים הבאות:

• הארכת זמן העיבוד:
  • לפתור בעיות מורכבות.
  • לקבל תשובה באיכות גבוהה יותר.
• קיצור זמן העיבוד:
  • לפתור בקשות פשוטות מהר יותר מאשר במצב ברירת המחדל.
  • לפתור בקשה בפחות זמן אבל לקבל תשובה באיכות נמוכה יותר.

הערה: הפרמטרים של זמן קצוב לתפוגה ומועד אחרון חלים רק כש-solvingMode מוגדר לערך ברירת המחדל שלו, DEFAULT_SOLVE. בדרך כלל לא צריך לשנות את זמן הקצוב לתפוגה באפשרויות אחרות של solvingMode, כמו VALIDATE_ONLY,‏ DETECT_SOME_INFEASIBLE_SHIPMENTS או TRANSFORM_AND_RETURN_REQUEST, כי הן מהירות יותר באופן משמעותי.

הבנת הצרכים שלכם בנוגע לזמן קצוב לתפוגה ולמועד אחרון

לפני שאתם מגדירים את הזמן הקצוב לתפוגה ואת המועדים האחרונים, כדאי לקרוא את הקטע הזה כדי לוודא שאתם מבינים איך הבחירות של נקודת הקצה והפרוטוקול משפיעות על ההגדרות האלה.

ההנחיות הבאות יכולות לעזור לכם לוודא שאתם משתמשים בהגדרה הנכונה בהתאם ליעדים שלכם.

• כדאי להשתמש בנקודות קצה (endpoint) לא חוסמות לבקשות חוזרות ונשנות, ולבקשות מורכבות שדורשות יותר זמן לפתרון.
• כדאי להשתמש בנקודות קצה חוסמות לבקשות קטנות ולקבלת תוצאות מהירות, תוך התפשרות על האיכות.
• gRPC: לתהליך העבודה היומיומי, במיוחד לאפליקציות בסביבת הייצור.
• השתמשו ב-REST לבדיקות, לניסויים או לבקשות חד-פעמיות.

כדי לראות דיאגרמה שיעזור לכם להבין אילו חלקים במסמך הזה הכי רלוונטיים להגדרה שלכם, לחצו על הכפתור הבא.

פתיחת התרשים בכרטיסייה נפרדת

הגדרת הפרמטר timeout

מגדירים את הערך של הפרמטר timeout בגוף הבקשה כדי לציין את משך הזמן המקסימלי שהשרת יעבוד על בקשה לפני שיחזיר תשובה. אם ה-API ימצא פתרון אופטימלי לפני שיגיע למגבלת הזמן, יכול להיות שהזמן בפועל יהיה קצר יותר מהזמן שהוקצה.

מגדירים את הפרמטר timeout באמצעות מאגר האחסון לפרוטוקולים של משך הזמן, שהוא משך זמן בשניות שיכול לנוע בין שנייה אחת ל-1,800 שניות. אפשר להגדיל את הערך הזה עד 3,600 שניות באמצעות 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 מעלות	‫900 שניות
‫10,001 או יותר	‫60 שניות + 120 שניות לכל 10,000 משלוחים	מספר הסרטונים ב-360 לכל 10,000 משלוחים	‫900 שניות לכל 10,000 משלוחים

הגדרת המועד האחרון להגשה

כדי להגדיר את משך הזמן המקסימלי שבו ה-Route Optimization API מעבד בקשה, מגדירים את המועד האחרון בכותרת הבקשה. בסעיפי המשנה הבאים מוסבר איך להגדיר מועדים אחרונים לבקשות REST ו-gRPC.

בקשות REST

כשמשתמשים ב-REST כדי לקרוא לנקודת קצה חוסמת, אפשר להאריך את המועד האחרון מעבר לברירת המחדל של 60 שניות, שלעיתים קרובות קצרה מדי לבקשות מורכבות. צריך לעשות את זה גם אם כבר ציינתם מועד אחרון ארוך יותר בגוף הבקשה, כי המועד האחרון שמוגדר כברירת מחדל מבטל כל ערך של timeout שמוגדר בגוף הבקשה וגדול מ-60 שניות.

כדי להאריך את המועד האחרון מעבר לברירת המחדל של 60 שניות, מגדירים את כותרת הבקשה X-Server-Timeout. בניגוד לגוף הבקשה, הערך של הכותרת הוא מספר השניות, אבל בלי הסיומת "s". הערך המקסימלי שאפשר להגדיר לכותרת הזו תואם להגבלות של הפרמטר timeout.

בדוגמת הקוד הבאה מוצגת כותרת HTTP שבה הערך של X-Server-Timeout מוגדר ל-1,800 שניות.

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, לא צריך להגדיר מועד אחרון. מועד ההגשה הסופי שמוגדר כברירת מחדל כשמשתמשים בהם הוא 3,600 שניות, זמן הבקשה המקסימלי ל-API הזה. כדי להגדיר את זמן הפתרון, צריך להגדיר רק את המאפיין timeout בגוף הבקשה.

פרמטרים שמשפיעים על זמני קצובות לתפוגה ומועדים אחרונים

הפרמטרים הבאים משפיעים על אופן הפעולה של זמן קצוב לתפוגה ושל מועדים אחרונים:

• אפשר לשלוט במועד האחרון המקסימלי לשליחת בקשה באמצעות allowLargeDeadlineDespiteInterruptionRisk.
• מגדירים את אופן הפעולה של החיפוש, ומאזנים בין איכות הפתרון לבין זמן האחזור באמצעות searchMode.

allowLargeDeadlineDespiteInterruptionRisk

הפרמטר allowLargeDeadlineDespiteInterruptionRisk מגדיל את המועד האחרון המקסימלי לבקשה ל-3,600 שניות. אם הפרמטר הזה לא מוגדר, הערך המקסימלי של הפרמטרים timeout ו-deadline הוא 1,800 שניות.

מגדירים את allowLargeDeadline DespiteInterruptionRisk ל-true כדי להגדיל את הערך של הפרמטרים timeout ו-deadline עד ל-3,600 שניות.

הערה: הגדרת allowLargeDeadline DespiteInterruptionRisk לערך true מציינת שבקשות ארוכות יותר נושאות סיכון גבוה יותר להפרעה, שעלולה לגרום לשגיאה במקום לתוצאה תקינה.

הערכים המותרים ל-allowLargeDeadline DespiteInterruptionRisk הם:

• ‫true: מגדיל את הערך המקסימלי של הפרמטרים של הזמן הקצוב לתפוגה ומועד אחרון ל-3,600 שניות, תוך הכרה בסיכון להפרעה.
• ‫false (ברירת המחדל): הערך המקסימלי של הפרמטרים של הזמן הקצוב לתפוגה ומועד ההגשה הוא 1,800 שניות.

אם אתם חושבים שאתם צריכים זמן קצוב לתפוגה ארוך יותר מ-3,600 שניות, פנו לנציג של Google.

searchMode

הפרמטר searchMode קובע איך הכלי לאופטימיזציה יחפש פתרונות, ומאפשר לכם לתת עדיפות לתגובה מהירה יותר (זמן אחזור קצר יותר) או לפתרון באיכות גבוהה יותר.

כשמתעדפים פתרון באיכות גבוהה יותר, לכלי האופטימיזציה נדרש זמן רב כדי למצוא פתרון באיכות גבוהה. בבקשות הארוכות האלה, כדאי להגדיר זמן קצוב ארוך יותר ולהשתמש בנקודות קצה שלא חוסמות כדי למנוע בעיות בחיבור.

הערכים המותרים ל-searchMode הם:

• ‫SEARCH_MODE_UNSPECIFIED (ברירת מחדל): מצב חיפוש לא מוגדר, שווה ערך ל-RETURN_FAST.
• ‫RETURN_FAST: החיפוש נפסק אחרי שנמצא הפתרון הטוב הראשון.
• ‫CONSUME_ALL_AVAILABLE_TIME: מקדיש את כל הזמן הפנוי לחיפוש פתרונות טובים יותר. ה-API לא משתמש בכל הזמן הזמין אם הוא מוצא פתרון אופטימלי מוקדם.

הפעלת פינגים של keepalive

כששולחים בקשות לנקודות קצה חוסמות עם זמן קצוב לתפוגה של יותר מ-60 שניות, פינגים של keepalive עוזרים למנוע אובדן של החיבור בזמן שממתינים לתגובה. פינגים של Keepalive הם חבילות קטנות שנשלחות כדי לשמור על פעילות החיבור, וכדי לזהות ולמנוע אובדן חיבור.

מגדירים את הפרמטרים האלה בהתאם לפרוטוקול ה-API שבו משתמשים:

• ‫REST: מגדירים את keepalive ברמת החיבור של TCP.
• ‫gRPC: מגדירים פינגים של keepalive בשקע ה-TCP הבסיסי או ישירות בפרוטוקול gRPC.

בקטעים הבאים מוסבר איך להגדיר פינגים של keepalive בשני הפרוטוקולים.

‫REST keepalive

הגדרת פינגים של keepalive כשמשתמשים ב-REST תלויה בספריית הלקוח של HTTP. ספריות לקוח וכלים, כמו curl, עשויים לספק אפשרויות הגדרה ספציפיות או להפעיל פינגים באופן אוטומטי.

אם הספרייה חושפת את שקע ה-TCP הבסיסי, אפשר להגדיר פינגים של keepalive ישירות בשקע ה-TCP באמצעות אפשרויות כמו SO_KEEPALIVE. כדי לעשות את זה, משתמשים בפונקציות כמו setsockopt() או בפונקציות מקבילות.

הפונקציה הזו שמתארחת ב-GitHub מדגימה איך להגדיר את זה בצורה נכונה לצד הלקוח ב-HTTP המובנה של Python.

למידע נוסף על הודעות keepalive ברמת ה-TCP, קראו את הסקירה הכללית של TLDP בנושא keepalive או את מסמכי התיעוד של ספריית הלקוח של HTTP.

gRPC keepalive

ל-gRPC יש מנגנון keepalive מובנה משלו כחלק מהפרוטוקול. במדריך של gRPC בנושא keepalive מוסבר איך להגדיר את זה בשפת הלקוח.

הערה: שרתי gRPC עשויים לדחות לקוחות ששולחים יותר מדי פינגים. מומלץ לא להגדיר תדירות גבוהה מדי של פינגים לשמירת החיבור.

בקשת gRPC לדוגמה עם keepalive

בדוגמה הבאה מוסבר איך לשלוח בקשת 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)