شروع شدن

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

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

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

ما توصیه می‌کنیم از فهرست مواد (BOM) مربوط به API گوگل ادز برای مدیریت نسخه‌های وابستگی استفاده کنید. این بهترین راه برای جلوگیری از تداخل وابستگی با کتابخانه‌هایی مانند Guava و GAX است که توسط سایر فریم‌ورک‌ها نیز استفاده می‌شوند. BOM تضمین می‌کند که شما از نسخه‌های دقیقی از این وابستگی‌ها که با کتابخانه کلاینت گوگل ادز آزمایش شده‌اند، استفاده می‌کنید.

وابستگی 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>41.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:41.0.0')

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

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

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

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

فهرست اجزای API گوگل ادز شامل مدیریت نسخه برای چندین کتابخانه رایج مانند Guava ، Protobuf ، GAX و gRPC است. برای جلوگیری از تداخل وابستگی‌های احتمالی، هنگام اعلام وابستگی‌هایی که فهرست اجزای تحت پوشش آنها را پوشش می‌دهد ، نباید نسخه‌ای را مشخص کنید. فهرست اجزای تحت پوشش به طور خودکار نسخه‌های این کتابخانه‌ها را مدیریت می‌کند و سازگاری را تضمین می‌کند.

برای مثال، برای تعریف وابستگی Guava در Maven، از کد زیر استفاده کنید:

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

و در گریدل:

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

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

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

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

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

توکن توسعه‌دهنده به یک حساب کاربری مدیر مرتبط است و می‌توان آن را در رابط وب گوگل ادز یافت.

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

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

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

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

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

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

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

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

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

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

اگر دسترسی شما به حساب کاربری گوگل ادز از طریق حساب کاربری مدیریت گوگل ادز است، باید یک شناسه مشتری برای ورود به سیستم نیز مطابق توضیحات زیر تعیین کنید.

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

توجه: یک کاربر گوگل می‌تواند به بسیاری از حساب‌های گوگل ادز دسترسی داشته باشد.

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

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

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

توجه: اگر با مجموعه‌های مختلفی از اعتبارنامه‌های 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 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'

توجه: از کد منبع، می‌توانید نظراتی که شامل [START...] و [END...] هستند را نادیده بگیرید - آنها به‌طور خاص توسط گوگل استفاده می‌شوند.