Method: computeRouteMatrix

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

הערה: השיטה הזו מחייבת לציין אנונימיזציה של שדות תגובה בקלט. אפשר לספק את המסכה של שדות התגובה באמצעות הפרמטר $fields או fields של כתובת ה-URL, או באמצעות הכותרת 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.

גוף הבקשה

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

ייצוג 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 בכל מקרה.
  • המכפלה של מספר המקורות × מספר היעדים לא יכולה להיות גדולה מ-100 אם העדפת הניתוב מוגדרת ל-TRAFFIC_AWARE_OPTIMAL.
  • המכפלה של מספר המקורות כפול מספר היעדים לא יכולה להיות גדולה מ-100 אם הערך של TravelMode מוגדר ל-TRANSIT.
destinations[]

object (RouteMatrixDestination)

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

enum (RouteTravelMode)

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

enum (RoutingPreference)

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

string (Timestamp format)

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

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

string (Timestamp format)

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

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

string

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

string

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

enum (Units)

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

enum (ExtraComputation)

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

enum (TrafficModel)

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

מחיר הכרטיס לתחבורה הציבורית מיוצג בפורמט טקסט.