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

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

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

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

מידע נוסף על פרמטרים של כתובות 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

הפניות לשדות

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

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

• מסכת שדה לחישוב מסלול
  • ‫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.