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

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

כדי לציין את רשימת השדות, יוצרים אנונימיזציה של שדות תשובה. לאחר מכן מעבירים את אנונימיזציה של שדות התגובה לכל method באמצעות הפרמטר $fields או fields של כתובת ה-URL, או באמצעות הכותרת 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: מציין את השדות של האובייקט Route בתגובה ל-Return, עם הקידומת routes., לדוגמה routes.distanceMeters.
  • gRPC: מציין את השדות של האובייקט Route בתגובה שיוחזר.
• מסכות של שדות מטריצת מסלולים ב-Compute
  • REST: מציין את השדות ב-Response body שצריך להחזיר.
  • 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 ל-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 להחזיר אסימוני מסלול עבור מסלולים שנוצרו, פועלים לפי השלבים הבאים:

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'

מידע נוסף מופיע במאמרי העזרה של Compute Routes API.