دليل البدء

ننصحك باستخدام مكتبة البرامج مع Apache Maven (أو Gradle).

إنشاء مشروع Maven أو Gradle جديد

يمكنك إنشاء مشروع Maven أو Gradle جديد في بيئة تطوير متكاملة (IDE) من اختيارك. تم نشر العناصر الخاصة بنا في مستودع Maven المركزي.

تبعية Maven هي:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>31.0.0</version>
</dependency>

تبعية Gradle هي:

implementation 'com.google.api-ads:google-ads:31.0.0'

يمكنك أيضًا إنشاء المحتوى من المصدر. لغرض هذا الدليل، يُفترض أن لديك إعداد مشروع بالتبعيات المطلوبة المتاحة.

الحصول على بيانات الاعتماد للمصادقة باستخدام واجهة برمجة التطبيقات

يتطلب الوصول إلى واجهة برمجة التطبيقات مع "إعلانات Google" بيانات اعتماد OAuth ورمزًا مميزًا لمطوّر برامج Google Ads API. يشرح هذا القسم ماهية هذه العناصر وكيفية استخدامها وكيفية الحصول عليها.

الرمز المميز للمطوِّر (للوصول إلى واجهة برمجة التطبيقات)

يرتبط الرمز المميز للمطوِّر بحساب إداري ويمكن العثور عليه في واجهة "إعلانات Google" على الويب.

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

بيانات اعتماد OAuth (للوصول إلى حسابات "إعلانات Google")

للتفويض كمستخدمي حساب Google الذين يمكنهم الوصول إلى حسابات "إعلانات Google"، عليك توفير مجموعة من بيانات اعتماد OAuth.

يتوفّر مساران من OAuth يتم استخدامهما بشكل عام: تطبيق سطح المكتب (مثبَّت) أو تطبيق الويب. ويتمثّل الاختلاف الرئيسي بينهما في أنّه يجب أن تفتح تطبيقات الكمبيوتر المكتبي متصفّح النظام وتوفّر معرّف موارد منتظم (URI) لإعادة التوجيه على الجهاز للتعامل مع الاستجابات من خادم تفويض Google، في حين يمكن لتطبيقات الويب إعادة توجيه متصفّح تابع لجهة خارجية لإكمال عملية التفويض وإعادة إرسال بيانات الاعتماد إلى خادمك. تدعم المكتبة أيضًا تدفق حساب الخدمة الأقل استخدامًا.

في حال منح الإذن باستخدام بيانات الاعتماد الخاصة بك (مسار التطبيقات المتوافقة مع أجهزة سطح المكتب)

راجِع تدفق تطبيق OAuth المتوافق مع الكمبيوتر المكتبي. يشمل ذلك جميع التفاصيل التي تحتاج إليها للحصول على تفويض باستخدام بيانات اعتمادك الخاصة.

في حال تفويضك كمستخدم Google تابع لجهة خارجية (مسار على الويب)

راجِع مسار تطبيق الويب OAuth. يقدّم ذلك مثالاً على كيفية إعداد تفويض OAuth للمستخدمين العشوائيين التابعين لجهات خارجية.

في حال التفويض كمستخدم نطاق Google Apps (تدفق حساب الخدمة)

راجِع تدفق حساب خدمة OAuth. يقدم هذا مثالاً حول كيفية إعداد تفويض OAuth لمستخدمي نطاق Google Apps.

إذا كانت وصولك إلى حساب عميل "إعلانات Google" يتم من خلال حساب إداري على "إعلانات Google"، عليك أيضًا تحديد رقم تعريفي للعميل لتسجيل الدخول كما هو موضّح أدناه.

الرقم التعريفي لعميل تسجيل الدخول (للوصول إلى حسابات "إعلانات Google" من خلال حساب إداري)

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

إعداد مكتبة البرامج باستخدام بيانات الاعتماد

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

أنشئ ملفًا باسم ~/ads.properties يتضمّن المحتوى التالي:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_REFRESH_TOKEN_HERE
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE

استبدِل العناصر النائبة ببيانات الاعتماد التي حصلت عليها في الخطوة السابقة.

بالإضافة إلى ذلك، إذا كان الرمز المميّز لإعادة التحميل يتعلّق بحساب إداري، عليك تحديد الرقم التعريفي للعميل لهذا الحساب على أنّه العميل الذي يسجّل الدخول:

api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

التحقّق من صحة بيانات الاعتماد

للتأكّد من إعداد كل شيء بشكلٍ صحيح، سنعرض مثال Getحملات.

أولاً، انتقِل إلى الدليل google-ads-examples.

$ cd google-ads-examples

يتطلب هذا المثال معلمة --customerId حيث تكون القيمة هي الرقم التعريفي للعميل لحساب "إعلانات Google" بدون شرطات.

للتشغيل باستخدام Gradle:

$ ./gradlew -q runExample --example="basicoperations.GetCampaigns --customerId INSERT_CUSTOMER_ID_HERE"

الاطّلاع على أمثلة أخرى

تحتوي حزمة examples في google-ads-examples على عدة أمثلة مفيدة. تتطلب معظم الأمثلة معلمات. ويمكنك تمرير المعلَمات كوسيطات (إجراء يُنصح به) أو تعديل قيم INSERT_XXXXX_HERE في رمز المصدر. للاطّلاع على عبارة استخدام على سبيل المثال، استخدِم --help باعتبارها الوسيطة الوحيدة.

مع قاعدة على المخطَّط:

$ ./gradlew -q runExample --example="basicoperations.GetCampaigns --help"

ويمكنك أيضًا استخدام مهمة listExamples في Gradle لسرد جميع الأمثلة أو الأمثلة في دليل فرعي أو أمثلة حيث يتضمن الوصف عبارة بحث.

# List all examples:
$ ./gradlew -q listExamples
# List examples in the 'basicoperations' subdirectory:
$ ./gradlew -q listExamples --subdirectory='basicoperations'
# Search for examples where the description includes 'Performance Max':
$ ./gradlew -q listExamples --searchTerm='Performance Max'