حساب های خدماتی

این راهنما نحوه دسترسی به Google Ads API با حساب‌های سرویس را مورد بحث قرار می‌دهد.

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

حساب‌های سرویس از یک جریان OAuth 2.0 استفاده می‌کنند که نیازی به مجوز انسانی ندارد و در عوض از یک فایل کلیدی استفاده می‌کنند که فقط برنامه شما می‌تواند به آن دسترسی داشته باشد.

استفاده از حساب های خدماتی دو مزیت کلیدی دارد:

  • مجوز دسترسی به Google API به عنوان یک مرحله پیکربندی انجام می‌شود، بنابراین از عوارض مرتبط با سایر جریان‌های OAuth 2.0 که به تعاملات کاربر نیاز دارند، اجتناب می‌شود.

  • جریان ادعای OAuth 2.0 به برنامه شما امکان می‌دهد در صورت لزوم جعل هویت کاربران دیگر را جعل کند.

دو راه برای مجوز دادن با حساب‌های سرویس وجود دارد: مستقیم یا با جعل هویت.

مجوز با دسترسی مستقیم به حساب

در این گزینه به حساب سرویس دسترسی مستقیم به حساب Google Ads خود می دهید.

راه اندازی دسترسی به حساب

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

    کلید حساب سرویس را با فرمت JSON دانلود کنید و شناسه حساب سرویس و ایمیل را یادداشت کنید.

  2. به عنوان سرپرست به حساب Google Ads خود وارد شوید. به Admin > Access and Security بروید.

  3. روی دکمه + در زیر تب کاربران کلیک کنید.

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

  5. به حساب سرویس دسترسی داده شده است.

پیکربندی کتابخانه مشتری

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

جاوا

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

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید.

دات نت

کلیدهای زیر را در App.config / Web.config خود پیکربندی کنید. برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

پایتون

مسیر JSON کلید خصوصی را در پیکربندی خود تنظیم کنید. اگر از google-ads.yaml file ، رشته YAML یا dict استفاده می کنید، موارد زیر را اضافه کنید:

json_key_file_path: JSON_KEY_FILE_PATH

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

کلیدهای زیر را در google_ads_php.ini خود پیکربندی کنید. برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

یاقوت سرخ

کلیدهای زیر را در google_ads_config.rb خود پیکربندی کنید.

c.keyfile = 'JSON_KEY_FILE_PATH'

پرل

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

jsonKeyFilePath=JSON_KEY_FILE_PATH

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

مجوز با استفاده از جعل هویت

در این گزینه شما جعل هویت کاربری می شوید که با استفاده از حساب سرویس به حساب Google Ads شما دسترسی دارد. این رویکرد فقط برای مشتریان Google Workspace کار می کند. یک حساب سرویس فقط می‌تواند هویت کاربران (آدرس ایمیل) را در همان Google Workspace جعل کند.

پیش نیازها

  • یک دامنه Google Workspace که مالک آن هستید، مانند mydomain.com یا mybusiness.com

  • یک توکن برنامه‌نویس Google Ads API و در صورت تمایل یک حساب آزمایشی

  • کتابخانه مشتری برای زبانی که استفاده می کنید

  • یک پروژه Google API Console که برای Google Ads API پیکربندی شده است

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

راه اندازی دسترسی به حساب سرویس

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

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

    کلید حساب سرویس را با فرمت JSON دانلود کنید و شناسه حساب سرویس را یادداشت کنید.

  2. شناسه حساب سرویس و محدوده API Google Ads ( https://www.googleapis.com/auth/adwords ) را با سرپرست دامنه خود به اشتراک بگذارید.

    از سرپرست دامنه بخواهید تا اختیارات دامنه را به حساب سرویس شما تفویض کند.

  3. اگر سرپرست دامنه هستید، دستورالعمل‌های مرکز راهنمایی را تکمیل کنید.

اکنون می توانید از حساب سرویس برای دسترسی به حساب Google Ads خود با جریان ادعایی OAuth 2.0 استفاده کنید.

پیکربندی کتابخانه مشتری

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

جاوا

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

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید.

دات نت

کلیدهای زیر را در App.config / Web.config خود پیکربندی کنید. برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید. 

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

پایتون

مسیر JSON کلید خصوصی و ایمیل جعل شده را در پیکربندی خود تنظیم کنید. اگر از google-ads.yaml file ، رشته YAML یا dict استفاده می کنید، موارد زیر را اضافه کنید: 

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

کلیدهای زیر را در google_ads_php.ini خود پیکربندی کنید. برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید. 

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

یاقوت سرخ

کلیدهای زیر را در google_ads_config.rb خود پیکربندی کنید. 

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

پرل

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

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

نگرانی های امنیتی

از آنجایی که حساب سرویس دارای کنترل تفویض اختیار در سطح دامنه برای دامنه Google Workspace شما است، مهم است که از فایل کلیدی محافظت کنید که به حساب سرویس اجازه می دهد به خدمات Google که برای آن مجاز است دسترسی پیدا کند. این امر به ویژه از آنجایی صادق است که آن حساب سرویس توانایی جعل هویت هر کاربر در دامنه را دارد.

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

،

این راهنما نحوه دسترسی به Google Ads API با حساب‌های سرویس را مورد بحث قرار می‌دهد.

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

حساب‌های سرویس از یک جریان OAuth 2.0 استفاده می‌کنند که نیازی به مجوز انسانی ندارد و در عوض از یک فایل کلیدی استفاده می‌کنند که فقط برنامه شما می‌تواند به آن دسترسی داشته باشد.

استفاده از حساب های خدماتی دو مزیت کلیدی دارد:

  • مجوز دسترسی به Google API به عنوان یک مرحله پیکربندی انجام می‌شود، بنابراین از عوارض مرتبط با سایر جریان‌های OAuth 2.0 که به تعاملات کاربر نیاز دارند، اجتناب می‌شود.

  • جریان ادعای OAuth 2.0 به برنامه شما امکان می‌دهد در صورت لزوم جعل هویت کاربران دیگر را جعل کند.

دو راه برای مجوز دادن با حساب‌های سرویس وجود دارد: مستقیم یا با جعل هویت.

مجوز با دسترسی مستقیم به حساب

در این گزینه به حساب سرویس دسترسی مستقیم به حساب Google Ads خود می دهید.

راه اندازی دسترسی به حساب

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

    کلید حساب سرویس را با فرمت JSON دانلود کنید و شناسه حساب سرویس و ایمیل را یادداشت کنید.

  2. به عنوان سرپرست به حساب Google Ads خود وارد شوید. به Admin > Access and Security بروید.

  3. روی دکمه + در زیر تب کاربران کلیک کنید.

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

  5. به حساب سرویس دسترسی داده شده است.

پیکربندی کتابخانه مشتری

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

جاوا

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

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید.

دات نت

کلیدهای زیر را در App.config / Web.config خود پیکربندی کنید. برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

پایتون

مسیر JSON کلید خصوصی را در پیکربندی خود تنظیم کنید. اگر از google-ads.yaml file ، رشته YAML یا dict استفاده می کنید، موارد زیر را اضافه کنید:

json_key_file_path: JSON_KEY_FILE_PATH

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

کلیدهای زیر را در google_ads_php.ini خود پیکربندی کنید. برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

یاقوت سرخ

کلیدهای زیر را در google_ads_config.rb خود پیکربندی کنید.

c.keyfile = 'JSON_KEY_FILE_PATH'

پرل

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

jsonKeyFilePath=JSON_KEY_FILE_PATH

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

مجوز با استفاده از جعل هویت

در این گزینه شما جعل هویت کاربری می شوید که با استفاده از حساب سرویس به حساب Google Ads شما دسترسی دارد. این رویکرد فقط برای مشتریان Google Workspace کار می کند. یک حساب سرویس فقط می‌تواند هویت کاربران (آدرس ایمیل) را در همان Google Workspace جعل کند.

پیش نیازها

  • یک دامنه Google Workspace که مالک آن هستید، مانند mydomain.com یا mybusiness.com

  • یک توکن برنامه‌نویس Google Ads API و در صورت تمایل یک حساب آزمایشی

  • کتابخانه مشتری برای زبانی که استفاده می کنید

  • یک پروژه Google API Console که برای Google Ads API پیکربندی شده است

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

راه اندازی دسترسی به حساب سرویس

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

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

    کلید حساب سرویس را با فرمت JSON دانلود کنید و شناسه حساب سرویس را یادداشت کنید.

  2. شناسه حساب سرویس و محدوده API Google Ads ( https://www.googleapis.com/auth/adwords ) را با سرپرست دامنه خود به اشتراک بگذارید.

    از سرپرست دامنه بخواهید تا اختیارات دامنه را به حساب سرویس شما تفویض کند.

  3. اگر سرپرست دامنه هستید، دستورالعمل‌های مرکز راهنمایی را تکمیل کنید.

اکنون می توانید از حساب سرویس برای دسترسی به حساب Google Ads خود با جریان ادعایی OAuth 2.0 استفاده کنید.

پیکربندی کتابخانه مشتری

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

جاوا

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

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید.

دات نت

کلیدهای زیر را در App.config / Web.config خود پیکربندی کنید. برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید. 

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

پایتون

مسیر JSON کلید خصوصی و ایمیل جعل شده را در پیکربندی خود تنظیم کنید. اگر از google-ads.yaml file ، رشته YAML یا dict استفاده می کنید، موارد زیر را اضافه کنید: 

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

کلیدهای زیر را در google_ads_php.ini خود پیکربندی کنید. برای جزئیات بیشتر به راهنمای پیکربندی مراجعه کنید. 

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

یاقوت سرخ

کلیدهای زیر را در google_ads_config.rb خود پیکربندی کنید. 

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

پرل

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

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

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

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

نگرانی های امنیتی

از آنجایی که حساب سرویس دارای کنترل تفویض اختیار در سطح دامنه برای دامنه Google Workspace شما است، مهم است که از فایل کلیدی محافظت کنید که به حساب سرویس اجازه می دهد به خدمات Google که برای آن مجاز است دسترسی پیدا کند. این امر به ویژه از آنجایی صادق است که آن حساب سرویس توانایی جعل هویت هر کاربر در دامنه را دارد.

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