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

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 دسترسی داشته باشد.

برای استفاده از «اطلاعات اعتباری پیش‌فرض برنامه»، گزینه 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، به صفحه پیکربندی مراجعه کنید.