البدء

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

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

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

تبعية Maven هي:

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

تبعية Gradle هي:

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

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

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

يتطلب الوصول إلى Google Ads API بيانات اعتماد 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

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

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

أولاً، انتقِل إلى دليل 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 كوسيطة الوحيدة.

مع Gradle:

$ ./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'