تطبيقك الأول: المتطلبات الأساسية

إنشاء حساب على Google والحصول على أذونات "إعلانات شبكة البحث 360"

لاستخدام واجهة برمجة التطبيقات مع "إعلانات شبكة البحث 360"، تحتاج إلى حساب على Google وأذونات مناسبة يتم منحها لهذا الحساب من "إعلانات شبكة البحث 360":

1. إذا لم يكن لديك حساب على Google، يمكنك إنشاء حساب.

2. اطلب من مدير الوكالة في "إعلانات شبكة البحث 360" إنشاء حساب مستخدم على "إعلانات شبكة البحث 360" لحسابك على Google.

   لتنزيل التقارير، ستحتاج إلى إذن عرض للمعلنين الذين ستعمل معهم.

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

   يمكن لمدير الوكالة إعداد حسابك على أنه مستخدم مُعلِن له حق الوصول إلى معلنين محددين، أو إعداد حسابك بمستوى أعلى من الوصول مثل مستخدم الوكالة مع حق الوصول إلى جميع المعلنين في الوكالة.

تنشيط خدمة تحويل واجهة برمجة التطبيقات

إذا كنت ترغب في تحميل بيانات عن الإحالات الناجحة، يحتاج مستخدم "إعلانات شبكة البحث 360" الذي لديه امتيازات مدير الوكالة إلى تسجيل الدخول إلى واجهة مستخدم "إعلانات شبكة البحث 360" وتفعيل خدمة الإحالة الناجحة لواجهة برمجة التطبيقات. اطّلِع على مركز مساعدة "إعلانات شبكة البحث 360" للحصول على تعليمات.

إنشاء مشروع وحدة تحكم واجهة برمجة تطبيقات Google وبيانات اعتماد OAuth لعميلك

1. ابدأ تشغيل أداة إعداد وحدة تحكم واجهة برمجة تطبيقات Google.
   ترشدك أداة الإعداد خلال عملية إنشاء مشروع (أو استخدام مشروع حالي)، وتفعيل واجهة برمجة تطبيقات "إعلانات شبكة البحث 360" وإنشاء بيانات اعتماد OAuth 2.0.
2. في صفحة تسجيل تطبيقك، اختَر مشروعًا حاليًا أو اختَر إنشاء مشروع. وبعد ذلك، انقر على مواصلة.
3. بعد أن تفعّل وحدة تحكم واجهة برمجة تطبيقات Google واجهة برمجة تطبيقات "إعلانات شبكة البحث 360"، انقر على الزر الانتقال إلى بيانات الاعتماد.
4. في صفحة إنشاء بيانات اعتماد، أدخِل المعلومات التالية:
   • ما واجهة برمجة التطبيقات التي تستخدمها؟: واجهة برمجة تطبيقات "إعلانات شبكة البحث 360"
   • ما البيانات التي سيتم الوصول إليها؟: بيانات المستخدم
5. انقر على الزرّ التالي.

   تقدم أداة الإعداد الآن المساعدة في إنشاء معرِّف عميل OAuth 2.0.

6. اتبع بقية الخطوات في أداة الإعداد.

تثبيت sa360Api.py

تقدّم "إعلانات شبكة البحث 360" نصًا برمجيًا لأداة مساعدة لتسهيل عملية إعداد التفويض. يمكنك أيضًا استخدام هذا النص البرمجي لإرسال البيانات واستلامها بتنسيق JSON، إذا كنت تريد محاولة إرسال البيانات وتلقيها قبل تصميم تطبيق كامل وكتابته. يمكنك نسخ العديد من أمثلة JSON في موقع المستندات هذا وإدخالها مباشرة في النص البرمجي.

لتثبيت النص البرمجي:

1. تثبيت Python 2.7.
   لا يعمل النص البرمجي مع Python 3.x.
2. تثبيت cURL:
3. نزِّل sa360Api.zip.
4. استخراج sa360Api.py من sa360Api.zip.
5. جعل sa360Api.py قابلاً للتنفيذ.

التعرُّف على أساسيات REST

هناك طريقتان لاستدعاء واجهة برمجة التطبيقات:

• استخدام مكتبات العملاء.
• إرسال طلبات HTTP وتحليل الردود.

إذا قررت عدم استخدام مكتبات العملاء، ستحتاج إلى فهم أساسيات REST.

REST هو نمط لبنية البرامج التي توفر منهجًا مريحًا ومتسقًا لطلب البيانات وتعديلها.

يشير المصطلح REST إلى "نقل الولاية التمثيلية". في سياق Google APIs، يشير إلى استخدام أفعال HTTP لاسترداد تمثيلات البيانات المخزنة بواسطة Google وتعديلها.

في نظام RESTful، يتم تخزين الموارد في مخزن بيانات، ويرسل العميل طلبًا بأن ينفذ الخادم إجراءً معينًا (مثل إنشاء مورد، أو استرداده، أو تحديثه، أو حذفه)، وينفذ الخادم الإجراء ويرسل ردًا، وغالبًا ما يكون في صورة تمثيل للمورد المحدد.

في واجهات برمجة تطبيقات RESTful في Google، يحدِّد العميل إجراءً باستخدام فعل HTTP، مثل POST أو GET أو PUT أو DELETE. تحدد المورد موردًا من خلال معرف موارد منتظم (URI) فريد عالميًا للشكل التالي:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

ونظرًا لأن جميع موارد واجهة برمجة التطبيقات بها عناوين URL فريدة يمكن الدخول إليها عبر بروتوكول HTTP، فإن REST يُمكّن التخزين المؤقت للبيانات وتم تحسينه للعمل مع البنية الأساسية الموزعة على الويب.

قد تجد تعريفات الطريقة في مستندات معايير HTTP 1.1 مفيدة، حيث إنها تتضمن مواصفات GET وPOST وPUT وDELETE.

واجهة برمجة تطبيقات REST في "إعلانات شبكة البحث 360"

يتم ربط عمليات واجهة برمجة التطبيقات في "إعلانات شبكة البحث 360" مباشرةً بأفعال REST HTTP.

الشكل المحدّد لعناوين URL لواجهة برمجة التطبيقات في "إعلانات شبكة البحث 360" هو:

https://www.googleapis.com/doubleclicksearch/v2/resourcePath?parameters

يتم تلخيص المجموعة الكاملة من معرفات الموارد المنتظمة (URI) المستخدمة لكل عملية معتمدة في واجهة برمجة التطبيقات في مرجع واجهة برمجة التطبيقات.

التعرّف على أساسيات JSON

إذا كنت تستخدم REST، ستحتاج إلى استخدام تنسيق JSON لنصوص الطلبات. يمكنك تحديد أن تكون الردود بتنسيق JSON أو CSV.

JSON (JavaScript Object Notation) هو تنسيق شائع شائع لا يستند إلى اللغة ويقدّم تمثيلاً نصيًا بسيطًا لهياكل البيانات العشوائية. لمزيد من المعلومات، راجع json.org .