البدء

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

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

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

تبعية Maven هي:

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

تبعية Gradle هي:

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

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

للتأكّد من إعداد كل شيء بشكل صحيح، سنُطلق Getالحملات مثال.

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

مع قاعدة على المخطَّط:

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