Google Ads API، مانند دیگر Google API، از پروتکل OAuth 2.0 برای اصالت‌سنجی و صدور مجوز استفاده می‌کند. OAuth 2.0 به برنامه کارخواه Google Ads API شما امکان می‌دهد بدون نیاز به مدیریت یا ذخیره اطلاعات ورود به سیستم کاربر، به حساب Google Ads کاربر دسترسی پیدا کند.
آشنایی با مدل دسترسی Google Ads
برای کار کردن مؤثر با Google Ads API، با نحوه عملکرد مدل دسترسی Google Ads آشنا شوید. به راهنمای مدل دسترسی Google Ads مراجعه کنید.
گردش‌های کار OAuth
هنگام کار با Google Ads API، سه گردش کار رایج استفاده می‌شود.
جریان حساب سرویس
اگر گردش کار شما به هیچ تعامل انسانی نیاز ندارد، این گردش کار توصیه می‌شود. این گردش کار به مرحله پیکربندی نیاز دارد که در آن کاربر حساب خدمات را به حساب Google Ads خود اضافه می‌کند. سپس برنامه می‌تواند از اعتبارنامه‌های حساب سرویس برای مدیریت حساب Google Ads کاربر استفاده کند.
در اینجا نحوه راه‌اندازی OAuth2 برای دسترسی به API بااستفاده از اطلاعات اعتباری خودتان با حساب سرویس در کتابخانه مشتری Perl آمده است:
ایجاد اعتبارنامه‌های OAuth2:
دستورالعمل‌ها را برای تولید حساب سرویس و فایل کلید JSON دنبال کنید.
راه‌اندازی کتابخانه کارخواه:
مسیر JSON کلید خصوصی (و
impersonatedEmailاختیاری درصورت استفاده از واگذاری در سطح دامنه Google Workspace) را در پیکربندی‌تان تنظیم کنید. اگر از فایلgoogleads.propertiesاستفاده می‌کنید، موارد زیر را اضافه کنید:jsonKeyFilePath=PRIVATE_KEY_FILE_PATH # Optional unless using Google Workspace domain-wide delegation: impersonatedEmail=IMPERSONATED_EMAIL loginCustomerId=LOGIN_CUSTOMER_IDاگر از متغیرهای محیطی استفاده می‌کنید، موارد زیر را به پیکربندی یا محیط Bash خود اضافه کنید:
export GOOGLE_ADS_JSON_KEY_FILE_PATH=KEY_FILE_PATH export GOOGLE_ADS_IMPERSONATED_EMAIL=\ IMPERSONATED_EMAIL export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_IDبرای کسب اطلاعات بیشتر، به راهنمای گردش کار حساب سرویس مراجعه کنید.
جریان اصالت‌سنجی تک‌کاربر
اگر نمی‌توانید از حساب‌های سرویس استفاده کنید، می‌توانید از این گردش کار استفاده کنید. این گردش کار به دو مرحله پیکربندی نیاز دارد:
- به یک کاربر واحد دسترسی به همه حساب‌هایی را بدهید که باید بااستفاده از Google Ads API مدیریت شوند. رویکرد معمول این است که به کاربر دسترسی به حساب مدیر Google Ads API بدهید و همه حساب‌های Google Ads را در آن حساب مدیر پیوند دهید.
- کاربر
generate_user_credentials.plنمونه کد را اجرا می‌کند تا به برنامه شما اجازه دهد همه حساب‌های Google Ads خود را ازطرف او مدیریت کند.
مراحل زیر نمونه کد تعاملی را اجرا می‌کند که سپس از شما می‌خواهد ورودی ارائه دهید.
در پایانه، نمونه
generate_user_credentials.plرا در فهرست راهنمایexamplesاجرا کنید. می‌توانید مقادیرINSERT_XXX_HEREرا در نمونه قبل‌از اجرا تغییر دهید یا از آرگومان‌های خط فرمان-client_idبرای شناسه کارخواه و-client_secretبرای رمز کارخواه استفاده کنید.perl generate_user_credentials.pl \ -client_id OAUTH_CLIENT_ID \ -client_secret OAUTH_CLIENT_SECRETاین کد نمونه از شما می‌خواهد از نشانی وبی بازدید کنید که در آن باید به برنامه اجازه دهید ازجانب شما به حساب Google Ads شما دسترسی داشته باشد.
Paste this url in your browser: https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline...در جلسه مرورگر خصوصی یا پنجره ناشناس، به نشانی وب بروید. با «حساب Google» که برای دسترسی به Google Ads استفاده می‌کنید به سیستم وارد شوید. معمولاً این حساب ایمیلی است که به حساب مدیر Google Ads دسترسی دارد و شامل همه حساب‌هایی است که باید در سلسله‌مراتب حساب آن مدیریت کنید. در صفحه کسب رضایت OAuth 2.0، روی ادامه دادن کلیک کنید.
به صفحه‌ای هدایت می‌شوید که پیامی در آن نشان می‌دهد مجوزدهی موفقیت‌آمیز بوده است.
Authorization code was successfully retrieved.به کنسولی که نمونه کد را در آن اجرا می‌کنید برگردید. خواهید دید که نمونه کد تکمیل شده است و دستورالعمل‌هایی را به‌همراه دستورالعمل‌هایی که باید برای پیکربندی کتابخانه مشتری دنبال کنید نمایش می‌دهد:
Replace the following keys and values in your googleads.properties configuration file: clientId=***********************apps.googleusercontent.com clientSecret=**** refreshToken=****برای پایان دادن به فرایند،
Ctrl + Cرا فشار دهید. سپس ژتون بازآوری تولیدشده را به‌همراه شناسه کارخواه و رمز کارخواه در فایلgoogleads.propertiesکپی کنید یا آن را در جای دیگری ذخیره کنید تا درصورت نمونه‌سازی کتابخانه در زمان اجرا از آن استفاده کنید.
کتابخانه را می‌توان بااستفاده از اطلاعات کاربری OAuth 2.0 کاربر با تنظیم موارد زیر در googleads.properties مقداردهی اولیه کرد:
clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID
یا از متغیرهای محیطی استفاده کنید:
export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID
برای کسب اطلاعات بیشتر، به راهنمای گردش کار اصالت‌سنجی تک‌کاربره مراجعه کنید.
جریان اصالت‌سنجی چندکاربری
اگر برنامه‌تان به کاربران اجازه می‌دهد به سیستم وارد شوند و به برنامه‌تان اجازه می‌دهد حساب‌های Google Ads آن‌ها را ازطرف آن‌ها مدیریت کند، این گردش کار توصیه می‌شود. برنامه شما اعتبارنامه‌های کاربر OAuth 2.0 را می‌سازد و مدیریت می‌کند.
برای Perl، معمولاً جریان برنامه وب را پیاده‌سازی می‌کنید که در آن برنامه شما مدیریت کد و هدایت OAuth 2.0 را انجام می‌دهد. کاربر ازطریق برنامه شما اصالت‌سنجی می‌کند و برنامه شما ژتون بازآوری کاربر را ذخیره و استفاده می‌کند تا ازطرف او فراخوانی‌های میانای برنامه‌سازی کاربردی انجام دهد.
پیکربندی برای استفاده از اطلاعات اعتباری به‌دست‌آمده همانند جریان اصالت‌سنجی تک‌کاربر است:
clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
loginCustomerId=LOGIN_CUSTOMER_ID
یا از متغیرهای محیط استفاده کنید:
export GOOGLE_ADS_CLIENT_ID=OAUTH_CLIENT_ID
export GOOGLE_ADS_CLIENT_SECRET=OAUTH_CLIENT_SECRET
export GOOGLE_ADS_REFRESH_TOKEN=REFRESH_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID
برای کسب اطلاعات بیشتر، به راهنمای گردش کار اصالت‌سنجی چندکاربری مراجعه کنید.
اگر کاربر من چند حساب را مدیریت کند چه؟
معمولاً کاربران بیش‌از یک حساب Google Ads را مدیریت می‌کنند، چه ازطریق دسترسی مستقیم به حساب‌ها یا ازطریق حساب مدیر Google Ads. کتابخانه سرویس‌گیرنده Perl نمونه‌هایی ارائه می‌دهد که نحوه رسیدگی به چنین مواردی را نشان می‌دهد:
- نمونه
get_account_hierarchy.plنشان می‌دهد چگونه فهرست همه حساب‌های تحت حساب مدیر Google Ads را بازیابی کنید. - مثال
list_accessible_customers.plنشان می‌دهد چگونه فهرست همه حساب‌هایی را که کاربر به آن‌ها دسترسی مستقیم دارد بازیابی کنید. سپس می‌توان از این حساب‌ها به‌عنوان مقادیر معتبر برای تنظیمloginCustomerIdدر فایلgoogleads.propertiesیا متغیر محیطیGOOGLE_ADS_LOGIN_CUSTOMER_IDاستفاده کرد.