בחירת המידע שיוחזר
כששולחים קריאה ל-method לחישוב מטריצת מסלול או מסלול, צריך לציין איזה מידע רוצים על ידי הצגת השדות שיוחזרו בתשובה. אין רשימת ברירת מחדל של השדות שהוחזרו. אם משמיטים את הרשימה הזו, השיטות יחזירו שגיאה.
כדי לציין את רשימת השדות, יוצרים אנונימיזציה של שדות תשובה. לאחר מכן מעבירים את אנונימיזציה של שדות התגובה לכל method באמצעות הפרמטר $fields
או fields
של כתובת ה-URL, או באמצעות הכותרת X-Goog-FieldMask
של HTTP או gRPC.
כדאי להשתמש במסכת שדה כדי לוודא שלא תבקשו נתונים מיותרים, וכך תימנעו מזמן עיבוד ומחיובים מיותרים.
מידע נוסף על פרמטרים של כתובות URL מופיע במאמר פרמטרים של מערכת.
הגדרת אנונימיזציה של שדות תשובה
המסכה של שדות התשובה היא רשימה מופרדת בפסיקים של נתיבים, כאשר כל נתיב מציין שדה ייחודי בהודעת התשובה. הנתיב מתחיל מהודעת התשובה ברמה העליונה, וכולל נתיב לשדה שצוין שמופרד באמצעות נקודות.
בונים ומציינים נתיב של שדה באופן הבא:
- מחפשים את השדות שמכילים את המידע הנחוץ ב-Routes API. למידע נוסף, ראו הפניות לשדות.
- קובעים את הנתיבים לשדות הדרושים ויוצרים עבורם מסכות שדות: לפרטים נוספים, אפשר לעיין במאמר איך לקבוע באיזו מסכה של שדות להשתמש.
משלבים את מסכות השדות לכל השדות שנחוצים לכם, ומפרידים בין מסכות השדות באמצעות פסיקים. לדוגמה, כדי לבקש את המאפיין
distanceMeters
בשביל הקטע במסלול, וגם את משך הזמן של כל שלב במסלול, מזינים את שניהם, מופרדים בפסיקים, ללא רווחים:routes.legs.distanceMeters,routes.legs.steps.duration
שולחים את מסכת השדות עם בקשת ה-API. לדוגמה, בבקשת cURL, מציינים את מסכת השדות באמצעות
-H
ו-X-Goog-FieldMask
:-H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
הפניות לשדות
כדי לראות את השדות שאפשר לבקש בתשובה באמצעות מסכות של שדות, עיינו בהפניות של Routes API שמקושרות ברשימה הבאה. יש לציין שדות באותיות רישיות כפי שמוצג בהפניה. לדוגמה, routePreference
.
הפניות אלה כוללות את השדות הזמינים. עם זאת, עליכם להתייחס להיררכיה של השדות כדי לקבוע את נתיב המסיכות המלא של השדות. מידע נוסף על קבלת ההיררכיה של השדות מופיע במאמר איך לקבוע באיזו מסכה של שדות להשתמש.
- אנונימיזציה של שדות נתיב ב-Compute
- מסכות של שדות מטריצת מסלולים ב-Compute
- REST: מציין את השדות ב-Response body שצריך להחזיר.
- gRPC: מציין את השדות של האובייקט RouteMatrixElement בתגובה שיוחזר.
קביעה באילו מסכות של שדות להשתמש
כך קובעים באילו שדות רוצים להשתמש, ובונים עבורם מסיכות שדות:
- בקשה לכל השדות באמצעות מסכת שדות של
*
. - מביטים בהיררכיה של השדות בתשובה של השדות הרצויים.
יוצרים את מסכות השדות לפי ההיררכיה של השדות שהוצגו בשלב הקודם, בפורמט הבא:
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 ל-method computeRoutes
כדי לחשב מסלול. בדוגמה הזו, בכותרת מציינים מסכות של שדות כדי להחזיר את השדות של המסלול distanceMeters
ו-duration
בתשובה. חשוב לזכור להוסיף routes
לתחילת שם השדה.
X-Goog-FieldMask: routes.distanceMeters,routes.duration
הפעלת REST ל-computeRouteMatrix
ב-method computeRouteMatrix
של ה-REST שמשמשת לחישוב מטריצת מסלולים, צריך לציין בכותרת את האירוע originIndex
, destinationIndex
ו-duration
לכל שילוב של המקור והיעד:
X-Goog-FieldMask: originIndex,destinationIndex,duration
קריאה ל-gRPC
ב-gRPC, מגדירים משתנה שמכיל את המסכה של שדות התגובה. לאחר מכן תוכלו להעביר את המשתנה הזה לבקשה.
const ( fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline" )
שיקולים בנוגע בנתיב לשדה
צריך לכלול בתשובה רק את השדות שנדרשים כדי להחזיר רק את השדות הנדרשים:
- מקצר את זמני העיבוד, כך שהתוצאות מוחזרות עם זמן אחזור קצר יותר.
- מבטיח ביצועים יציבים בזמן האחזור. אם תבחרו את כל השדות, או אם תבחרו את כל השדות ברמה העליונה, יכול להיות שהביצועים לא יהיו איכותיים כשמוסיפים שדות חדשים ואז נכללים בתשובה באופן אוטומטי.
- התוצאות יהיו קטנות יותר, כלומר תפוקה גבוהה יותר ברשת.
- מבטיח שלא תבקשו נתונים מיותרים, וכך לחסוך זמן עיבוד וחיובים מיותרים.
לפרטים נוספים על בניית מסיכת שדות, עיינו במאמר field_mask.proto.
בקשה לאסימון מסלול
כדי לבקש מ-Routee API להחזיר אסימוני מסלול עבור מסלולים שנוצרו, פועלים לפי השלבים הבאים:
- מגדירים את הפרמטרים הבאים שנדרשים כדי להחזיר אסימון מסלול:
- מגדירים את
travelMode
להיותDRIVE
. - מגדירים את
routingPreference
להיותTRAFFIC_AWARE
אוTRAFFIC_AWARE_OPTIMAL
.
- מגדירים את
- צריך לוודא שאף אחת מנקודות הדרך במסלול לא עומדת על
via
ציוני דרך. - מציינים את מסכת השדות
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'
מידע נוסף מופיע במאמרי העזרה של Compute Routes API.