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

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

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

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

מידע נוסף על פרמטרים של כתובות 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: מציין את השדות נתב את האובייקט בתוך תגובה ל-Return, בקידומת routes., לדוגמה, routes.distanceMeters
  • gRPC: מציין את השדות נתב את האובייקט בתוך תגובה ל'חזרה'.
• מסכות שדות של מטריצת מסלולים ב-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.