Authentication

مانند دیگر «میاناهای برنامه‌سازی کاربردی Google»، «میانای برنامه‌سازی کاربردی Google Ads» از پروتکل 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 کاربر استفاده کند.

کتابخانه PHP را می‌توان به روش‌های زیر پیکربندی کرد:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withJsonKeyFilePath('INSERT_PATH_TO_JSON_KEY_FILE_HERE')
    // Optional in v32.1.0 and later (defaults to
    // 'https://www.googleapis.com/auth/adwords').
    ->withScopes('https://www.googleapis.com/auth/adwords')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

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

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

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

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

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

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

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

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

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

// Construct credentials dynamically per authenticated user session.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken($userRefreshToken)
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId($userLoginCustomerId)
    ->build();

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

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

کتابخانه کارخواه PHP همچنین از اصالت‌سنجی با اعتبارنامه پیش‌فرض برنامه (ADC) پشتیبانی می‌کند. وقتی نه اعتبارنامه‌های حالت «برنامه» (clientId، clientSecret، refreshToken) و نه اعتبارنامه‌های حالت «حساب سرویس» (jsonKeyFilePath) در OAuth2TokenBuilder تنظیم نشده باشد، فراخوانی build() به‌طور خودکار به «اعتبارنامه‌های پیش‌فرض برنامه» برمی‌گردد:

$oAuth2Credential = (new OAuth2TokenBuilder())->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->withLoginCustomerId('INSERT_LOGIN_CUSTOMER_ID_HERE')
    ->build();

مدیریت چند حساب

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

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