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

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

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

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

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

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

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

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

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

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

הערה: אסור להשתמש ברווחים בשום מקום ברשימת נתיבי השדות.

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

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

מידע נוסף על בניית מסכות שדות זמין בקובץ 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'

אובייקט התגובה המלא מהקריאה Text Search (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": "[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 הזה, מציינים את השדות של אובייקט המקום שרוצים להחזיר:

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