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

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

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

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

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

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

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

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

בהמשך מוצגת התשובה המלאה לבקשת קידוד גיאוגרפי קדימה:

{
  "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.