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

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

מבוא

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

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

  • פרטי מקום (חדש) FieldMask
  • חיפוש בסביבה (חדש) FieldMask
  • פרמטרים של FieldMask בחיפוש טקסט (חדש)

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

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

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

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

יוצרים נתיב שדה באופן הבא:

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 יחיד בפורמט הבא:

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

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

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 יוסיף בעתיד עוד שדות תשובה, והשדות החדשים האלה ידרשו זמן חישוב נוסף. אם תבחרו את כל השדות, או אם תבחרו את כל השדות ברמה העליונה, יכול להיות שתחוו ירידה בביצועים כשכל השדות החדשים ייכללו אוטומטית בתשובה.
  • התוצאה היא גודל תגובה קטן יותר, מה שמוביל לתפוקה גבוהה יותר של הרשת.
  • מוודאים שלא תבקשו נתונים מיותרים, וכך תוכלו להימנע מזמן עיבוד מיותר ומחיובים מיותרים.