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