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

מפתחים באזור הכלכלי האירופי (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.