فیلدهایی را برای بازگشت انتخاب کنید

مقدمه

وقتی متدهای Place Details (New) ، Nearby Search (New) یا Text Search (New) را فراخوانی می‌کنید، باید مشخص کنید که می‌خواهید کدام فیلدها در پاسخ برگردانده شوند. هیچ لیست پیش‌فرضی از فیلدهای برگردانده شده وجود ندارد. اگر این لیست را حذف کنید، متدها خطا برمی‌گردانند.

لیست کاملی از فیلدهای داده پشتیبانی شده و SKU های مربوط به آنها را می‌توانید در Place Data Fields (جدید) پیدا کنید. برای اطلاعات مربوط به فیلدهای مخصوص هر 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'

شیء پاسخ کامل از فراخوانی جستجوی متن (جدید) به شکل زیر است:

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

تعریف ماسک فیلد پاسخ برای جزئیات مکان (جدید)

جزئیات مکان (جدید) یک شیء مکان واحد را به شکل زیر برمی‌گرداند:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "types": [
    "locality",
    "political"
  ],
  "formattedAddress": "Trinidad, CA 95570, USA",
  "displayName": {
    "text": "Trinidad",
    "languageCode": "en"
  }
  ...
}

بنابراین، شما با مشخص کردن فیلدهای شیء Place که می‌خواهید برگردانید، یک ماسک فیلد برای این 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 در آینده فیلدهای پاسخ بیشتری اضافه کند و این فیلدهای جدید به زمان محاسبه بیشتری نیاز داشته باشند، عملکرد با تأخیر پایدار را تضمین می‌کند . اگر همه فیلدها را انتخاب کنید، یا اگر همه فیلدها را در سطح بالا انتخاب کنید، ممکن است وقتی همه فیلدهای جدید به طور خودکار در پاسخ شما گنجانده می‌شوند، با افت عملکرد مواجه شوید.
• منجر به اندازه پاسخ کوچکتر می‌شود که به معنای افزایش توان عملیاتی شبکه است.
• تضمین می‌کند که شما داده‌های غیرضروری درخواست نمی‌کنید ، که به جلوگیری از زمان پردازش غیرضروری و هزینه‌های اضافی کمک می‌کند.