شروع شدن

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

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

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

وابستگی Maven عبارت است از:

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

وابستگی Gradle عبارت است از:

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

شما همچنین می توانید از منبع بسازید . برای هدف این راهنما، فرض بر این است که شما یک راه اندازی پروژه با وابستگی های مورد نیاز در دسترس دارید.

برای احراز هویت با 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'