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

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

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

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

{
  "places": [
    {
      "name": "places/ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "id": "ChIJs5ydyTiuEmsR0fRSlU0C7k0",
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "meal_takeaway",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "nationalPhoneNumber": "0433 479 794",
      "internationalPhoneNumber": "[phone]",
      "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 מחזיר אובייקט 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 יוסיף עוד שדות תגובה בעתיד ושדות החדשים ידרשו זמן חישוב נוסף. אם תבחרו את כל השדות או אם תבחרו את כל השדות ברמה העליונה, יכול להיות שהביצועים של כל השדות החדשים ייפגעו כשכל השדות החדשים ייכללו בתשובה באופן אוטומטי.
• התוצאות יהיו קטנות יותר, כלומר תפוקה גבוהה יותר ברשת.
• מבטיחה שלא תבקשו נתונים מיותרים, וכך למנוע זמן עיבוד מיותר וחיובים מיותרים.

הערה: כשמנתחים הודעת תשובה, ושדה בהודעת התשובה מכיל את ערך ברירת המחדל שלה, יכול להיות שהשדה יושמט מהתשובה גם אם ציינתם אותו במסכה של שדות התשובה. למידע נוסף, עיינו במדריך השפה (proto3).