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

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

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