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

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

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

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

הגדרת מסכת שדות לתגובה

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

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

חיפוש מסכות שדות של יעדים

כשמפעילים את SearchDestinations, מציינים את מאפייני היעד המדויקים שצריך, כמו פרטי המקום הראשי, הכניסות, נקודות הניווט, קווי המתאר של הבניין (displayPolygon) וציוני הדרך:

curl -X POST -d '{"addressQuery": {"addressQuery": "1600 Amphitheatre Pkwy, Mountain View, CA"}}' \
-H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: destinations.primary.displayName,destinations.primary.displayPolygon,destinations.entrances,destinations.navigationPoints,destinations.landmarks' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/destinations

מסכות שדות ליבה של המרת כתובות לקואורדינטות (geocoding)

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

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.