Method: computeRouteMatrix

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

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

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

  • אנונימיזציה של שדות בכל השדות הזמינים (לבדיקה ידנית): 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)

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

  • הסכום של מספר המקורות ומספר היעדים שצוינו כ-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, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "2014-10-02T15:01:23Z" ו-"2014-10-02T15:01:23.045123456Z".
arrivalTime

string (Timestamp format)

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

חותמת זמן בפורמט "זולו" RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: "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.

גוף התשובה

מכילה מידע על המסלול שחושב עבור צמד מוצא/יעד ב-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

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

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

RouteMatrixElementCondition

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

טיפוסים בני מנייה (enums)
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)

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