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

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

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

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

سير عمل OAuth

هناك ثلاثة من عمليات سير العمل الشائعة التي يتم استخدامها عند العمل مع واجهة برمجة التطبيقات مع "إعلانات Google".

سير عمل حساب الخدمة

ننصحك باستخدام سير العمل هذا إذا كان سير عملك لا يتطلّب أي تفاعل بشري. يتطلّب سير العمل هذا خطوة إعداد، حيث يضيف المستخدم حساب خدمة إلى حسابه على "إعلانات 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 لضبط المكتبة، أدرِج زوج القيم والمفتاح التالي واستخدِم الط101}ريقة 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 Ads API. هناك نهج شائع يتمثل في منح المستخدم إذن الوصول إلى حساب إداري على واجهة برمجة التطبيقات مع "إعلانات Google"، وربط جميع حسابات "إعلانات 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 لضبط المكتبة، أدرِج أزواج القيم والمفاتيح التالية واستخدِم الط101}ريقة 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.