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

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

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

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

ماسک فیلد پاسخ را تعریف کنید

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

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

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

توجه: در هیچ کجای لیست مسیرهای فیلد از فاصله استفاده نکنید.

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

احتیاط: در حالی که استفاده از این ماسک فیلد عام در توسعه مناسب است، از ماسک فیلد پاسخ علامت عام (*) در تولید استفاده نکنید. هزینه ممکن است بالاتر از حد انتظار باشد زیرا ویژگی های پیشرفته تری از طریق این فیلد ماسک درخواست می شود و تاخیر پاسخ را افزایش می دهد. مطمئن شوید که فقط فیلدهایی را درخواست می کنید که برای به حداقل رساندن هزینه ها و درخواست زمان پاسخ نیاز دارید.

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

تعیین کنید که از چه ماسک هایی استفاده کنید

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

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

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

جستجوی نزدیک (جدید) و جستجوی متن (جدید) آرایه‌ای از اشیاء مکان را در قسمت 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": "[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"
  }
  ...
}

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

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