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

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

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

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

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

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

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

בנו נתיב לשדה באופן הבא:

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

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

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

למידע נוסף על יצירת מסכות של שדות, ראו field_mask.proto.

בחירת מסכות שדות לשימוש

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

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

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

 "routes": [
  {
    "legs": [
    {
      "distanceMeters": 12886,
    }
...
]}]

אם רוצים להחזיר רק את השדה distanceMeters, אנונימיזציה של שדות היא:

routes.legs.distanceMeters

דוגמה נוספת: כדי להחזיר בתשובה את כל מה שמופיע מתחת ל-legs, מסכת השדה היא:

routes.legs

ציון נתיב של שדה

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

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

שיחת REST אל computeRoutes

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

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

שיחת REST אל computeRouteMatrix

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

-H X-Goog-FieldMask: originIndex,destinationIndex,duration

קריאה ל-gRPC

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

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

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

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

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

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

בקשת אסימון מסלול

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

1. מגדירים את travel_mode להיות DRIVING.
2. הגדרה של routing_preference לערך 'TRAFFIC_AWARE' או 'TRAFFIC_AWARE_OPTIMAL'.
3. צריך לוודא שאף אחד מציוני הדרך במסלול אינו ציוני דרך של via.
4. מציינים את אנונימיזציה של שדות אסימון המסלול:

   -H X-Goog-FieldMask: routes.route_token

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

אתם יכולים להשתמש במסלול המתוכנן ב-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.route_token,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

לפרטים נוספים קראו את חומרי העזר של Compute Routes API.