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

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

מבוא

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

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

  • פרמטרים של FieldMask ב-Place Details (New)
  • פרמטרים של FieldMask בגרסה החדשה של "חיפוש בסביבה"
  • פרמטרים של FieldMask בחיפוש טקסט (חדש)

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

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

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

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

כך יוצרים נתיב שדה:

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

כדי לבקש את כל השדות, אפשר להשתמש במסכת שדות של *.

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

איך מחליטים באילו מסכות שדות להשתמש

כך קובעים באילו מסכות שדות להשתמש:

  1. מבקשים את כל השדות באמצעות מסכת שדות של *.
  2. בודקים את היררכיית השדות בתגובה ומחליטים אילו שדות רוצים.
  3. יוצרים את מסכת השדות באמצעות היררכיית השדות.

הגדרת מסכת שדות לתגובה בחיפוש בסביבה (חדש) ובחיפוש טקסט (חדש)

השיטות "חיפוש בסביבה (חדש)" ו"חיפוש טקסט (חדש)" מחזירות מערך של אובייקטים מסוג Place בשדה places של התגובה. בממשקי ה-API האלה, places הוא השדה ברמה העליונה של התגובה.

לדוגמה, כדי לראות את אובייקט התגובה המלא מחיפוש טקסט (חדש):

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: *' \
'https://places.googleapis.com/v1/places:searchText'

אובייקט התגובה המלא מקריאה ל-חיפוש טקסט (New) הוא בפורמט הבא:

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "+61 433 479 794",
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Spiced @ Barangaroo",
        "languageCode": "en"
      },      ...
    },
  ...
  ]
}

לכן, צריך לציין מסכת שדה לממשקי ה-API האלה בפורמט הבא:

places[.secondLevelField][.thirdLevelField][...]

אם רוצים להחזיר רק את השדות formattedAddress ו-displayName, מגדירים את מסכת השדות כך:

places.formattedAddress,places.displayName

אם מציינים את displayName, נכללים גם השדות text ו-language של displayName. אם רוצים רק את השדה text, מגדירים את מסכת השדות כך:

places.formattedAddress,places.displayName.text

הגדרת מסכת שדות לתגובה ב-Place Details (New)

השיטה Place Details (New) מחזירה אובייקט Place אחד בפורמט הבא:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

לכן, צריך לציין מסכת שדות ל-API הזה על ידי ציון השדות של האובייקט Place שרוצים להחזיר:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: formattedAddress,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

קריאת gRPC

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

const (
  fieldMask = "places.formattedAddress,places.displayName"
)

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

צריך לכלול בתגובה רק את השדות שאתם צריכים. החזרת השדות שאתם צריכים בלבד:

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