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

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

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

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

X-Goog-FieldMask: originIndex,destinationIndex,duration

קריאה ל-gRPC

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

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

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

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

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

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