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

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

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

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

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

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

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

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

// Initialize a GoogleAdsConfig class.
GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = ******
};

// Initialize a GoogleAdsClient class.
GoogleAdsClient client = new GoogleAdsClient(config);

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

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

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

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

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

GoogleAdsConfig googleAdsConfig = new GoogleAdsConfig()
{
    DeveloperToken = DEVELOPER_TOKEN,
    LoginCustomerId = LOGIN_CUSTOMER_ID,
    OAuth2ClientId = OAUTH_CLIENT_ID,
    OAuth2ClientSecret = OAUTH_CLIENT_SECRET,
    OAuth2RefreshToken = REFRESH_TOKEN,
};

GoogleAdsClient googleAdsClient = new GoogleAdsClient(googleAdsConfig);

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

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

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

GoogleAdsConfig googleAdsConfig = new GoogleAdsConfig()
{
    DeveloperToken = DEVELOPER_TOKEN,
    LoginCustomerId = LOGIN_CUSTOMER_ID,
    OAuth2ClientId = OAUTH_CLIENT_ID,
    OAuth2ClientSecret = OAUTH_CLIENT_SECRET,
    OAuth2RefreshToken = REFRESH_TOKEN,
};

GoogleAdsClient googleAdsClient = new GoogleAdsClient(googleAdsConfig);

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

1. مثال کد AuthenticateInAspNetCoreApplication نحوه ساخت یک برنامه وب را نشان می‌دهد که احراز هویت کاربر را در زمان اجرا برای مدیریت حساب‌های Google Ads از طرف آنها دریافت می‌کند. این برنامه از اعتبارنامه‌های OAuth 2.0 کاربر برای بازیابی کمپین‌ها در حساب Google Ads او استفاده می‌کند.

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

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

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

1. مثال کد GetAccountHierarchy نحوه بازیابی لیست همه حساب‌های کاربری تحت یک حساب مدیریت تبلیغات گوگل (Google Ads manager) را نشان می‌دهد.
2. مثال کد ListAccessibleCustomers نحوه بازیابی لیست تمام حساب‌هایی را که یک کاربر به آنها دسترسی مستقیم دارد، نشان می‌دهد. سپس می‌توان از این حساب‌ها به عنوان مقادیر معتبر برای تنظیم LoginCustomerId استفاده کرد.

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

کتابخانه کلاینت .NET همچنین از احراز هویت با اعتبارنامه‌های پیش‌فرض برنامه پشتیبانی می‌کند.

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

برای API گوگل ادز، مطمئن شوید که اعتبارنامه‌های پیش‌فرض برنامه شما می‌توانند به محدوده OAuth2.0 در آدرس https://www.googleapis.com/auth/adwords دسترسی داشته باشند.

برای استفاده از اعتبارنامه‌های پیش‌فرض برنامه، گزینه UseApplicationDefaultCredentials را در GoogleAdsConfig خود روی true تنظیم کنید: این کار را می‌توان به همان روش‌های تنظیم سایر ویژگی‌های پیکربندی در کتابخانه کلاینت انجام داد، بنابراین یا در کد خود، در یک فایل پیکربندی یا با استفاده از متغیرهای محیطی.

برای جزئیات بیشتر در مورد گزینه‌های موجود برای پیکربندی کتابخانه کلاینت .NET، به صفحه پیکربندی مراجعه کنید.