الإرشادات

توفّر هذه الصفحة تفاصيل حول كيفية تنفيذ المهام الشائعة باستخدام واجهة برمجة التطبيقات.

إنشاء مستخدمين

تسمح UserService مستخدم لديه حقوق المشرف لإنشاء مستخدم مباشرةً في شبكته. يمكن لأي مطور القيام بذلك دون جعل المستخدم الجديد يشترك أولاً. على سبيل المثال، إذا كنت تجرب واجهة برمجة التطبيقات للمرة الأولى، بدلاً من إجراء كل طلب بيانات من واجهة برمجة التطبيقات بصفتك مشرفًا (الإعداد التلقائي لعنوان بريدك الإلكتروني)، فقد ترغب في إنشاء بعض المستخدمين بأدوار مثل مندوب مبيعات أو مسؤول إعلانات أو معلن لاختبار سير العمل في العالم الحقيقي

1. أنشئ بعض عناوين Gmail الجديدة مثل [e-mail]. بدلاً من ذلك، تسجيل عنوان حالي غير تابع لخدمة Gmail كعنوان جديد حساب Google.
2. يمكنك الاتصال بالرقم createUsers باستخدام هذا العنوان الجديد وعنوان البريد الإلكتروني Role الذي تم اختياره.
3. يمكنك المصادقة بصفتك هذا المستخدم الجديد، باستخدام OAuth 2.0 لإنشاء رمز الدخول.

الحصول على الوحدة الإعلانية الجذر

يعتمد كلّ من أعلى AdUnit يمكنك إضافة عُقد فرعية إليه والعمق المسموح به في التدرّج الهرمي على نوع حسابك (نشاط تجاري صغير أو Premium). الجزء العلوي من AdUnit الذي يتيح تعديل العُقد الفرعية يُطلق على الجذر الفعّال AdUnit.

لاسترداد الجذر الفعّال، عليك استدعاء NetworkService.getCurrentNetwork() وفحص الحقل effectiveRootAdUnitId في كائن Network الذي تم عرضه.

ملاحظة: تتيح أنواع الحسابات المختلفة أنماط التدرّج الهرمي المختلفة.

طلب البحث عن كائن

البحث عن العناصر حسب معايير البحث باستخدام الطريقة getObjectsByStatement() يعرضها العديد من الخدمات، حيث يكون Object نوعًا محددًا من الكائنات. هذا النمط استعلام PQL، وهو مشابه لاستعلام SQL من حيث إنه يتيح لك تحديد للبحث فيها (حيث يتم تعيين أسماء الحقول للخصائص الموجودة على الكائن)، والفرز، والحد من نتائج البحث والاقتطاع منها. الاطّلاع على PQL دليل للاطّلاع على مزيد من المعلومات حول PQL، ومعرفة حقول الكائنات التي يمكنك استخدامها الفلترة حسبها.

إنشاء طلب

لإنشاء طلب، ما عليك سوى إنشاء عنصر Order وتحديد المعلِن، ومعرفات مندوبي المبيعات ومسئولي الإعلانات للمستخدمين المناسبين، وقم بتعيين اسم فريد، واتصل بـ createOrders(). وستتضمّن النتيجة دالة Order التي تم إنشاؤها حديثًا أو خطأ.

مثال

راجِع مثال رمز Java لإنشاء طلب.

إنشاء عنصر

في ما يلي خطوات إنشاء بند جديد:

1. أنشِئ عنصر Order جديدًا أو استخدِم عنصرًا حاليًا.
2. أنشِئ عنصر LineItem جديدًا، واضبط نوع عرض الإعلانات بالتناوب، ومصفوفة حجم تصميم الإعلان، وتواريخ البدء والانتهاء والخصائص الأخرى.
3. أنشِئ كائن InventoryTargeting جديدًا وحدِّد العنصر Placement أو AdUnit الذي تريد استهدافه أو استبعاده.
4. التفاف عنصر InventoryTargeting داخل عنصر Targeting جديد وتعيينه إلى خاصية الاستهداف LineItem.
5. استدعِ طريقة خدمة العناصر createLineItems() باستخدام العنصر الجديد، وافحص النتيجة لمعرفة ما إذا كان قد تم إنشاء العنصر أم لا.

مثال

يمكنك الاطّلاع على مثال رمز Java لإنشاء عنصر.

إنشاء تصميم إعلان

تتوافق الأنواع المختلفة من تصميمات الإعلانات مع مكونات مختلفة: على سبيل المثال، صورة أن يتيح تصميم الإعلان ملف مصدر واحد للصورة يدعم إعلان الفلاش ملفي الأصول الأساسيين: ملف فلاش وملف صورة احتياطية، في حال كان ملف الفلاش لا يمكن عرض الملف. بالنسبة إلى تصميمات الإعلانات المستضافة على مواقع إلكترونية تابعة لجهات خارجية، ستقوم بتحميل فقط مقتطف HTML الذي يشير إلى الملف على الخادم التابع للجهة الخارجية. اطّلِع على فئة فرعية محددة من Creative لمعرفة مواد العرض التي يجب تحميلها لإنشاء تصميم الإعلان الخاص بك

مثال

اطّلِع على مثال رمز Java لإنشاء تصميم إعلان مصوَّر.

تعديل عنصر حالي

لتعديل عنصر حالي، يمكنك البحث عنه من خلال طلب getObjectsByStatement(). لتعديل القيم في الكائنات التي تم إرجاعها، ثم استدعاء updateObjects().

ملاحظة: ستحلّ العناصر المعدَّلة محلّ العناصر الحالية بالكامل، لذلك إذا إهمال تعيين قيمة خاصية في الكائن الذي ترسله، فإن الكائن المحفوظ نحصل على القيمة التلقائية لتلك الخاصية، وليس القيمة السابقة.

تغيير حالة العنصر

يتم تغيير حالة العنصر من خلال استدعاء طريقة performObjectAction() الكشف عنها من خلال خدمتك. تستخدم هذه الطريقة معلمتين:

• مثال لكائن الإجراء الذي يصف ما تريد تنفيذه بالنسبة مثلاً، تعرض خدمة الطلب عدة إجراءات من بينها ApproveOrders وPauseOrders وArchiveOrders. يتم اشتقاق كائنات الحركة من إجراء أساسي الفئة المناسبة لخدمتك.
• طلب بحث PQL يصف الكائنات المطلوب تغييرها يمكنك تغيير حالة عنصر واحد أو أكثر في المرة الواحدة من خلال تحديد جدول بيانات مناسب الشخصي.

إنشاء علامات الإعلان

لا يمكنك إنشاء علامات الإعلانات باستخدام واجهة برمجة التطبيقات. وبدلاً من ذلك، عليك استخدام موقع "مدير إعلانات Google" الإلكتروني اطّلِع على مقالة وضع العلامات قسم مركز المساعدة عن مزيد من المعلومات.

مزيد من الأمثلة

يمكنك العثور على العديد من الأمثلة الإضافية في نموذج رمز مكتبة العملاء الخاص بنا، بعدة لغات برمجة مختلفة. راجع مكتبات العميل مثال التعليمة البرمجية للحصول على رابط لأمثلة بلغة البرمجة الخاصة بك.