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

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

כששולחים בקשה להמרת כתובות לקואורדינטות (geocoding), אפשר להשתמש במסכת שדות כדי לציין את רשימת השדות שיוחזרו בתגובה. בשיטות Geocode an address,‏ Geocode a location ו-Place geocoding, כל השדות באובייקט התגובה מוחזרים כברירת מחדל. בשיטה Search for destinations, צריך לציין מסכת שדות בבקשת ה-API.

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

הגדרת אנונימיזציה של שדות בתשובה

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

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

דוגמאות למסכות שדות

בהמשך מוצגת התשובה המלאה לבקשת המרת כתובות לקואורדינטות (geocoding) קדימה:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
    ...
}

יוצרים את מסכות השדות באמצעות ההיררכיה של שדות התגובה, בפורמט:

‫
topLevelField[.secondLevelField][.thirdLevelField][...]

לדוגמה, כדי להחזיר רק את השדה placeId בתגובה, משתמשים במסכת שדות:

curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://"geocode.googleapis.com/v4beta/"geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

התגובה עכשיו:

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE"
    }
  ]
}

כדי להחזיר את השדה viewport, האנונימיזציה של השדות היא:

-H 'X-Goog-FieldMask: results.viewport'

התגובה עכשיו:

{
  "results": [
    {
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

כדי להחזיר את שניהם:

-H 'X-Goog-FieldMask: results.placeId,results.viewport'

התגובה עכשיו:

{
  "results": [
    {
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "viewport": {
        "low": {
          "latitude": 37.420654569708496,
          "longitude": -122.08547618029148
        },
        "high": {
          "latitude": 37.423352530291496,
          "longitude": -122.0827782197085
        }
      }
    }
  ]
}

אנונימיזציה של שדות ב-gRPC

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

const (
  fieldMask = "results.placeId,results.viewport"
)

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

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

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

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