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

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

إنشاء مشروع جديد باستخدام Maven أو Gradle

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

تكون تبعية Maven على النحو التالي:

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

تكون تبعية Gradle على النحو التالي:

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

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

إذا كنت تنشئ التطبيق من المصدر، تأكَّد من تفعيل معالجة التعليقات التوضيحية في بيئة التطوير المتكاملة (IDE).

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

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

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

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

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

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

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

هناك نوعان من مسارات OAuth الشائعة الاستخدام، وهما تطبيقات سطح المكتب (المثبّتة) أو تطبيقات الويب. والفرق الرئيسي بينهما هو أنّ تطبيقات سطح المكتب يجب أن تفتح متصفح النظام وتوفّر معرّف موارد منتظمًا محليًا لإعادة التوجيه من أجل التعامل مع الردود الواردة من خادم تفويض 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

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

للتأكّد من إعداد كل شيء بشكل صحيح، سننفّذ مثال 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'