مانند سایر APIهای گوگل، API گوگل ادز از پروتکل OAuth 2.0 برای احراز هویت و مجوزدهی استفاده میکند. OAuth 2.0 به برنامه کلاینت API گوگل ادز شما این امکان را میدهد که بدون نیاز به مدیریت یا ذخیره اطلاعات ورود کاربر، به حساب گوگل ادز او دسترسی پیدا کند.
این راهنما نحوه پیکربندی کتابخانه کلاینت جاوا برای احراز هویت API گوگل ادز با استفاده از سه جریان رایج OAuth 2.0 را به همراه توضیح اعتبارنامههای لازم پوشش میدهد.
برای آشنایی عمیقتر با مدل دسترسی به API گوگل ادز، راهنمای مدل دسترسی به گوگل ادز را مطالعه کنید.
مدارک تحصیلی
دسترسی به API گوگل ادز به یک توکن توسعهدهنده، اعتبارنامههای OAuth 2.0 و در برخی موارد، شناسه مشتری برای ورود نیاز دارد.
توکن توسعهدهنده
توکن توسعهدهنده به یک حساب کاربری مدیر مرتبط است و میتوان آن را در رابط وب گوگل ادز یافت.
اگرچه توکن توسعهدهنده به یک حساب کاربری مدیر متصل است، اما دسترسی به آن حساب را فراهم نمیکند. در عوض، توکن توسعهدهنده به طور کلی دسترسی به API را اعطا میکند و دسترسی در سطح حساب از طریق OAuth 2.0 پیکربندی میشود.
در کتابخانه کلاینت، توکن توسعهدهنده توسط کلید api.googleads.developerToken در فایل ads.properties شما مشخص میشود.
اعتبارنامههای OAuth 2.0
برای تأیید دسترسی کاربران حساب گوگل به حسابهای گوگل ادز، باید مجموعهای از اعتبارنامههای OAuth 2.0 را ارائه دهید. نوع اعتبارنامههای مورد نیاز بسته به جریان OAuth 2.0 مورد استفاده متفاوت است.
این کتابخانه از سه جریان پشتیبانی میکند:
- جریان حساب خدمات
- جریان احراز هویت تک کاربره
- جریان احراز هویت چند کاربره
برای جزئیات بیشتر در مورد جریانهای OAuth در API گوگل ادز، به بخش OAuth Overview مراجعه کنید و دستورالعملهای مربوط به جریانی که به بهترین وجه نیازهای شما را برآورده میکند، برای دریافت اعتبارنامههای مورد نیاز، دنبال کنید.
شناسه مشتری ورود
به صورت اختیاری، شناسه مشتری یک حساب کاربری مدیریتی که دسترسی به حساب کاربری ارائه دهنده را فراهم میکند، مشخص کنید. اگر دسترسی شما به حساب کاربری از طریق یک حساب کاربری مدیریتی است، باید این مورد مشخص شود. نیازی به مشخص کردن همه حسابهای کاربری مدیریتی در مسیر شناسه مشتری نیست، فقط بالاترین شناسه مدیریتی که برای مجوزهای دسترسی استفاده میکنید، کافی است. برای جزئیات بیشتر، به مستندات مربوطه مراجعه کنید.
در کتابخانه کلاینت، شناسه مشتری ورود به سیستم توسط کلید api.googleads.loginCustomerId در فایل ads.properties شما مشخص میشود.
پیکربندی
شما میتوانید کتابخانه کلاینت را با یک فایل ads.properties ، متغیرهای محیطی یا به صورت برنامهنویسی پیکربندی کنید. این راهنما بر استفاده از فایل ads.properties تمرکز دارد. برای جزئیات بیشتر در مورد همه گزینهها، به راهنمای پیکربندی مراجعه کنید.
اگر از فایل ads.properties استفاده میکنید، آن را در دایرکتوری home خود قرار دهید: ~/ads.properties .
گردشهای کاری OAuth
سه گردش کار رایج هنگام کار با API گوگل ادز وجود دارد.
جریان حساب خدمات
اگر گردش کار شما نیازی به تعامل انسانی ندارد، این گردش کار توصیه میشود. این گردش کار نیاز به یک مرحله پیکربندی دارد که در آن کاربر یک حساب سرویس به حساب Google Ads خود اضافه میکند. سپس برنامه میتواند از اعتبارنامههای حساب سرویس برای مدیریت حساب Google Ads کاربر استفاده کند.
وقتی فایل JSON کلید خصوصی را داشتید، موارد زیر را به فایل ads.properties خود اضافه کنید:
api.googleads.serviceAccountSecretsPath=PRIVATE_KEY_JSON_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
# Only add this key if you are using impersonation to access an account
# other than the service account itself.
# api.googleads.serviceAccountUser=USER_EMAIL_TO_IMPERSONATE
برای کسب اطلاعات بیشتر به راهنمای گردش کار حساب سرویس مراجعه کنید.
جریان احراز هویت تک کاربره
اگر نمیتوانید از حسابهای سرویس استفاده کنید، میتوانید از این گردش کار استفاده کنید. این گردش کار به دو مرحله پیکربندی نیاز دارد:
- به یک کاربر واحد اجازه دسترسی به تمام حسابهایی که قرار است با استفاده از Google Ads API مدیریت شوند را بدهید. یک رویکرد رایج این است که به کاربر یک حساب کاربری مدیریت Google Ads API بدهید و تمام حسابهای Google Ads را به آن حساب کاربری مدیریت لینک کنید.
- کاربر یک ابزار خط فرمان مانند gcloud یا نمونه کد
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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
برای کسب اطلاعات بیشتر به راهنمای گردش کار احراز هویت تک کاربره مراجعه کنید.
جریان احراز هویت چند کاربره
اگر برنامه شما به کاربران اجازه میدهد وارد سیستم شوند و به برنامه شما اجازه دهند تا حسابهای Google Ads خود را از طرف آنها مدیریت کند، این گردش کار توصیه میشود. 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
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
برای کسب اطلاعات بیشتر به راهنمای گردش کار احراز هویت چند کاربره مراجعه کنید.
اگر کاربر من چندین حساب کاربری را مدیریت کند، چه میشود؟
رایج است که یک کاربر بیش از یک حساب گوگل ادز را مدیریت کند، چه از طریق دسترسی مستقیم به حسابها و چه از طریق یک حساب مدیریت گوگل ادز. کتابخانه کلاینت جاوا نمونههای کد زیر را ارائه میدهد که نحوه مدیریت چنین مواردی را نشان میدهد.
- مثال کد GetAccountHierarchy نحوه بازیابی لیست همه حسابهای کاربری تحت یک حساب مدیریت تبلیغات گوگل (Google Ads manager) را نشان میدهد.
- مثال کد ListAccessibleCustomers نحوه بازیابی لیست تمام حسابهایی را که یک کاربر به آنها دسترسی مستقیم دارد، نشان میدهد. سپس میتوان از این حسابها به عنوان مقادیر معتبر برای تنظیم
LoginCustomerIdاستفاده کرد.
اعتبارنامههای پیشفرض برنامه
کتابخانه کلاینت جاوا همچنین از احراز هویت با اعتبارنامههای پیشفرض برنامه پشتیبانی میکند.
این امر به ویژه برای توسعه محلی یا برای توسعه در برابر API های مختلف Google مفید است، زیرا میتوانید از اعتبارنامههای یکسان دوباره استفاده کنید، مشروط بر اینکه بتوانند به دامنههای صحیح OAuth 2.0 دسترسی داشته باشند.
برای API تبلیغات گوگل، مطمئن شوید که اعتبارنامههای پیشفرض برنامه شما میتوانند به محدوده OAuth 2.0 در آدرس https://www.googleapis.com/auth/adwords دسترسی داشته باشند.
برای استفاده از اعتبارنامههای پیشفرض برنامه، گزینه api.googleads.useApplicationDefaultCredentials را در فایل ads.properties خود روی true تنظیم کنید. هنگام استفاده از اعتبارنامههای پیشفرض برنامه، شناسه کلاینت، رمز کلاینت و توکن refresh نباید تنظیم شوند.