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

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

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

אתם מציינים את רשימת השדות שאתם צריכים במסכת שדה תגובה. אחר כך מעבירים את מסכת שדות התגובה לכל אחת מהשיטות באמצעות פרמטר של כתובת 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 שמקושרים ברשימה הבאה. מציינים שדות בפורמט קאמל קייס כמו שמופיע בהפניה. לדוגמה, routePreference.

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

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

ב-method‏ computeRoutes של gRPC שמשמשת לחישוב מסלול, מגדירים משתנה שמכיל את מסכת שדות התגובה כדי להחזיר את השדות 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.