اصالت‌سنجی و مجوز

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

آشنایی با مدل دسترسی Google Ads

برای کار کردن مؤثر با Google Ads API، با نحوه عملکرد مدل دسترسی Google Ads آشنا شوید. به راهنمای مدل دسترسی Google Ads مراجعه کنید.

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

سه گردش کار رایج وجود دارد که هنگام کار با Google Ads API استفاده می‌شود.

جریان حساب سرویس

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

کتابخانه را به‌صورت زیر پیکربندی کنید:

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

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

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

جریان اصالت‌سنجی تک‌کاربره

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

برای کسب اطلاعات بیشتر، به راهنمای گردش کار اصالت‌سنجی تک‌کاربره مراجعه کنید.

جریان اصالت‌سنجی چندکاربره

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    LoginCustomerId = userSession.LoginCustomerId,
    OAuth2ClientId = "INSERT_OAUTH_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = userSession.RefreshToken
};

GoogleAdsClient client = new GoogleAdsClient(config);

از Google.Ads.GoogleAds v27.0.0، می‌توانید یک شیء ICredential یا GoogleCredential ازپیش پیکربندی‌شده را مستقیماً بااستفاده از ویژگی Credentials در GoogleAdsConfig تزریق کنید.

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

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

اگر کاربر من چند حساب را مدیریت کند چه؟

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

1. نمونه کد GetAccountHierarchy نشان می‌دهد که چگونه فهرست همه حساب‌های تحت حساب مدیر Google Ads را بازیابی کنید.
2. نمونه کد ListAccessibleCustomers نشان می‌دهد که چگونه می‌توان فهرست همه حساب‌هایی را که کاربر دسترسی مستقیم به آن‌ها دارد بازیابی کرد. سپس می‌توان از این حساب‌ها به‌عنوان مقادیر معتبر برای تنظیم LoginCustomerId استفاده کرد.

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

کتابخانه کارخواه .NET (نسخه v24.1.0 و جدیدتر) از اصالت‌سنجی با اعتبارنامه پیش‌فرض برنامه نیز پشتیبانی می‌کند.

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

برای Google Ads API، مطمئن شوید «اعتبارنامه‌های پیش‌فرض برنامه» شما می‌تواند به https://www.googleapis.com/auth/adwords OAuth 2.0 scope دسترسی داشته باشد.

برای استفاده از «اعتبارنامه پیش‌فرض برنامه»، گزینه UseApplicationDefaultCredentials را در GoogleAdsConfig روی true تنظیم کنید (یا متغیر محیطی USE_APPLICATION_DEFAULT_CREDENTIALS=true را هنگام بار کردن پیکربندی با config.LoadFromEnvironmentVariables() تنظیم کنید):

GoogleAdsConfig config = new GoogleAdsConfig()
{
    UseApplicationDefaultCredentials = true,
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

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