Method: computeRouteMatrix

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

הערה: בשיטה הזו צריך לציין מסכה של שדה תגובה בקלט. אפשר לספק את המסכה של שדה התגובה באמצעות הפרמטר של כתובת ה-URL $fields או fields, או באמצעות הכותרת HTTP/gRPC‏ X-Goog-FieldMask (ראו הפרמטרים והכותרות הזמינים של כתובות URL). הערך הוא רשימה של נתיבים של שדות, מופרדים בפסיקים. איך יוצרים את נתיבי השדות

לדוגמה, בשיטה הזו:

  • אנונימיזציה של כל השדות הזמינים (לבדיקה ידנית): X-Goog-FieldMask: *
  • מסכת שדה של משכי זמן, מרחקים, סטטוס רכיבים, תנאים ומערכי רכיבים של מסלולים (דוגמה להגדרה בסביבת הייצור): X-Goog-FieldMask: originIndex,destinationIndex,status,condition,distanceMeters,duration

חשוב מאוד לכלול את status במסכת השדה, אחרת כל ההודעות יופיעו כתקינות. Google ממליצה לא להשתמש במסכת השדה של התגובה עם התו הכללי לחיפוש (*), כי:

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

בקשת HTTP

POST https://routes.googleapis.com/distanceMatrix/v2:computeRouteMatrix

כתובת ה-URL משתמשת בתחביר של Transcoding של gRPC.

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "origins": [
    {
      object (RouteMatrixOrigin)
    }
  ],
  "destinations": [
    {
      object (RouteMatrixDestination)
    }
  ],
  "travelMode": enum (RouteTravelMode),
  "routingPreference": enum (RoutingPreference),
  "departureTime": string,
  "arrivalTime": string,
  "languageCode": string,
  "regionCode": string,
  "units": enum (Units),
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "trafficModel": enum (TrafficModel),
  "transitPreferences": {
    object (TransitPreferences)
  }
}
שדות
origins[]

object (RouteMatrixOrigin)

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

  • הסכום של מספר מקורות הנתונים + מספר היעדים שצוינו כ-placeId או כ-address לא יכול להיות גדול מ-50.
  • המכפלה של מספר מקורות x מספר יעדים לא יכולה להיות גדולה מ-625 בכל מקרה.
  • אם הערך של routingPreference מוגדר כ-TRAFFIC_AWARE_OPTIMAL, המכפלה של מספר מקורות × מספר יעדים לא יכולה להיות גדולה מ-100.
  • המכפלה של מספר המקוריים × מספר היעדים לא יכולה להיות גדולה מ-100 אם הערך של travelMode מוגדר כ-TRANSIT.
destinations[]

object (RouteMatrixDestination)

חובה. מערך של יעדים, שקובע את העמודות של מטריצה התגובה.
travelMode

enum (RouteTravelMode)

אופציונלי. מציין את אמצעי התחבורה.
routingPreference

enum (RoutingPreference)

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

string (Timestamp format)

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

הפורמט הזה משתמש ב-RFC 3339, שבו הפלט שנוצר תמיד יהיה מנורמלי לפי Z וישמש בספרות עשרוניות של 0, 3, 6 או 9. אפשר להשתמש גם בשינויים (offsets) אחרים מלבד 'Z'. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
arrivalTime

string (Timestamp format)

אופציונלי. שעת ההגעה. הערה: אפשר להגדיר את השדה הזה רק אם הערך של RouteTravelMode הוא TRANSIT. אפשר לציין departureTime או arrivalTime, אבל לא את שניהם.

הפורמט הזה משתמש ב-RFC 3339, שבו הפלט שנוצר תמיד יהיה מנורמלי לפי Z וישמש בספרות עשרוניות של 0, 3, 6 או 9. אפשר להשתמש גם בשינויים (offsets) אחרים מלבד 'Z'. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
languageCode

string

אופציונלי. קוד השפה לפי BCP-47, למשל 'en-US' או 'sr-Latn'. מידע נוסף זמין במאמר מזהה המקום (locale) של Unicode. כאן אפשר לעיין ברשימת השפות הנתמכות. אם לא מציינים את הערך הזה, שפת התצוגה נובעת מהמיקום של המקור הראשון.
regionCode

string

אופציונלי. קוד האזור, שמצוין כערך בן שתי אותיות של דומיין ברמה עליונה עם קוד מדינה (ccTLD). מידע נוסף זמין במאמר דומיינים ברמה העליונה עם קוד מדינה.
units

enum (Units)

אופציונלי. מציין את יחידות המידה של שדות התצוגה.
extraComputations[]

enum (ExtraComputation)

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

enum (TrafficModel)

אופציונלי. ההנחות שישמשו לחישוב הזמן בפקקים. ההגדרה הזו משפיעה על הערך שמוחזר בשדה duration ב-RouteMatrixElement, שמכיל את משך הזמן המשוער בתנועה על סמך ממוצעים היסטוריים. TrafficModel זמין רק לבקשות שבהן RoutingPreference מוגדר כ-TRAFFIC_AWARE_OPTIMAL ו-RouteTravelMode מוגדר כ-DRIVE. ברירת המחדל היא BEST_GUESS אם מבקשים נתוני תנועה ולא מציינים את הערך TrafficModel.
transitPreferences

object (TransitPreferences)

אופציונלי. העדפות שמשפיעות על המסלול שמוחזר למסלולים מסוג TRANSIT. הערה: אפשר לציין transitPreferences רק כשהערך של RouteTravelMode הוא TRANSIT.

גוף התשובה

מכיל מידע על מסלולים שחושבו עבור זוג מקור/יעד ב-API v2.computeRouteMatrix. אפשר להעביר את ה-proto הזה ללקוח בסטרימינג.

אם הפעולה מצליחה, גוף התגובה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "status": {
    object (Status)
  },
  "condition": enum (RouteMatrixElementCondition),
  "distanceMeters": integer,
  "duration": string,
  "staticDuration": string,
  "travelAdvisory": {
    object (RouteTravelAdvisory)
  },
  "fallbackInfo": {
    object (FallbackInfo)
  },
  "localizedValues": {
    object (LocalizedValues)
  },
  "originIndex": integer,
  "destinationIndex": integer
}
שדות
status

object (Status)

קוד סטטוס השגיאה של האלמנט הזה.
condition

enum (RouteMatrixElementCondition)

מציין אם המסלול נמצא או לא. ללא קשר לסטטוס.
distanceMeters

integer

מרחק הנסיעה במסלול, במטרים.
duration

string (Duration format)

משך הזמן הנדרש לנסיעה במסלול. אם מגדירים את routingPreference כ-TRAFFIC_UNAWARE, הערך הזה זהה ל-staticDuration. אם מגדירים את routingPreference לערך TRAFFIC_AWARE או TRAFFIC_AWARE_OPTIMAL, הערך הזה מחושב תוך התחשבות בתנאי התנועה.

משך זמן בשניות, עם עד תשע ספרות עשרוניות, שמסתיימים ב-'s'. דוגמה: "3.5s".
staticDuration

string (Duration format)

משך הנסיעה במסלול, בלי להביא בחשבון את מצב התנועה.

משך זמן בשניות, עם עד תשע ספרות עשרוניות, שמסתיימים ב-'s'. דוגמה: "3.5s".
travelAdvisory

object (RouteTravelAdvisory)

מידע נוסף על המסלול. לדוגמה: מידע על הגבלות ומידע על כבישי אגרה
fallbackInfo

object (FallbackInfo)

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

object (LocalizedValues)

ייצוגים של מאפיינים של RouteMatrixElement בטקסט.
originIndex

integer

אינדקס שמתחיל באפס של המקור בבקשה.
destinationIndex

integer

אינדקס מבוסס-אפס של היעד בבקשה.

RouteMatrixOrigin

מקור יחיד ל-ComputeRouteMatrixRequest

ייצוג ב-JSON 
{
  "waypoint": {
    object (Waypoint)
  },
  "routeModifiers": {
    object (RouteModifiers)
  }
}
שדות
waypoint

object (Waypoint)

חובה. ציון הדרך של המקור
routeModifiers

object (RouteModifiers)

אופציונלי. משתני אופן הגדרה לכל מסלול שמשתמש בזה כמקור

RouteMatrixDestination

יעד יחיד ל-ComputeRouteMatrixRequest

ייצוג ב-JSON 
{
  "waypoint": {
    object (Waypoint)
  }
}
שדות
waypoint

object (Waypoint)

חובה. ציון דרך ליעד

ExtraComputation

חישובים נוספים לביצוע במהלך השלמת הבקשה.

טיפוסים בני מנייה (enum)
EXTRA_COMPUTATION_UNSPECIFIED לא בשימוש. בקשות שמכילות את הערך הזה ייכשל.
TOLLS פרטי התשלום על כבישי אגרה של רכיבי המטריצה.

RouteMatrixElementCondition

התנאי של המסלול המוחזר.

טיפוסים בני מנייה (enum)
ROUTE_MATRIX_ELEMENT_CONDITION_UNSPECIFIED משמש רק כשהערך של status ברכיב לא תקין.
ROUTE_EXISTS נמצא מסלול והמידע התואם הוזן לאלמנט.
ROUTE_NOT_FOUND לא נמצא מסלול. שדות שמכילים פרטי מסלול, כמו distanceMeters או duration, לא ימולאו ברכיב.

LocalizedValues

ייצוגים של טקסט של נכסים מסוימים.

ייצוג ב-JSON 
{
  "distance": {
    object (LocalizedText)
  },
  "duration": {
    object (LocalizedText)
  },
  "staticDuration": {
    object (LocalizedText)
  },
  "transitFare": {
    object (LocalizedText)
  }
}
שדות
distance

object (LocalizedText)

מרחק הנסיעה שמוצג בטקסט.
duration

object (LocalizedText)

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

object (LocalizedText)

משך הנסיעה שמוצג בטקסט, בלי להביא בחשבון את תנאי התנועה.
transitFare

object (LocalizedText)

מחיר הנסיעה בתחבורה הציבורית שמוצג בטקסט.