دليل البدء

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

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

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

تبعية Maven هي:

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

تبعية Gradle هي:

implementation 'com.google.api-ads:google-ads:29.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'