الخطوات الأولى

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

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

أنشئ مشروع Maven/Gradle جديدًا في بيئة تطوير البرامج المتكاملة التي تختارها. يتم نشر العناصر في مستودع Maven central.

تبعية Maven هي:

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

تبعية Gradle هي:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ملاحظة: يمكن لمستخدم Google الوصول إلى العديد من حسابات "إعلانات Google".

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

ضبط مكتبة العميل باستخدام بيانات الاعتماد

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

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

أنشئ ملفًا ~/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

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

للتأكّد من أنّ كلّ شيء تم إعداده بشكل صحيح، سننفّذ مثال GetCampaigns.

أولاً، انتقِل إلى الدليل 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'

ملاحظة: من رمز المصدر، يمكنك تجاهل التعليقات التي تحتوي على [START...] و [END...]، لأنّ Google تستخدمها على وجه التحديد.