شروع شدن

توصیه می کنیم از کتابخانه مشتری با Apache Maven یا Gradle استفاده کنید.

یک پروژه Maven/Gradle جدید ایجاد کنید

یک پروژه Maven یا Gradle جدید در IDE مورد نظر خود ایجاد کنید. مصنوعات ما در مخزن مرکزی Maven منتشر می شوند.

توصیه می‌کنیم برای مدیریت نسخه‌های وابستگی از Google Ads API's Bill of Materials (BOM) استفاده کنید. این بهترین راه برای جلوگیری از تضاد وابستگی با کتابخانه‌هایی مانند Guava و GAX است که توسط سایر چارچوب‌ها نیز استفاده می‌شوند. BOM تضمین می‌کند که از نسخه‌های دقیق این وابستگی‌ها استفاده می‌کنید که با کتابخانه مشتری Google Ads آزمایش شده‌اند.

وابستگی 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 خود فعال کرده‌اید.

اعلام وابستگی های تحت پوشش BOM

Google Ads API BOM شامل مدیریت نسخه برای چندین کتابخانه رایج، مانند Guava ، Protobuf ، GAX و gRPC است. برای جلوگیری از تداخل احتمالی وابستگی، هنگام اعلام وابستگی هایی که BOM پوشش می دهد، نباید نسخه ای را مشخص کنید. 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

با حذف نسخه، به BOM اجازه می دهید آن را مدیریت کند، که به جلوگیری از مشکلات ناشی از نسخه های وابستگی ناسازگار کمک می کند. شاخص‌های متداول تعارض‌های وابستگی شامل NoSuchMethodError یا ClassNotFoundException است که اغلب می‌توان با اطمینان از اینکه تمام وابستگی‌های مدیریت‌شده توسط BOM نسخه‌ای مشخص نشده‌اند، حل‌وفصل شوند.

برای احراز هویت با API اعتبارنامه دریافت کنید

دسترسی به Google Ads API به اعتبارنامه OAuth و یک توکن برنامه‌نویس Google Ads API نیاز دارد. این بخش توضیح می دهد که اینها چیستند، چگونه استفاده می شوند و چگونه به دست می آیند.

توکن توسعه دهنده (برای دسترسی به API)

توکن برنامه‌نویس به یک حساب مدیر مرتبط است و می‌توان آن را در رابط وب Google Ads پیدا کرد.

اگرچه توکن توسعه دهنده به یک حساب مدیر مرتبط است، اما امکان دسترسی به آن حساب را فراهم نمی کند. در عوض، توکن توسعه دهنده به طور کلی به API دسترسی می دهد و دسترسی سطح حساب از طریق OAuth پیکربندی می شود.

اعتبارنامه OAuth (برای دسترسی به حساب‌های Google Ads)

برای اجازه دادن به عنوان کاربران حساب Google با دسترسی به حساب‌های Google Ads، باید مجموعه‌ای از اطلاعات کاربری OAuth را ارائه کنید.

دو جریان OAuth وجود دارد که به طور کلی استفاده می شود: برنامه دسکتاپ (نصب شده) یا برنامه وب. تفاوت اصلی بین این دو این است که برنامه‌های دسکتاپ باید مرورگر سیستم را باز کنند و یک URI تغییر مسیر محلی برای رسیدگی به پاسخ‌ها از سرور مجوز Google ارائه دهند، در حالی که برنامه‌های وب می‌توانند یک مرورگر شخص ثالث دلخواه را برای تکمیل مجوز هدایت کنند و اعتبارنامه را به سرور شما ارسال کنند. این کتابخانه همچنین از جریان حساب سرویس که کمتر استفاده می شود پشتیبانی می کند.

اگر مجوز استفاده از اطلاعات کاربری خود را صادر کنید (جریان برنامه دسکتاپ)

به جریان برنامه دسکتاپ OAuth مراجعه کنید. این شامل تمام جزئیاتی است که برای تأیید اعتبار با اعتبار خود نیاز دارید.

اگر به عنوان یک کاربر شخص ثالث Google مجوز دهید (جریان وب)

به جریان برنامه وب OAuth مراجعه کنید. این مثالی از نحوه تنظیم مجوز OAuth برای کاربران خودسرانه شخص ثالث را نشان می دهد.

اگر به عنوان کاربر دامنه Google Apps مجوز دهید (جریان حساب سرویس)

به جریان حساب سرویس OAuth مراجعه کنید. در اینجا مثالی از نحوه تنظیم مجوز OAuth برای کاربران دامنه Google Apps ارائه می شود.

اگر دسترسی شما به حساب مشتری Google Ads از طریق یک حساب مدیر Google Ads است، باید شناسه مشتری ورود به سیستم را نیز همانطور که در زیر توضیح داده شده است مشخص کنید.

شناسه مشتری ورود به سیستم (برای دسترسی به حساب‌های Google Ads از طریق حساب مدیر)

به صورت اختیاری، شناسه مشتری یک حساب مدیر را مشخص کنید که به حساب سرویس دهنده دسترسی دارد. اگر دسترسی شما به حساب مشتری از طریق یک حساب مدیر باشد، باید مشخص شود. نیازی به تعیین تمام حساب‌های مدیر در مسیر شناسه مشتری نیست، فقط بالاترین شناسه مدیری است که برای مجوزهای دسترسی استفاده می‌کنید. برای جزئیات بیشتر، به اسناد مربوطه مراجعه کنید.

کتابخانه مشتری را با اعتبار خود پیکربندی کنید

شما می توانید کتابخانه مشتری را با یک فایل پیکربندی، متغیرهای محیطی یا به صورت برنامه ای پیکربندی کنید. برای این راهنما، ما از رویکرد فایل پیکربندی استفاده می کنیم و روی دسکتاپ و جریان های وب تمرکز می کنیم. استفاده از یک فایل پیکربندی به طور کلی روش خوبی است اگر فقط یک مجموعه اعتبار دارید (به عنوان مثال، حساب ها را تحت یک مدیر واحد مدیریت می کنید).

یک فایل ~/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 Ads شما بدون خط تیره است.

برای اجرا با Gradle:

./gradlew -q runExample --example="basicoperations.GetCampaigns --customerId INSERT_CUSTOMER_ID_HERE"

نمونه های دیگر را بررسی کنید

بسته نمونه در 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'