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

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

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

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

• מסכת שדה של מסלול ב-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"
)

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

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

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

פרטים נוספים על בניית מסכת שדה זמינים ב-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.