מפתחים באזור הכלכלי האירופי (EEA)

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

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

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

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

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

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

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

• 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"
)

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

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

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

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

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