تقدّم هذه الصفحة تفاصيل حول طريقة تنفيذ المهام الشائعة باستخدام واجهة برمجة التطبيقات.
إنشاء حسابات المستخدمين
تتيح UserService لمستخدم لديه حقوق المشرف إنشاء مستخدم مباشرةً في شبكته. يمكن لأي مطوّر إجراء ذلك بدون اشتراك المستخدم الجديد أولاً. على سبيل المثال، إذا كنت تجرّب واجهة برمجة التطبيقات للمرة الأولى، بدلاً من إجراء كل طلب بيانات من واجهة برمجة التطبيقات بصفتك مشرفًا (الإعداد التلقائي لعنوان بريدك الإلكتروني)، قد تحتاج إلى إنشاء عدد قليل من المستخدمين الذين لديهم أدوار، مثل مندوب مبيعات أو مسؤول نقل أو معلن لاختبار مهام سير العمل الفعلية.
- يمكنك إنشاء بعض عناوين Gmail الجديدة، مثل
my.name.dfp.salesperson@gmail.com. ويمكنك بدلاً من ذلك تسجيل عنوان حالي غير تابع لخدمة Gmail باعتباره حساب Google جديدًا. - يمكنك الاتصال بـ "
createUsers" باستخدام ذلك العنوان الجديد وعنوانRoleالذي تم اختياره. - يمكنك المصادقة بصفتك هذا المستخدم الجديد، باستخدام OAuth 2.0 لإنشاء رمز الدخول.
الحصول على الوحدة الإعلانية الجذرية
يعتمد كل من أعلى AdUnit الذي يمكنك إضافة عُقد فرعية إليه وعمق تدرجك الهرمي المسموح به على نوع حسابك (نشاط تجاري صغير أو مميّز). يُطلق على أعلى AdUnit يتيح تعديل العُقد الفرعية اسم الجذر الفعال AdUnit.
لاسترداد الجذر الفعّال، استدعِ NetworkService.getCurrentNetwork()، وافحص الحقل effectiveRootAdUnitId في الكائن Network الذي تم عرضه.
ملاحظة: تسمح أنواع الحسابات المختلفة بأنماط تدرّج هرمي مختلفة.
البحث عن كائن
يمكنك البحث عن العناصر حسب معايير البحث باستخدام طريقة getObjectsByStatement() التي تعرضها العديد من الخدمات، حيث يكون Object نوعًا محددًا من العناصر. تستخدم هذه الطريقة طلب بحث PQL، الذي يشبه طلب بحث SQL من حيث أنّه يتيح لك تحديد الحقول المطلوب البحث فيها (حيث يتم ربط أسماء الحقول بخصائص العنصر) وترتيب نتائج البحث وحصرها وإزاءها. يمكنك الاطّلاع على دليل
PQL لمزيد من المعلومات حول PQL، وعلى حقول العناصر التي يمكنك الفلترة حسبها.
إنشاء طلب
لإنشاء طلب، ما عليك سوى إنشاء عنصر Order وضبط أرقام تعريف المعلن
ومندوب المبيعات ومسؤولي الإعلانات للمستخدمين المناسبين، وتحديد اسم فريد
والاتصال بـ createOrders(). ستتضمّن النتيجة Order الذي تم إنشاؤه حديثًا، أو خطأ.
مثال
راجِع مثال رمز Java لإنشاء طلب.
إنشاء عنصر
في ما يلي خطوات إنشاء بند جديد:
- يمكنك إنشاء عنصر "
Order" جديد أو استخدام عنصر حالي. - أنشِئ عنصر
LineItemجديدًا، واضبط نوع التدوير، ومصفوفة حجم تصميم الإعلان، وتاريخَي البدء والانتهاء، وخصائص أخرى. - أنشِئ عنصر
InventoryTargetingجديدًا، وحدِّد كائناتPlacementأوAdUnitالتي تريد استهدافها أو استبعادها. - لف كائن
InventoryTargetingداخل كائنTargetingجديد، وخصِّصه لخاصية الاستهدافLineItem. - عليك استدعاء طريقة خدمة العنصر
createLineItems()مع العنصر الجديد، والتحقّق من النتيجة لمعرفة ما إذا تم إنشاء العنصر أم لا.
مثال
راجِع مثال رمز Java لإنشاء عنصر.
إنشاء تصميم إعلان
تتوافق الأنواع المختلفة من تصميمات الإعلانات مع مكونات مختلفة: على سبيل المثال، يتيح تصميم الإعلان
المصوّر استخدام ملف مصدر واحد للصورة، ويتوافق تصميم إعلان الفلاش مع ملفَي مواد عرض أساسيَّين: ملف فلاش وملف صورة احتياطية في حال تعذّر عرض ملف
الفلاش. بالنسبة إلى تصاميم الإعلانات المستضافة على مواقع إلكترونية تابعة لجهات خارجية، يجب تحميل
مقتطف HTML فقط يشير إلى الملف على الخادم التابع لجهة خارجية. اطّلع على الفئة الفرعية المحددة في Creative لمعرفة مواد العرض التي ستحتاج إلى تحميلها لإنشاء تصميم إعلانك.
مثال
راجِع مثال رمز JavaScript لإنشاء تصميم إعلان مصوّر.
تعديل كائن حالي
لتعديل عنصر حالي، ابحث عنه من خلال طلب getObjectsByStatement()،
وعدِّل القيم في العناصر المعروضة، ثم استدعِ updateObjects().
ملاحظة: ستحلّ العناصر المعدَّلة محلّ العناصر الحالية بالكامل، لذلك إذا تجاهلت ضبط قيمة للخاصية في العنصر الذي ترسله، سيحصل العنصر المحفوظ على القيمة التلقائية لتلك السمة، وليس القيمة السابقة.
تغيير حالة العنصر
يتم تغيير حالة العنصر من خلال استدعاء طريقة performObjectAction()
التي عرضتها الخدمة. تستخدم هذه الطريقة معلَمتَين:
- مثال لكائن الإجراء الذي يصف ما تريد تنفيذه. على سبيل المثال، تعرض خدمة الطلبات عدة إجراءات، من بينها
ApproveOrdersوPauseOrdersوArchiveOrders. تنشأ كائنات الإجراءات جميعها من فئة إجراء أساسي مناسبة لخدمتك. - طلب بحث PQL يصف العناصر التي يجب تغييرها ويمكنك تغيير حالة عنصر واحد أو أكثر في المرة الواحدة من خلال تحديد عبارة PQL مناسبة.
إنشاء علامات الإعلان
لا يمكنك إنشاء علامات الإعلانات باستخدام واجهة برمجة التطبيقات، بل عليك استخدام موقع "مدير إعلانات Google" الإلكتروني بدلاً من ذلك. راجِع قسم وضع العلامات في مركز المساعدة للحصول على مزيد من المعلومات.
مزيد من الأمثلة
يمكنك العثور على العديد من الأمثلة الأخرى في نموذج الرمز البرمجي الخاص بمكتبة البرامج، وبعدّة لغات برمجة مختلفة. راجِع صفحة مكتبات العملاء ومثال الرمز للحصول على رابط إلى أمثلة بلغة البرمجة.