المصادقة والترخيص

مثل واجهات 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 الخاص بالمفتاح الخاص في بيئتك المحلية (بالإضافة إلى 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" بهذا الحساب الإداري.

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

يمكن إعداد المكتبة باستخدام بيانات اعتماد OAuth 2.0 الخاصة بالمستخدم على النحو التالي:

في حال استخدام أداة gcloud CLI (يُنصح بها)

ملاحظة: تتطلّب المصادقة باستخدام use_application_default_credentials google-ads v28.3.0 أو إصدار أحدث.

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 الذي تم تنزيله في الخطوة 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,
    use_proto_plus=True,
)

إدارة حسابات متعددة

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

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