בחירת המידע שיוחזר

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

כדי לציין את רשימת השדות, יוצרים מסכת שדה תגובה. לאחר מכן מעבירים את המסכה של שדה התגובה לשיטה הרצויה באמצעות הפרמטר של כתובת ה-URL $fields או fields, או באמצעות הכותרת HTTP או gRPC X-Goog-FieldMask.

שימוש במסכת שדה הוא שיטה טובה לתכנון, שמאפשרת לוודא שאתם לא מבקשים נתונים מיותרים, וכך להימנע מזמן עיבוד מיותר וחיובים מיותרים.

מידע נוסף על פרמטרים של כתובות URL זמין במאמר פרמטרים מערכתיים.

הגדרת מסכת שדות תגובה

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

יוצרים נתיב שדה ומציינים אותו באופן הבא:

1. מחפשים את השדות שמכילים את המידע הדרוש מ-Routes API. פרטים נוספים זמינים במאמר הפניות לשדות.
2. מגדירים את הנתיבים לשדות הנדרשים ויוצרים את אנונימיזציית השדות שלהם: פרטים נוספים זמינים במאמר קביעת אנונימיזציית השדות שבה רוצים להשתמש.

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

   routes.legs.distanceMeters,routes.legs.steps.duration

4. שליחת מסכת השדות עם בקשת ה-API. לדוגמה, בבקשה של cURL, צריך לציין את אנונימיזציית השדות באמצעות -H ו-X-Goog-FieldMask:

   -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration

דוגמאות ופרטים נוספים זמינים בסעיפים הבאים.

הפניות לשדות

כדי לראות את השדות שאפשר לבקש בתגובה באמצעות מסכות שדות, אפשר לעיין במאמרי העזרה של Routes API שמקושרים ברשימה הבאה. מציינים את השדות באותיות רישיות באותיות רישיות, כפי שמופיע במסמך העזרה. לדוגמה, routePreference.

לעומת זאת, צריך להזין ערכים של פרמטרים כפי שמוצג. לדוגמה, עבור routingPreference, צריך להזין TRAFFIC_AWARE.

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

• מסכת שדה של מסלול ב-Compute
  • ‏REST: מציין את השדות של אובייקט Route בתגובה שתוחזר, עם הקידומת routes., לדוגמה routes.distanceMeters.
  • gRPC: מציין את השדות של אובייקט Route בתגובה שתוחזר.
• מסכות שדות של מטריצת מסלולים ב-Compute
  • REST: מציין את השדות של גוף התגובה שיוחזרו.
  • gRPC: מציין את השדות של האובייקט RouteMatrixElement בתגובה שתוחזר.

איך קובעים באילו מסכות שדות להשתמש

כך קובעים באילו שדות רוצים להשתמש ובונים את מסכות השדות שלהם:

1. מבקשים את כל השדות באמצעות מסכת שדה של *.
   זהירות: אפשר להשתמש במסכת השדה עם התו הכללי לחיפוש במהלך הפיתוח כדי לקבוע אילו שדות נחוצים לכם, אבל אל תשתמשו בה בסביבת הייצור. שליחת בקשה לכל השדות בסביבת הייצור גורמת לעלויות גבוהות יותר ולזמני מענה ארוכים יותר. בנוסף, העלות עשויה לעלות באופן בלתי צפוי ככל שיתווספו תכונות מתקדמות יותר, כי מסכת השדה הזו תכלול אותן באופן אוטומטי. במקום זאת, כדאי לבקש רק את השדות הנחוצים כדי לצמצם את העלויות ולקצר את זמן המענה.
2. בודקים את היררכיית השדות בתגובה בשביל השדות הרצויים.

3. יוצרים את מסכות השדות לפי היררכיית השדות שמוצגת בשלב הקודם, לפי הפורמט הזה:

   topLevelField[.secondLevelField][.thirdLevelField][...]

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

לדוגמה, בתגובה החלקית הזו ממסלול:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

אם רוצים להחזיר רק את השדה distanceMeters של מקטע המסלול, כלומר את distanceMeters האחרון בדוגמה הקודמת, מסכת השדה תהיה:

routes.legs.distanceMeters

אם במקום זאת רוצים להחזיר את השדה distanceMeters לכל שלב של מקטע המסלול, כלומר את distanceMeters שמתחת ל-steps בדוגמה הקודמת, מסכת השדה תהיה:

routes.legs.steps.distanceMeters

אם רוצים להחזיר את שניהם, עם התוצאה שלמעלה, מסכת השדה היא:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

דוגמאות לנתיבים של מסכות שדות

בקטע הזה מפורטות דוגמאות נוספות לאופן שבו מציינים נתיב שדה כחלק ממסכת שדה תגובה בקריאות REST ו-gRPC.

קריאה ל-REST אל computeRoutes

בדוגמה הראשונה, משתמשים בקריאת REST לשיטה computeRoutes כדי לחשב מסלול. בדוגמה הזו, בכותרת מציינים מסכות שדות כדי להחזיר את השדות distanceMeters ו-duration של המסלול בתגובה. חשוב לזכור להוסיף את הסימן routes כתחילית לשם השדה.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

קריאה ל-REST אל computeRouteMatrix

בשיטת ה-REST‏ computeRouteMatrix שמשמשת לחישוב של מטריצת מסלולים, מציינים בכותרת שצריך להחזיר את הערכים originIndex,‏ destinationIndex ו-duration לכל שילוב של מקור ויעד:

X-Goog-FieldMask: originIndex,destinationIndex,duration

קריאה ל-gRPC

ב-gRPC, מגדירים משתנה שמכיל את המסכה של שדה התשובה. לאחר מכן אפשר להעביר את המשתנה הזה לבקשה.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

שיקולים לגבי נתיב השדה

כדי להחזיר רק את השדות הנחוצים, צריך לכלול בתגובה רק את השדות הנחוצים:

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

הערה: כשמתבצע ניתוח של הודעת תגובה, ושדה בהודעת התגובה מכיל את ערך ברירת המחדל שלו, יכול להיות שהשדה יושמט מהתגובה גם אם ציינתם אותו במסכת השדות של התגובה. מידע נוסף זמין במדריך השפה (proto3). לדוגמה, כשמחשבים מטריצת מסלולים, השדה distanceMeters בתגובה יכול להכיל את הערך 0, שהוא ערך ברירת המחדל שלו. מאחר ש-0 הוא ערך ברירת המחדל של distanceMeters, הוא לא מופיע בתגובה.

פרטים נוספים על בניית מסכת שדה זמינים ב-field_mask.proto.

שליחת בקשה לטוקן מסלול

כדי לבקש מ-Routes API להחזיר אסימוני מסלולים למסלולים שנוצרו, פועלים לפי השלבים הבאים:

1. מגדירים את הפרמטרים הבאים הנדרשים להחזרת אסימון מסלול:
   • מגדירים את travelMode להיות DRIVE.
   • מגדירים את routingPreference לערך TRAFFIC_AWARE או TRAFFIC_AWARE_OPTIMAL.
2. בודקים שאף אחת מנקודות הדרך במסלול לא היא נקודת דרך מסוג via.
3. מציינים את אנונימיזציית השדה routes.routeToken כדי להחזיר אסימון מסלול:

   X-Goog-FieldMask: routes.routeToken

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

אפשר להשתמש באסימון המסלול של המסלול המתוכנן ב-Navigation SDK. פרטים נוספים זמינים במאמרים תכנון מסלול (Android) ותכנון מסלול (iOS).

דוגמה לטוקן מסלול

לפניכם דוגמה לגוף בקשה של cURL למסלול עם מקור יחיד ויעד יחיד, שבו נעשה שימוש במסכות שדות כדי לבקש אסימון מסלול, יחד עם משך המסלול, המרחק והקו הפוליגוני של המסלול:

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

מידע נוסף זמין במאמר הפניית API של Compute Routes.