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 כתובה בתחביר של gRPC Transcoding.

גוף הבקשה

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

ייצוג ב-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.
  • בכל מקרה, המכפלה של מספר נקודות המוצא × מספר היעדים לא יכולה להיות גדולה מ-625.
  • אם הערך של routingPreference הוא TRAFFIC_AWARE_OPTIMAL, המכפלה של מספר נקודות המוצא × מספר היעדים לא יכולה להיות גדולה מ-100.
  • אם הערך של travelMode הוא TRANSIT, מכפלת מספר נקודות המוצא במספר נקודות היעד לא יכולה להיות גדולה מ-100.
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 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-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 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-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. מידע נוסף זמין במאמר Unicode Locale Identifier. כאן אפשר לעיין ברשימת השפות הנתמכות. אם לא תציינו את הערך הזה, שפת התצוגה תוסק מהמיקום של המקור הראשון.
regionCode

string

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

enum (Units)

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

enum (ExtraComputation)

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

enum (TrafficModel)

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

object (TransitPreferences)

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

גוף התשובה

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

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

ייצוג ב-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)

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