اصالت‌سنجی و مجوز

Google Ads API، مانند دیگر Google APIها، از پروتکل OAuth 2.0 برای اصالت‌سنجی و صدور مجوز استفاده می‌کند. OAuth 2.0 به برنامه کارخواه Google Ads API شما امکان می‌دهد بدون نیاز به مدیریت یا ذخیره اطلاعات ورود به سیستم کاربر، به حساب Google Ads کاربر دسترسی پیدا کند.

این راهنما نحوه پیکربندی کتابخانه کارخواه Java برای اصالت‌سنجی Google Ads API بااستفاده از سه جریان رایج OAuth 2.0 را پوشش می‌دهد و اعتبارنامه‌های لازم را توضیح می‌دهد.

برای بررسی جامع‌تر مدل دسترسی Google Ads API، راهنمای مدل دسترسی Google Ads را بخوانید.

اطلاعات کاربری

دسترسی به Google Ads API به اطلاعات کاربری OAuth 2.0 و در برخی موارد به شناسه مشتری ورود به سیستم نیاز دارد.

اعتبارنامه‌های OAuth 2.0

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

این کتابخانه از سه جریان پشتیبانی می‌کند:

• جریان حساب سرویس
• جریان اصالت‌سنجی تک‌کاربره
• جریان اصالت‌سنجی چندکاربره

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

شناسه مشتری ورود به سیستم

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

در کتابخانه کارخواه، شناسه مشتری ورود به سیستم با کلید api.googleads.loginCustomerId در فایل ads.properties شما مشخص می‌شود.

پیکربندی

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

اگر از فایل ads.properties استفاده می‌کنید، آن را در دایرکتوری صفحه اصلی قرار دهید: ~/ads.properties.

گردش‌های کار OAuth

سه گردش کار رایج وجود دارد که هنگام کار با Google Ads API استفاده می‌شود.

جریان حساب سرویس

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

وقتی فایل JSON کلید خصوصی را دریافت کردید، موارد زیر را به فایل ads.properties خود اضافه کنید:

api.googleads.serviceAccountSecretsPath=INSERT_PATH_TO_JSON_HERE
# Only add this key if you are using Google Workspace domain-wide delegation
# to impersonate a user who has access to the Google Ads account.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE

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

جریان اصالت‌سنجی تک‌کاربره

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

1. به یک کاربر امکان دسترسی به همه حساب‌هایی را بدهید که قرار است بااستفاده از Google Ads API مدیریت شوند. یک رویکرد رایج این است که به کاربر دسترسی به حساب مدیر Google Ads API اعطا شود و همه حساب‌های Google Ads هدف تحت آن حساب مدیر پیوند داده شوند.
2. کاربر ابزار خط فرمانی مثل gcloud CLI یا GenerateUserCredentials نمونه کد را اجرا می‌کند تا به برنامه شما اجازه دهد همه حساب‌های 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

برای کسب اطلاعات بیشتر، به راهنمای گردش کار اصالت‌سنجی تک‌کاربره مراجعه کنید.

جریان اصالت‌سنجی چندکاربره

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

برای برنامه‌های چندکاربره، شناسه کارخواه OAuth 2.0 و رمز کارخواه برنامه‌تان را در ads.properties (یا فروشگاه پیکربندی دیگری) ذخیره کنید، درحالی‌که ژتون بازآوری هر کاربر نهایی را به‌طور ایمن در پایگاه داده برنامه‌تان ذخیره می‌کنید و آن را به‌صورت برنامه‌نویسی‌شده در زمان اجرا هنگام ساختن UserCredentials و GoogleAdsClient ارسال می‌کنید:

api.googleads.clientId=INSERT_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_CLIENT_SECRET_HERE

برای کسب اطلاعات بیشتر، به راهنمای گردش کار اصالت‌سنجی چندکاربره مراجعه کنید.

مدیریت چند حساب

معمولاً کاربران بیش‌از یک حساب Google Ads را مدیریت می‌کنند، چه ازطریق دسترسی مستقیم به حساب‌ها و چه ازطریق حساب مدیر Google Ads. کتابخانه کارخواه Java نمونه کدهای زیر را ارائه می‌دهد که نحوه رسیدگی به چنین مواردی را نشان می‌دهد:

1. نمونه کد GetAccountHierarchy نشان می‌دهد که چگونه فهرست همه حساب‌های تحت حساب مدیر Google Ads را بازیابی کنید.
2. نمونه کد ListAccessibleCustomers نشان می‌دهد که چگونه می‌توان فهرست همه حساب‌هایی را که کاربر دسترسی مستقیم به آن‌ها دارد بازیابی کرد. سپس می‌توان از این حساب‌ها به‌عنوان مقادیر معتبر برای تنظیم loginCustomerId استفاده کرد.

اعتبارنامه پیش‌فرض برنامه

کتابخانه کارخواه Java از اصالت‌سنجی با اعتبارنامه پیش‌فرض برنامه نیز پشتیبانی می‌کند.

این به‌ویژه برای توسعه محلی یا توسعه دربرابر Google APIهای مختلف مفید است، زیرا می‌توانید از همان اعتبارنامه‌ها مجدداً استفاده کنید، مشروط بر اینکه بتوانند به دامنه‌های OAuth 2.0 موردنیاز دسترسی داشته باشند.

برای Google Ads API، مطمئن شوید «اعتبارنامه‌های پیش‌فرض برنامه» شما می‌تواند به https://www.googleapis.com/auth/adwords OAuth 2.0 scope دسترسی داشته باشد.

برای استفاده از «اعتبارنامه‌های پیش‌فرض برنامه»، گزینه api.googleads.useApplicationDefaultCredentials را در فایل ads.properties روی true تنظیم کنید (یا .enableApplicationDefaultCredentials() را در GoogleAdsClient.newBuilder() فراخوانی کنید). هنگام استفاده از «اعتبارنامه‌های پیش‌فرض برنامه»، شناسه کارخواه، رمز کارخواه، و ژتون بازآوری نباید تنظیم شوند.