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

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

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

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

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

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

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