احراز هویت و مجوز

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

مدل دسترسی به گوگل ادز را درک کنید

برای کار مؤثر با API گوگل ادز، باید نحوه‌ی عملکرد مدل دسترسی گوگل ادز را درک کنید. توصیه می‌کنیم راهنمای مدل دسترسی گوگل ادز را مطالعه کنید.

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

سه گردش کار رایج هنگام کار با API گوگل ادز وجود دارد.

جریان حساب خدمات

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

در اینجا نحوه تنظیم OAuth2 برای دسترسی به API با استفاده از اعتبارنامه‌های شخصی خود با یک حساب کاربری سرویس در کتابخانه کلاینت Perl آورده شده است:

1. ایجاد اعتبارنامه‌های OAuth2:

   برای ایجاد یک حساب کاربری سرویس و یک فایل *.JSON ، دستورالعمل‌ها را دنبال کنید.

2. کتابخانه کلاینت را راه‌اندازی کنید:

   مسیر JSON کلید خصوصی را در پیکربندی خود تنظیم کنید. اگر از فایل googleads.properties استفاده می‌کنید، موارد زیر را اضافه کنید:

   jsonKeyFilePath=PRIVATE_KEY_FILE_PATH
   

   اگر از متغیرهای محیطی استفاده می‌کنید، موارد زیر را به پیکربندی یا محیط Bash خود اضافه کنید:

   export GOOGLE_ADS_JSON_KEY_FILE_PATH=PRIVATE_KEY_FILE_PATH
   

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

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

جریان احراز هویت تک کاربره

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

1. به یک کاربر واحد اجازه دسترسی به تمام حساب‌هایی که قرار است با استفاده از Google Ads API مدیریت شوند را بدهید. یک رویکرد رایج این است که به کاربر دسترسی به یک حساب کاربری مدیریت Google Ads API داده شود و تمام حساب‌های Google Ads تحت آن حساب کاربری مدیریت پیوند داده شوند.
2. کاربر کد مثال generate_user_credentials.pl را اجرا می‌کند تا به برنامه شما اجازه دهد تمام حساب‌های گوگل ادز خود را از طرف او مدیریت کند.

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

1. در یک ترمینال، مثال generate_user_credentials.pl را در دایرکتوری examples اجرا کنید. می‌توانید مقادیر INSERT_XXX_HERE را در مثال قبل از اجرا تغییر دهید یا از آرگومان‌های خط فرمان -client_id برای شناسه کلاینت و -client_secret برای راز کلاینت استفاده کنید.

   perl generate_user_credentials.pl -client_id {client_id} -client_secret {client_secret}
   

2. این نمونه کد شما را به بازدید از یک URL ترغیب می‌کند که در آن باید به برنامه اجازه دهید از طرف شما به حساب Google Ads شما دسترسی پیدا کند.

   Paste this url in your browser:
   https://accounts.google.com/o/oauth2/v2/auth?response_type=code&access_type=offline&client_id=...
   

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

   

   به صفحه‌ای هدایت می‌شوید که پیامی مبنی بر موفقیت‌آمیز بودن مجوز در آن نمایش داده می‌شود.

   Authorization code was successfully retrieved.
   

3. به کنسولی که در آن مثال کد را اجرا می‌کنید، برگردید. خواهید دید که مثال کد تکمیل شده و توکن به‌روزرسانی شما و برخی دستورالعمل‌ها را نمایش می‌دهد، و در ادامه دستورالعمل‌هایی که برای پیکربندی کتابخانه کلاینت باید دنبال کنید، آمده است:

   Replace the following keys and values in your googleads.properties configuration file:
   
   clientId==***********************apps.googleusercontent.com
   clientSecret=****
   refreshToken=****
   

4. برای خاتمه دادن به فرآیند، Ctrl + C را فشار دهید. سپس توکن refresh تولید شده را به همراه شناسه کلاینت و رمز کلاینت در فایل googleads.properties خود کپی کنید یا آن را در جای دیگری ذخیره کنید تا در صورت نمونه‌سازی کتابخانه در زمان اجرا، از آن استفاده کنید.

این کتابخانه می‌تواند با استفاده از اعتبارنامه‌های OAuth 2.0 کاربر و با تنظیم موارد زیر در googleads.properties مقداردهی اولیه شود:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

جریان احراز هویت چند کاربره

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

برای Perl، شما معمولاً یک جریان برنامه وب را پیاده‌سازی می‌کنید که در آن برنامه شما تغییر مسیر OAuth 2.0 و مدیریت توکن را مدیریت می‌کند. کاربر از طریق برنامه شما احراز هویت می‌شود و برنامه شما توکن refresh کاربر را ذخیره و از آن برای برقراری تماس‌های API از طرف او استفاده می‌کند.

پیکربندی استفاده از اعتبارنامه‌های به دست آمده مشابه جریان احراز هویت تک کاربره است:

clientId=OAUTH_CLIENT_ID
clientSecret=OAUTH_CLIENT_SECRET
refreshToken=REFRESH_TOKEN
developerToken=DEVELOPER_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_DEVELOPER_TOKEN=DEVELOPER_TOKEN
export GOOGLE_ADS_LOGIN_CUSTOMER_ID=LOGIN_CUSTOMER_ID

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

اگر کاربر من چندین حساب کاربری را مدیریت کند، چه می‌شود؟

رایج است که یک کاربر بیش از یک حساب Google Ads را مدیریت کند، چه از طریق دسترسی مستقیم به حساب‌ها و چه از طریق یک حساب مدیریت Google Ads. کتابخانه کلاینت Perl مثال‌هایی را ارائه می‌دهد که نحوه مدیریت چنین مواردی را نشان می‌دهد.

1. مثال get_account_hierarchy.pl نحوه بازیابی لیست تمام حساب‌های کاربری تحت یک حساب مدیریت تبلیغات گوگل را نشان می‌دهد.
2. مثال list_accessible_customers.pl نحوه بازیابی لیست تمام حساب‌هایی را که یک کاربر به آنها دسترسی مستقیم دارد، نشان می‌دهد. سپس می‌توان از این حساب‌ها به عنوان مقادیر معتبر برای تنظیم LoginCustomerId در فایل googleads.properties یا متغیر محیطی GOOGLE_ADS_LOGIN_CUSTOMER_ID استفاده کرد.