أقنعة الحقل

تستخدم واجهة برمجة تطبيقات REST في "مدير الإعلانات" أقنعة الحقول لعمليات القراءة والكتابة الجزئية. يمكن أن تحسين الأداء من خلال الحد من كمية البيانات المنقولة. أقنعة الحقل يتم تمثيلها بقائمة من أسماء الحقول مفصولة بفواصل. على سبيل المثال:

startTime,endTime,targeting.geoTargeting

قراءة معلومات الأقنعة

تتحكّم أقنعة القراءة في الحقول المتوفّرة في ردّ واجهة برمجة التطبيقات. يمكنك ضبط اقرأ القناع عند طلبك بطريقتين:

1. معلَمة طلب البحث fields:

   curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSize
   

2. عنوان HTTP يتضمّن العنصر X-Goog-FieldMask:

   curl -H "X-Goog-FieldMask: adUnits,nextPageToken,totalSize" \
       https://admanager.googleapis.com/v1/networks/123456/adUnits
   

ملاحظة: يمكن استخدام كل من camelCase وsnake_case في سلاسل أقنعة الحقول.

أقنعة القراءة التلقائية

تتضمن بعض طرق واجهة برمجة التطبيقات قناع حقل تلقائيًا للحقول الباهظة الثمن للرجوع. طرق القائمة هي مثال على ذلك. بشكل افتراضي، لا تتضمن 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.

ملاحظة: لا تسمح أقنعة الحقول بالوصول إلى عنصر معين من عناصر الحقل حسب الفهرس. يؤدي ذلك إلى ظهور خطأ INVALID_ARGUMENT.

أحرف البدل

تحذير: لا يتوافق استخدام حرف بدل في قناع التحديث مع عملية إعادة التوجيه. تشير رسالة الأشكال البيانية سيمحو حرف البدل أي حقول غير معروفة لعميلك.

تتيح أقنعة الحقول استخدام الحرف * الذي يشير إلى جميع الحقول في الرسالة. توضح الأمثلة التالية استخدام حرف البدل عند إدراج Orders وتتضمن هذه الطريقة قناع قراءة تلقائي عدم تضمين الحقل total_size.

مثال	المعنى
*	تتضمّن جميع الحقول، بما في ذلك total_size
orders	يتضمّن الحقل orders وكل حقوله الفرعية فقط.
orders.*	يتضمّن الحقل orders وكل حقوله الفرعية فقط.

حقول غير صالحة

إذا كان قناع الحقل يشير إلى قيمة غير موجودة، ستجيب واجهة برمجة التطبيقات. مع الخطأ INVALID_ARGUMENT.