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

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

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

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

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

לעומת זאת, צריך להזין ערכים של פרמטרים כפי שמוצג. לדוגמה, עבור routingPreference, צריך להזין TRAFFIC_AWARE.

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

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

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

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

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

הערה: כשמתבצע ניתוח של הודעת תגובה, ושדה בהודעת התגובה מכיל את ערך ברירת המחדל שלו, יכול להיות שהשדה יושמט מהתגובה גם אם ציינתם אותו במסכת השדות של התגובה. מידע נוסף זמין במדריך השפה (proto3). לדוגמה, כשמחשבים מטריצת מסלולים, השדה distanceMeters בתגובה יכול להכיל את הערך 0, שהוא ערך ברירת המחדל שלו. מאחר ש-0 הוא ערך ברירת המחדל של distanceMeters, הוא לא מופיע בתגובה.

פרטים נוספים על בניית מסכת שדה זמינים ב-field_mask.proto.