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

Google Ads API، مانند دیگر Google APIها، از پروتکل 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 کاربر استفاده کند. کتابخانه Python به‌صورت زیر پیکربندی شده است:

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

  json_key_file_path: JSON_KEY_FILE_PATH
  # Optional: only set if using Google Workspace domain-wide delegation:
  # impersonated_email: IMPERSONATED_EMAIL
  

  سپس روش‌های 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 یا تنظیم‌نشده باشد، و کلیدهای اطلاعات کاربری کاربر OAuth (client_id، client_secret، و refresh_token) تنظیم‌نشده یا به‌صورت نظر باشد، کتابخانه به‌طور خودکار بااستفاده از جریان حساب سرویس مجوز می‌دهد.

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

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

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

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_application_default_credentials": True,
       # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

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

   export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS=true
   

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

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

اگر کدهای OAuth را مستقیماً مدیریت می‌کنید

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

2. کتابخانه کارخواه Python را در دستگاهتان شبیه‌سازی کنید و به دایرکتوری آن بروید:

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

3. نمونه را اجرا کنید و مسیر مطلق فایل JSON بارگیری‌شده در مرحله ۱ را ارائه دهید:

   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,
    use_proto_plus=True,
)

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

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

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