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

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

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

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

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

הגדרת אנונימיזציה של שדות תשובה

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

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

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.

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

כדי לבקש מ-Routee 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.