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

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

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

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

האפשרות 'פרטי מקום' מחזירה אובייקט מקום יחיד בצורת:

{
  "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).