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

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

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

מבוא

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

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

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

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

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

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

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

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

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

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

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

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

מידע נוסף על בניית מסכות שדות זמין ב-field_mask.proto.

קובעים באילו מסכות שדות להשתמש

כך קובעים באילו מסכות שדות רוצים להשתמש:

1. שליחת בקשה לכל השדות באמצעות מסכת שדות של *.
2. בודקים את ההיררכיה של השדות בתגובה ומחליטים אילו שדות רוצים.
3. יוצרים את מסכת השדות באמצעות היררכיית השדות.

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

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

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