وقتی روشهای جزئیات مکان (جدید) ، جستجوی نزدیک (جدید) ، یا جستجوی متن (جدید) را فرا میخوانید، باید مشخص کنید که کدام قسمتها را میخواهید در پاسخ بازگردانید. هیچ لیست پیش فرضی از فیلدهای برگشتی وجود ندارد. اگر این لیست را حذف کنید، متدها با خطا مواجه می شوند.
شما با ایجاد یک ماسک فیلد پاسخ، لیست فیلد را مشخص می کنید. سپس ماسک فیلد پاسخ را با استفاده از پارامتر $fields
یا fields
، یا با استفاده از هدر HTTP یا X-Goog-FieldMask
به هر یک از روشها ارسال میکنید.
پوشاندن میدان یک روش طراحی خوب برای اطمینان از عدم درخواست دادههای غیرضروری است که به جلوگیری از زمان پردازش غیرضروری و هزینههای صورتحساب کمک میکند.
ماسک فیلد پاسخ را تعریف کنید
ماسک فیلد پاسخ، لیستی از مسیرها است که با کاما از هم جدا شدهاند، که در آن هر مسیر یک فیلد منحصر به فرد را در پیام پاسخ مشخص میکند. مسیر از پیام پاسخ سطح بالا شروع می شود و از یک مسیر جدا شده با نقطه به فیلد مشخص شده استفاده می کند.
یک مسیر فیلد به صورت زیر بسازید:
topLevelField[.secondLevelField][.thirdLevelField][...]
با استفاده از یک فیلد ماسک *
می توانید همه فیلدها را درخواست کنید.
برای اطلاعات بیشتر در مورد نحوه ساخت فیلد ماسک، به field_mask.proto مراجعه کنید.
تعیین کنید که از چه ماسک هایی استفاده کنید
در اینجا نحوه تعیین فیلد ماسک هایی که می خواهید استفاده کنید آمده است:
- تمام فیلدها را با استفاده از یک فیلد ماسک «*» درخواست کنید.
- به سلسله مراتب فیلدها در پاسخ نگاه کنید و تعیین کنید چه فیلدهایی را می خواهید.
- ماسک فیلد خود را با استفاده از سلسله مراتب فیلد بسازید.
یک ماسک فیلد پاسخ برای جستجوی نزدیک (جدید) و جستجوی متن (جدید) تعریف کنید
جستجوی نزدیک (جدید) و جستجوی متن (جدید) آرایهای از اشیاء مکان را در قسمت 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
ماسک فیلد پاسخ را برای جزئیات مکان تعریف کنید (جدید)
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 فیلدهای پاسخ بیشتری را در آینده اضافه کند و آن فیلدهای جدید به زمان محاسبات اضافی نیاز داشته باشند، عملکرد تأخیر پایدار را تضمین می کند . اگر همه فیلدها را انتخاب کنید، یا اگر همه فیلدها را در سطح بالا انتخاب کنید، ممکن است زمانی که همه فیلدهای جدید به طور خودکار در پاسخ شما گنجانده شوند، کاهش عملکرد را تجربه کنید.
- منجر به اندازه پاسخ کوچکتر می شود که به توان عملیاتی شبکه بالاتر تبدیل می شود.
- اطمینان حاصل می کند که داده های غیر ضروری را درخواست نمی کنید ، که به جلوگیری از زمان پردازش غیر ضروری و هزینه های صورتحساب کمک می کند.