تستخدم واجهة برمجة تطبيقات REST في "مدير الإعلانات" أقنعة الحقول لعمليات القراءة والكتابة الجزئية. يمكن أن تحسين الأداء من خلال الحد من كمية البيانات المنقولة. أقنعة الحقل يتم تمثيلها بقائمة من أسماء الحقول مفصولة بفواصل. على سبيل المثال:
startTime,endTime,targeting.geoTargeting
قراءة معلومات الأقنعة
تتحكّم أقنعة القراءة في الحقول المتوفّرة في ردّ واجهة برمجة التطبيقات. يمكنك ضبط اقرأ القناع عند طلبك بطريقتين:
معلَمة طلب البحث
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
أقنعة القراءة التلقائية
تتضمن بعض طرق واجهة برمجة التطبيقات قناع حقل تلقائيًا للحقول الباهظة الثمن
للرجوع. طرق القائمة هي مثال على ذلك. بشكل افتراضي، لا تتضمن
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 وكل حقوله الفرعية فقط. |
حقول غير صالحة
إذا كان قناع الحقل يشير إلى قيمة غير موجودة، ستجيب واجهة برمجة التطبيقات.
مع الخطأ INVALID_ARGUMENT.