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استفاده کرد.