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

قبل أن تتمكّن من بدء ترميز تطبيق العميل الأول، هناك بعض الإجراءات التي عليك اتّخاذها، إذا لم يسبق لك اتّخاذها.

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

لاستخدام Search Ads 360 API، تحتاج إلى حساب Google وأذونات مناسبة تم منحها لهذا الحساب من "إعلانات شبكة البحث 360":

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

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

   لتنزيل التقارير، يجب أن يكون لديك إذن عرض للمعلِنين الذين ستعمل معهم.

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

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

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

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

إنشاء مشروع على Google API Console وبيانات اعتماد OAuth لعميلك

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

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

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

تثبيت sa360Api.py

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

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

1. ثبِّت الإصدار 2.7 من Python.
   لا يعمل النص البرمجي مع 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. وتحدّد هذه السمة موردًا باستخدام معرّف موارد منتظم فريد عالميًا بالشكل التالي:

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

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

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

واجهة برمجة التطبيقات REST في Search Ads 360 API

تتمّ ربط عمليات Search Ads 360 API مباشرةً بأفعال REST HTTP.

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

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

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

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

في حال استخدام REST، عليك استخدام تنسيق JSON لنص الطلبات. يمكنك تحديد أن تكون الردود بتنسيق JSON أو CSV.

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