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

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

מבוא

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

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

  • פרטי מקום (חדש) FieldMask
  • חיפוש בסביבה (חדש) 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 אחד בפורמט הבא:

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