المصادقة والتفويض

مثل واجهات Google APIs الأخرى، تستخدم واجهة Google Ads API بروتوكول OAuth 2.0 للمصادقة والتفويض. يتيح بروتوكول OAuth 2.0 لتطبيق عميل Google Ads API الوصول إلى حساب أحد المستخدمين على "إعلانات Google" بدون الحاجة إلى معالجة معلومات تسجيل الدخول الخاصة بالمستخدم أو تخزينها.

التعرّف على نموذج الوصول إلى "إعلانات Google"

للعمل بفعالية مع Google Ads API، عليك فهم طريقة عمل نموذج الوصول إلى "إعلانات Google". ننصحك بقراءة دليل نموذج الوصول إلى "إعلانات Google".

سير عمل OAuth

هناك ثلاث طرق شائعة لسير العمل تُستخدَم عند التعامل مع Google Ads API.

تدفّق حساب الخدمة

هذا هو سير العمل المقترَح إذا كان سير العمل لا يتطلّب أي تفاعل بشري. يتطلّب سير العمل هذا خطوة إعداد، حيث يضيف المستخدم حساب خدمة إلى حسابه على "إعلانات Google". يمكن للتطبيق بعد ذلك استخدام بيانات اعتماد حساب الخدمة لإدارة حساب المستخدم على "إعلانات Google". يتم ضبط مكتبة Python على النحو التالي:

• في حال استخدام ملف 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 أو لم يتم ضبطه، ستتم المصادقة تلقائيًا باستخدام مسار حساب الخدمة.

لمزيد من المعلومات، يُرجى الرجوع إلى دليل سير عمل حساب الخدمة.

عملية مصادقة المستخدم الفردي

يمكن استخدام سير العمل هذا إذا لم يكن بإمكانك استخدام حسابات الخدمة. يتطلّب سير العمل هذا خطوتَين لإعداده:

1. امنح مستخدمًا واحدًا إذن الوصول إلى جميع الحسابات التي ستتم إدارتها باستخدام واجهة برمجة التطبيقات مع "إعلانات Google". ويتمثل أحد الأساليب الشائعة في منح المستخدم إذن الوصول إلى حساب إداري على Google Ads API، وربط جميع حسابات "إعلانات Google" ضِمن هذا الحساب الإداري.

2. يستخدم المستخدم أداة مثل gcloud CLI أو generate_user_credentials مثال الرمز البرمجي للسماح لتطبيقك بإدارة جميع حساباته على "إعلانات Google" نيابةً عنه.

يمكن تهيئة المكتبة باستخدام بيانات اعتماد 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. استنسِخ مكتبة برامج Python إلى جهازك وانتقِل إلى الدليل الخاص بها:

   $ 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" نيابةً عنهم. ينشئ تطبيقك بيانات اعتماد المستخدمين في 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
)

ماذا لو كان المستخدم يدير حسابات متعددة؟

من الشائع أن يدير المستخدم أكثر من حساب على "إعلانات Google"، إما من خلال الوصول المباشر إلى الحسابات أو من خلال حساب إداري على "إعلانات Google". توفّر مكتبة برامج Python للعملاء أمثلة الرموز البرمجية التالية التي توضّح كيفية التعامل مع هذه الحالات.

1. يوضّح مثال الرمز البرمجي get_account_hierarchy كيفية استرداد قائمة بجميع الحسابات ضمن حساب إداري على "إعلانات Google".
2. يوضّح مثال الرمز list_accessible_customers كيفية استرداد قائمة بجميع الحسابات التي يمكن للمستخدم الوصول إليها مباشرةً. ويمكن بعد ذلك استخدام هذه الحسابات كقيم صالحة للإعداد login_customer_id.