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)

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

  • הסכום של מספר מקורות הנתונים + מספר היעדים שצוינו כ-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.

חותמת זמן בפורמט UTC "Zulu" של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
arrivalTime

string (Timestamp format)

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

חותמת זמן בפורמט UTC "Zulu" של RFC3339, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
languageCode

string

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

string

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

enum (Units)

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

enum (ExtraComputation)

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

enum (TrafficModel)

זה שינוי אופציונלי. ההנחות שישמשו לחישוב הזמן בפקקים. ההגדרה הזו משפיעה על הערך שמוחזר בשדה duration ב-RouteMatrixElement, שמכיל את משך הזמן המשוער בתנועה על סמך ממוצעים היסטוריים. 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 ברכיב הוא לא OK.
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)

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