בחירת שדות להחזרה

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

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

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

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

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

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

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

1. מאתרים את השדות שמכילים את המידע שאתם צריכים. פרטים נוספים זמינים במאמר בנושא הפניות לשדות.
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

הפניות לשדות

כדי לראות את השדות שאפשר לבקש בתשובה באמצעות מסכות שדות, אפשר לעיין בהפניות ל-Compute Routes או ל-Compute Route Matrix של Routes API שמקושרות ברשימה הבאה. מציינים שדות בפורמט CamelCase כמו שמופיע בהפניה. לדוגמה, routePreference.

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

• Compute route field mask
  • ‫REST: מציינים את השדות של אובייקט Route בתגובה שרוצים להחזיר, עם הקידומת routes.. לדוגמה, routes.distanceMeters.
  • ‫gRPC: מציין את השדות של אובייקט Route בתגובה שיוחזרו.
• Compute Route Matrix field masks
  • ‫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 method שמשמש לחישוב מטריצת מסלולים, בכותרת מציינים להחזיר את originIndex, destinationIndex ו-duration לכל שילוב של נקודת מוצא ויעד:

X-Goog-FieldMask: originIndex,destinationIndex,duration

שיחת gRPC אל computeRoutes

בשיטת gRPC‏ computeRoutes שמשמשת לחישוב מסלול, מגדירים משתנה שמכיל את מסכת השדות של התגובה כדי להחזיר את המסלול distanceMeters, את duration ואת השדות של הקו הפוליגוני המקודד בתגובה. אחר כך אפשר להעביר את המשתנה הזה לבקשה:

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

שיחת gRPC אל computeRouteMatrix

בשיטת gRPC‏ computeRouteMatrix שמשמשת לחישוב מטריצת מסלולים, מגדירים משתנה שמכיל את מסכת שדות התגובה כדי לציין את הערכים originIndex, destinationIndex ו-duration לכל שילוב של נקודת מוצא ויעד. אחר כך אפשר להעביר את המשתנה הזה לבקשה:

const (
  fieldMask = "originIndex,destinationIndex,duration"
)

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

כדי לקבל בתגובה רק את השדות שאתם צריכים, כוללים רק את השדות שאתם צריכים:

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

מידע נוסף על יצירת מסכת שדה זמין בקובץ field_mask.proto.