Ad Manager REST API از ماسک‌های فیلد برای خواندن و نوشتن جزئی استفاده می‌کند. این می تواند عملکرد را با محدود کردن مقدار داده های منتقل شده بهبود بخشد. ماسک‌های فیلد با فهرستی از نام‌های فیلد جدا شده با کاما نشان داده می‌شوند. به عنوان مثال:
startTime,endTime,targeting.geoTargeting
ماسک ها را بخوانید
Read masks کنترل می کند که کدام فیلدها در یک پاسخ API وجود دارد. شما می توانید به دو روش یک ماسک خواندن را بر اساس درخواست خود تنظیم کنید:
پارامتر پرس و جو
fields:curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSizeهدر HTTP
X-Goog-FieldMask:curl -H "X-Goog-FieldMask: adUnits,nextPageToken,totalSize" \ https://admanager.googleapis.com/v1/networks/123456/adUnits
ماسک‌های خواندن پیش‌فرض
برخی از روش‌های API شامل یک فیلد ماسک پیش‌فرض برای فیلدهایی هستند که بازگرداندن آنها پرهزینه است. روش های لیست نمونه ای از این موارد است. به طور پیش فرض، آنها فیلد totalSize شامل نمی شوند.
این فیلدها باید به صراحت در فیلد ماسک یا با نام یا با استفاده از علامت * درخواست شوند.
ماسک ها را به روز کنید
ماسک‌های به‌روزرسانی کنترل می‌کنند که کدام فیلدها در درخواست به‌روزرسانی ( PATCH ) تغییر می‌کنند. وقتی یک ماسک به‌روزرسانی تنظیم می‌شود، صرف نظر از اینکه کدام فیلد در بدنه درخواست تنظیم شده است، فقط فیلدهای ماسک به‌روزرسانی می‌شوند.
ماسک های به روز رسانی به عنوان پارامترهای پرس و جو تنظیم می شوند. به عنوان مثال:
curl -X PATCH https://admanager.googleapis.com/v1/networks/1234/order/4567?updateMask=displayName
پیمایش میدانی
ماسک‌های فیلد می‌توانند فیلدهایی را در یک موجودیت با استفاده از . شخصیت برای پیمایش این همان نحوی است که فیلترها استفاده می کنند.
ماسک های فیلد همیشه نسبت به شی پاسخ هستند. برای مثال، یک ماسک برای خواندن یک LineItem ممکن است شامل primaryGoal.units باشد. ماسک مربوطه برای فهرست کردن LineItems lineItems.primaryGoal.units است.
شما می توانید یک فیلد را به عنوان یک کل یا یکی از زیرفیلدهای آن را مشخص کنید. هر دو primaryGoal و primaryGoal.units معتبر هستند.
این همچنین برای فیلدهای تکراری صدق می کند. یک ماسک فیلد LineItem از creativePlaceholders.size معتبر است و فقط شامل فیلد size برای هر CreativePlaceholder است.
عجایب
ماسک‌های فیلد از کاراکتر * پشتیبانی می‌کنند که همه فیلدهای پیام را نشان می‌دهد. مثال‌های زیر استفاده از حروف عام را هنگام فهرست‌بندی Orders نشان می‌دهند. این روش دارای یک ماسک خواندن پیش‌فرض است که فیلد total_size شامل نمی‌شود.
| مثال | معنی |
|---|---|
* | شامل تمام فیلدها، از جمله total_size |
orders | فقط شامل قسمت orders و تمام زیرفیلدهای آن می شود |
orders.* | فقط شامل قسمت orders و تمام زیرفیلدهای آن می شود |
فیلدهای نامعتبر
اگر یک فیلد ماسک به مقداری اشاره کند که وجود ندارد، API با یک خطای INVALID_ARGUMENT پاسخ خواهد داد.