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

مثل واجهات 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". لضبط هذا الإعداد، أنشئ ملف مفتاح JSON ونزِّله في Google Cloud Console، ثم انسخ google_ads_config.rb إلى الدليل الرئيسي وعدِّله لتحديد موقع ملف مفتاح حساب الخدمة (وعنوان البريد الإلكتروني الاختياري للمستخدم الذي سيتم انتحال هويته عند استخدام التفويض على مستوى النطاق في Google Workspace):

# You can also authenticate using a service account. If "keyfile" is
# specified below, then service account authentication will be assumed and
# the above authentication fields ignored. Read more about service account
# authentication here:
# https://developers.google.com/google-ads/api/docs/oauth/service-accounts
c.keyfile = 'path/to/keyfile.json'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

إذا كنت تفضّل عدم تخزين هذه المعلومات في ملف واستخدام متغيرات البيئة بدلاً من ذلك، يمكنك ضبط GOOGLE_ADS_JSON_KEY_FILE_PATH (وGOOGLE_ADS_IMPERSONATED_EMAIL الاختياري):

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

يمكنك أيضًا تمرير مسار ملف مفتاح حساب الخدمة (والبريد الإلكتروني الاختياري الذي تم انتحال هويته) آليًا في وقت التشغيل:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

بدلاً من ذلك، يمكنك استخدام حزمة googleauth لإنشاء بيانات اعتماد حساب الخدمة وتمرير credentials.updater_proc إلى config.authentication:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file.
key_file = '/path/to/your/service-account-key.json'

# Define the scopes needed for the Google Ads API.
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials.
credentials = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
end

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

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

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

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

يمكن ضبط بيانات اعتماد OAuth 2.0 لـ Ruby من خلال نسخ ملف google_ads_config.rb إلى الدليل الرئيسي وتعديله ليشمل معرّف العميل وسر العميل ورمز إعادة التحميل:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

يقرأ العميل تلقائيًا ملف الإعدادات من الدليل الرئيسي إذا تم إنشاء مثيل بدون وسيطات:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

بدلاً من ذلك، إذا كنت تفضّل تخزين الملف في مكان آخر، يمكنك إنشاء مثيل للعميل من خلال تمرير المسار إلى المكان الذي تحتفظ فيه بهذا الملف:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

إذا كنت تفضّل عدم تخزين هذه المعلومات في ملف واستخدام متغيرات البيئة بدلاً من ذلك، يمكنك ضبط كل منها على النحو التالي:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

يمكنك أيضًا تمرير المعلومات آليًا في وقت التشغيل:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

يُرجى الرجوع إلى دليل سير عمل مصادقة المستخدم الفردي لمعرفة المزيد.

عملية المصادقة المتعدّدة المستخدمين

هذه هي خطوات العمل المقترَحة إذا كان تطبيقك يتيح للمستخدمين تسجيل الدخول والسماح لتطبيقك بإدارة حساباتهم على "إعلانات Google" نيابةً عنهم. ينشئ تطبيقك بيانات اعتماد المستخدمين الخاصة ببروتوكول OAuth 2.0 ويديرها. يمكن ضبط سير العمل هذا بشكل مشابه لسير عمل المستخدم الفردي، مع تحديد login_customer_id أيضًا.

ننصحك باستخدام ملف إعداد. انسخ الملف google_ads_config.rb إلى دليل الصفحة الرئيسية وعدِّله ليشمل معرّف العميل وسر العميل والرمز المميز لإعادة التحميل ومعرّف العميل:

# Authentication tells the API that you are allowed to make changes to the
# specific account you're trying to access.
# The default method of authentication is to use a refresh token, client id,
# and client secret to generate an access token.
c.client_id = 'INSERT_CLIENT_ID_HERE'
c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

# Required for manager accounts only: Specify the login customer ID used to
# authenticate API calls. This will be the customer ID of the authenticated
# manager account. If you need to use different values for this field, then
# make sure to fetch a new copy of the service after each time you change the
# value.
c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

يقرأ العميل تلقائيًا ملف الإعدادات من الدليل الرئيسي إذا تم إنشاء مثيل بدون وسيطات:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

بدلاً من ذلك، إذا كنت تفضّل تخزين الملف في مكان آخر، يمكنك إنشاء مثيل للعميل من خلال تمرير المسار إلى المكان الذي تحتفظ فيه بهذا الملف:

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

إذا كنت تفضّل عدم تخزين هذه المعلومات في ملف واستخدام متغيرات البيئة بدلاً من ذلك، يمكنك ضبط كل منها على النحو التالي:

export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

يمكنك أيضًا تمرير المعلومات آليًا في وقت التشغيل:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

يُرجى الرجوع إلى دليل سير عمل مصادقة تعدد المستخدمين لمعرفة المزيد. تتضمّن مكتبة برامج Ruby للعملاء مثالاً على الرمز البرمجي كمرجع. يوضّح مثال رمز سطر الأوامر GenerateUserCredentials كيفية الحصول على مصادقة المستخدم في وقت التشغيل لإدارة حساباته على "إعلانات Google" نيابةً عنه. يمكنك استخدام مثال الرمز هذا كمرجع لإنشاء تطبيقات على أجهزة الكمبيوتر تتطلّب مصادقة المستخدم.

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

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

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

بيانات الاعتماد التلقائية للتطبيق

تتيح مكتبة برامج Ruby (الإصدار 36.1.0 والإصدارات الأحدث) أيضًا المصادقة باستخدام بيانات الاعتماد التلقائية للتطبيق (ADC). تتيح لك هذه الطريقة ضبط بيانات الاعتماد التلقائية لتطبيقك بدون الحاجة إلى ضبط معلومات OAuth 2.0 ضمن إعدادات تطبيقك.

ويكون ذلك مفيدًا بشكل خاص عند التطوير على الجهاز أو عند التطوير باستخدام واجهات Google APIs المختلفة، إذ يمكنك إعادة استخدام بيانات الاعتماد نفسها، شرط أن يكون بإمكانها الوصول إلى نطاقات OAuth 2.0 المطلوبة.

بالنسبة إلى Google Ads API، تأكَّد من أنّ بيانات الاعتماد التلقائية لتطبيقك يمكنها الوصول إلى نطاق https://www.googleapis.com/auth/adwords OAuth 2.0.

لاستخدام بيانات الاعتماد التلقائية للتطبيق، استخدِم أداة سطر الأوامر في Google Cloud وقم بالمصادقة على بيانات الاعتماد التلقائية للتطبيق:

gcloud auth application-default login

يفتح هذا الأمر متصفّح ويب لإكمال عملية المصادقة لحساب Google. بعد الحصول على الإذن، يتم تخزين بيانات الاعتماد في موقع عادي. بعد ذلك، عليك تعديل تطبيقك لاستخدام ADC.

انسخ ملف google_ads_config.rb إلى دليل المنزل، واضبط use_application_default_credentials على true:

# You can also authenticate using Application Default Credentials (ADC).
# To understand how ADC discovers credentials in a given environment, see:
# https://developers.google.com/identity/protocols/application-default-credentials
c.use_application_default_credentials = true

إذا كنت تفضّل عدم تخزين هذه المعلومات في ملف واستخدام متغيرات البيئة بدلاً من ذلك، يمكنك ضبط ما يليGOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

يمكنك أيضًا تمرير المعلومات آليًا في وقت التشغيل. عند تهيئة العميل في رمز Ruby، اضبط config.use_application_default_credentials = true ولا تقدّم بيانات اعتماد OAuth 2.0 صريحة. ترصد المكتبة تلقائيًا بيانات الاعتماد التي تم إعدادها بواسطة أداة سطر الأوامر في Google Cloud وتستخدمها:

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = 'YOUR_LOGIN_CUSTOMER_ID'

  # Do NOT include client_id, client_secret, or refresh_token here.
end

يُرجى الرجوع إلى صفحة الإعداد للحصول على مزيد من التفاصيل حول الخيارات المتاحة لإعداد مكتبة برامج Ruby.