- בקשת HTTP
- גוף הבקשה
- גוף התשובה
- RouteMatrixOrigin
- RouteMatrixDestination
- ExtraComputation
- RouteMatrixElementCondition
- LocalizedValues (ערכים מקומיים)
מאחזרת רשימה של נקודות מוצא ויעדים ומחזירה זרם שמכיל מידע על המסלול לכל שילוב של מוצא ויעד.
הערה: השיטה הזו מחייבת לציין אנונימיזציה של שדה תגובה בקלט. אפשר לספק את האנונימיזציה של שדות התגובה באמצעות הפרמטר של כתובת האתר $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 ( |
שדות | |
---|---|
origins[] |
חובה. מערך מקורות, שקובע את השורות במטריצת התגובה. יש כמה הגבלות גודל שחלות על העוצמה של מקורות ויעדים:
|
destinations[] |
חובה. מערך של יעדים, שקובע את העמודות של מטריצת התגובות. |
travelMode |
זה שינוי אופציונלי. מציין את אמצעי התחבורה. |
routingPreference |
זה שינוי אופציונלי. מציין איך לחשב את המסלול. השרת מנסה להשתמש בהעדפת הניתוב שנבחרה כדי לחשב את המסלול. אם העדפת הניתוב גורמת לשגיאה או לזמן אחזור ארוך במיוחד, תוחזר שגיאה. אפשר לציין את האפשרות הזו רק אם הערך של |
departureTime |
זה שינוי אופציונלי. שעת היציאה. אם לא תגדירו את הערך הזה, ברירת המחדל תהיה השעה שבה שלחתם את הבקשה. הערה: אפשר לציין חותמת זמן בפורמט "זולו" RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: |
arrivalTime |
זה שינוי אופציונלי. שעת ההגעה. הערה: ניתן לקבוע רק אם המאפיין חותמת זמן בפורמט "זולו" RFC3339 UTC, עם רזולוציה של ננו-שנייה ועד תשע ספרות עשרוניות. דוגמאות: |
languageCode |
זה שינוי אופציונלי. קוד השפה BCP-47, למשל "en-US" או "sr-Latn". למידע נוסף ראו את המאמר מזהה מקומי ב-Unicode. ראו תמיכה בשפות כדי לקבל רשימה של השפות הנתמכות. אם לא מציינים את הערך הזה, שפת התצוגה מתבססת על המיקום של המקור הראשון. |
regionCode |
זה שינוי אופציונלי. קוד האזור, מצוין כ-ccTLD ("דומיין ברמה העליונה") בן שני תווים. למידע נוסף, ראה דומיינים ברמה העליונה עם קוד מדינה. |
units |
זה שינוי אופציונלי. מציין את יחידות המידה של שדות התצוגה. |
extraComputations[] |
זה שינוי אופציונלי. רשימה של חישובים נוספים שבהם ניתן להשתמש כדי להשלים את הבקשה. הערה: החישובים הנוספים האלה עלולים להחזיר שדות נוספים בתשובה. יש לציין גם את השדות הנוספים האלה באנונימיזציה של השדות כדי שיוחזרו בתגובה. |
trafficModel |
זה שינוי אופציונלי. מציין את ההנחות שיש להשתמש בהן בעת חישוב הזמן בתנועה. ההגדרה הזו משפיעה על הערך המוחזר בשדה משך הזמן ב- |
transitPreferences |
זה שינוי אופציונלי. המדיניות הזו מציינת העדפות שמשפיעות על המסלול שמוחזר למסלולים מסוג |
גוף התשובה
מכילה מידע על המסלול שחושב עבור צמד מוצא/יעד ב-v2.computeRouteMatrix API. ניתן לשדר את הפרוטו הזה ללקוח.
אם הפעולה בוצעה ללא שגיאות, גוף התשובה מכיל נתונים במבנה הבא:
ייצוג JSON |
---|
{ "status": { object ( |
שדות | |
---|---|
status |
קוד סטטוס שגיאה של רכיב זה. |
condition |
מציין אם המסלול נמצא או לא. ללא תלות בסטטוס. |
distanceMeters |
מרחק הנסיעה של המסלול, במטרים. |
duration |
משך הזמן הדרוש לניווט במסלול. אם תגדירו את משך זמן בשניות עם עד תשע ספרות עשרוניות, המסתיים ב-' |
staticDuration |
משך הנסיעה במסלול בלי להביא בחשבון את מצב התנועה. משך זמן בשניות עם עד תשע ספרות עשרוניות, המסתיים ב-' |
travelAdvisory |
מידע נוסף על המסלול. לדוגמה: מידע על ההגבלות ומידע על כבישי אגרה |
fallbackInfo |
במקרים מסוימים שבהם השרת לא יכול לחשב את המסלול עם ההעדפות הנתונות עבור צמד המוצא והיעד הספציפי הזה, ייתכן שהוא יחזור להשתמש במצב חישוב אחר. כשמשתמשים במצב חזרה, השדה הזה מכיל מידע מפורט על התגובה החלופית. אחרת, השדה הזה לא מוגדר. |
localizedValues |
ייצוגי טקסט של המאפיינים של |
originIndex |
אינדקס מבוסס אפס של המקור בבקשה. |
destinationIndex |
אינדקס מבוסס-אפס של היעד בבקשה. |
RouteMatrixOrigin
מקור יחיד של ComputeRouteMatrixRequest
ייצוג JSON |
---|
{ "waypoint": { object ( |
שדות | |
---|---|
waypoint |
חובה. ציון הדרך של נקודת המוצא |
routeModifiers |
זה שינוי אופציונלי. מגבילי התאמה בכל מסלול, שלוקחים את הנקודה הזו כמקור |
RouteMatrixDestination
יעד יחיד ל-ComputeRouteMatrixRequest
ייצוג JSON |
---|
{
"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 ( |
שדות | |
---|---|
distance |
מרחק הנסיעה מיוצג בפורמט טקסט. |
duration |
משך הזמן שמיוצג בפורמט טקסט תוך התחשבות בתנאי התנועה. הערה: אם לא נשלחה בקשה למידע על תנועה, הערך הזה יהיה זהה לערך של staticDuration. |
staticDuration |
משך הזמן שמיוצג בפורמט טקסט בלי להביא בחשבון את תנאי התנועה. |
transitFare |
תעריפים לתחבורה ציבורית מיוצגים בפורמט טקסט. |