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

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

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

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

ننصحك باستخدام قائمة المواد (BOM) في Google Ads API لإدارة إصدارات التبعيات. وهذه هي أفضل طريقة لتجنُّب تعارضات التبعية مع مكتبات مثل Guava وGAX التي تستخدمها أيضًا أُطر أخرى. تضمن قائمة BOM استخدام الإصدارات المحدّدة من هذه التبعيات التي تم اختبارها مع مكتبة عملاء "إعلانات Google".

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

<!-- Import the Bill of Materials (BOM) to ensure you're using compatible
     versions of all google-ads libraries. -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.api-ads</groupId>
      <artifactId>google-ads-bom</artifactId>
      <version>40.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<!-- Add the google-ads dependency, without a version. The version is
     managed by the BOM. -->
<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
</dependency>

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

// Import the Bill of Materials (BOM).
implementation platform('com.google.api-ads:google-ads-bom:40.0.0')

// Add the google-ads dependency, without a version.
implementation 'com.google.api-ads:google-ads'

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

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

تحديد الاعتماديات التي يغطيها بيان المواد

يتضمّن مستند مواد البناء لواجهة برمجة التطبيقات Google Ads API إدارة الإصدارات للعديد من المكتبات الشائعة، مثل Guava وProtobuf وGAX وgRPC. لتجنُّب حدوث تعارضات محتملة في الاعتماديات، يجب عدم تحديد إصدار عند تعريف الاعتماديات التي تغطيها قائمة مواد الإنشاء. تتولّى قائمة BOM إدارة إصدارات هذه المكتبات تلقائيًا، ما يضمن التوافق.

على سبيل المثال، للإعلان عن اعتمادية Guava في Maven، استخدِم ما يلي:

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava</artifactId>
  <!-- NO VERSION SPECIFIED -->
</dependency>

وفي Gradle:

implementation 'com.google.guava:guava' // NO VERSION SPECIFIED

من خلال حذف رقم الإصدار، يمكنك السماح لقائمة مواد البناء بإدارته، ما يساعد في منع حدوث مشاكل ناتجة عن إصدارات غير متوافقة من التبعيات. تشمل المؤشرات الشائعة لتضارب التبعيات NoSuchMethodError أو ClassNotFoundException، ويمكن غالبًا حلّها من خلال التأكّد من عدم تحديد أي إصدار لجميع التبعيات المُدارة في قائمة المواد.

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

تتطلّب إمكانية الوصول إلى 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" من خلال حساب إداري)

ملاحظة: يمكن لمستخدم 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.