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

توسعه‌دهندگان منطقه اقتصادی اروپا (EEA)

مقدمه

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

فهرست کامل فیلدهای داده پشتیبانی‌شده و SKUهای مربوط به آن‌ها را می‌توانید در فیلدهای داده مکان (جدید) پیدا کنید. برای اطلاعات درباره فیلدهای مختص هر میانای برنامه‌سازی کاربردی، موارد زیر را ببینید:

  • پارامترهای FieldMask «جزئیات جا» (جدید)
  • پارامترهای FieldMask «جستجوی اطراف» (جدید)
  • پارامترهای FieldMask «جستجوی نوشتار (جدید)»

با ایجاد ماسک فیلد پاسخ، فهرست فیلد را مشخص می‌کنید. سپس ماسک فیلد پاسخ را بااستفاده از پارامتر $fields یا fields یا بااستفاده از سرصفحه HTTP یا gRPC X-Goog-FieldMask به یکی از روش‌ها ارسال می‌کنید.

ماسک کردن فیلد یک روش طراحی خوب است که تضمین می‌کند داده‌های غیرضروری درخواست نکنید، که این امر به جلوگیری از زمان پردازش غیرضروری و هزینه‌های صورت‌حساب کمک می‌کند.

تعریف پوشش فیلد پاسخ

ماسک فیلد پاسخ فهرستی از مسیرها است که با کاما از هم جدا شده‌اند و هر مسیر فیلد یکتایی را در بدنه پاسخ مشخص می‌کند. مسیر از پیام پاسخ سطح بالا شروع می‌شود و از مسیر جداشده با نقطه برای فیلد مشخص‌شده استفاده می‌کند.

مسیر فیلد را به‌صورت زیر بسازید:

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

می‌توانید همه فیلدها را بااستفاده از ماسک فیلد * درخواست کنید.

برای اطلاعات بیشتر درباره نحوه ساختن ماسک‌های فیلد، به field_mask.proto مراجعه کنید.

تعیین کنید از کدام ماسک‌های فیلد استفاده شود

در اینجا نحوه تعیین ماسک‌های فیلدی که می‌خواهید استفاده کنید آورده شده است:

  1. همه فیلدها را بااستفاده از ماسک فیلد * درخواست کنید.
  2. سلسله‌مراتب فیلدها را در پاسخ بررسی کنید و فیلدهای موردنظرتان را تعیین کنید.
  3. ماسک فیلدتان را بااستفاده از سلسله‌مراتب فیلد بسازید.

تعریف کردن پوشش فیلد پاسخ برای «جستجوی اطراف» (جدید) و «جستجوی نوشتار» (جدید)

«جستجوی اطراف» (جدید) و «جستجوی نوشتار» (جدید) آرایه‌ای از اشیای «مکان» را در فیلد places پاسخ برمی‌گردانند. برای این میاناهای برنامه‌سازی کاربردی، 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"
      },      ...
    },
  ...
  ]
}

بنابراین، برای این میاناهای برنامه‌سازی کاربردی، ماسک فیلد را در فرم مشخص می‌کنید:

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 مشخص می‌کنید:

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