البدء

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

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

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

إن تبعية Maven هي:

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

إن تبعية Gradle هي:

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

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

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

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

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

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

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

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

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

استكشاف أمثلة أخرى

تحتوي حزمة الأمثلة في 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'