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

مقدمه

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

«جستجوی اطراف» (جدید) و «جستجوی نوشتاری» (جدید) آرایه‌ای از اشیای Place را در فیلد 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

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

Place Details (New)‎ یک شیء «مکان» را در این قالب برمی‌گرداند:

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