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

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

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

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

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

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

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

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

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

  json_key_file_path: JSON_KEY_FILE_PATH
  

  سپس متدهای load_from_storage یا load_from_string را فراخوانی کنید:

  from google.ads.googleads.client import GoogleAdsClient
  client = GoogleAdsClient.load_from_storage()
  

• اگر از یک dict برای پیکربندی کتابخانه استفاده می‌کنید، جفت کلید-مقدار زیر را وارد کنید و متد load_from_dict را فراخوانی کنید و dict پیکربندی را به آن ارسال کنید:

  from google.ads.googleads.client import GoogleAdsClient
  
  configuration = {
    # ...
    "json_key_file_path": JSON_KEY_FILE_PATH
    # ...
  }
  
  client = GoogleAdsClient.load_from_dict(configuration)
  

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

  export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
  

  سپس متد load_from_env را فراخوانی کنید:

  from google.ads.googleads.client import GoogleAdsClient
  client = GoogleAdsClient.load_from_env()
    ```
  

اگر گزینه پیکربندی json_key_file_path در هر یک از این متدهای پیکربندی وجود داشته باشد، و گزینه use_application_default_credentials False یا unset باشد، کتابخانه به طور خودکار با استفاده از جریان حساب سرویس، مجوزدهی را انجام می‌دهد.

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

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

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

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

2. کاربر ابزاری مانند gcloud CLI یا نمونه کد generate_user_credentials را اجرا می‌کند تا به برنامه شما اجازه دهد تمام حساب‌های Google Ads خود را از طرف او مدیریت کند.

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

اگر از ابزار gcloud CLI استفاده می‌کنید (توصیه می‌شود)

1. برای تنظیم اعتبارنامه‌های پیش‌فرض برنامه (ADC) در محیط محلی خود، مستندات «ایجاد اعتبارنامه‌ها» را دنبال کنید.

2. پیکربندی زیر را به google-ads.yaml یا رشته YAML خود اضافه کنید:

   use_application_default_credentials: true
   

   سپس یکی از متدهای load_from_storage یا load_from_string را فراخوانی کنید:

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_storage()
   

   اگر از یک dict برای پیکربندی کتابخانه استفاده می‌کنید، جفت کلید-مقدار زیر را وارد کرده و متد load_from_dict را فراخوانی کنید:

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
     # ...
     "use_account_default_credentials": True
     # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

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

   export GOOGLE_ADS_USE_ACCOUNT_DEFAULT_CREDENTIALS=true
   

   سپس متد load_from_env را فراخوانی کنید:

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_env()
   

در صورت مدیریت مستقیم توکن‌های OAuth

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

2. کتابخانه کلاینت پایتون را روی دستگاه خود کلون کنید و به دایرکتوری آن بروید:

   $ git clone https://github.com/googleads/google-ads-python.git
   $ cd google-ads-python
   

3. مثال را اجرا کنید و مسیر مطلق فایل JSON دانلود شده در مرحله 1 را ارائه دهید:

   $ python examples/authentication/generate_user_credentials.py -c PATH_TO_CREDENTIALS_JSON
   

   پس از تکمیل، یک توکن به‌روزرسانی در کنسول شما چاپ می‌شود. آن را کپی کرده و برای مرحله بعدی ذخیره کنید.

4. با اضافه کردن تنظیمات زیر به پیکربندی مورد نظر خود، کتابخانه را پیکربندی کنید:

   پیکربندی زیر را به google-ads.yaml یا رشته YAML خود اضافه کنید:

   client_id: INSERT_OAUTH2_CLIENT_ID_HERE
   client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
   refresh_token: INSERT_REFRESH_TOKEN_HERE
   

   سپس یکی از متدهای load_from_storage یا load_from_string را فراخوانی کنید:

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_storage()
   

   اگر از یک dict برای پیکربندی کتابخانه استفاده می‌کنید، جفت‌های کلید-مقدار زیر را وارد کرده و متد load_from_dict را فراخوانی کنید:

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
     # ...
     "client_id": INSERT_OAUTH2_CLIENT_ID_HERE
     "client_secret": INSERT_OAUTH2_CLIENT_SECRET_HERE
     "refresh_token": INSERT_REFRESH_TOKEN_HERE
     # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

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

   export GOOGLE_ADS_CLIENT_ID=INSERT_OAUTH2_CLIENT_ID_HERE
   export GOOGLE_ADS_CLIENT_SECRET=INSERT_OAUTH2_CLIENT_SECRET_HERE
   export GOOGLE_ADS_REFRESH_TOKEN=INSERT_REFRESH_TOKEN_HERE
   

   سپس متد load_from_env را فراخوانی کنید:

   from google.ads.googleads.client import GoogleAdsClient
   client = GoogleAdsClient.load_from_env()
   

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

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

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

یک dict ساده‌ترین مکانیزم پیکربندی برای استفاده هنگام دریافت اعتبارنامه‌ها در زمان اجرا است:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
  # ...
  "client_id": client_id
  "client_secret": client_secret
  "refresh_token": refresh_token
  # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

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

شما می‌توانید با هر رویکردی اعتبارنامه‌های احراز هویت را تولید کنید و با نمونه‌سازی مستقیم کلاس کلاینت، آنها را به صورت دستی در اختیار GoogleAdsClient قرار دهید. با فرض اینکه شیء اعتبارنامه‌ای که ایجاد می‌کنید نمونه‌ای از google.auth.credentials.Credentials است، می‌توانید آن را به صورت زیر ارسال کنید:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`
credentials = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
  credentials=credentials,
  # ... insert remaining parameters
)

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

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

1. مثال کد get_account_hierarchy نحوه بازیابی لیست همه حساب‌های کاربری تحت یک حساب مدیریت تبلیغات گوگل را نشان می‌دهد.
2. مثال کد list_accessible_customers نحوه بازیابی لیست تمام حساب‌هایی را که یک کاربر به آنها دسترسی مستقیم دارد، نشان می‌دهد. سپس می‌توان از این حساب‌ها به عنوان مقادیر معتبر برای تنظیم login_customer_id استفاده کرد.