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

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

مثل واجهات 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

بدلاً من ذلك، يمكنك استخدام gem 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

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

عملية مصادقة المستخدم الواحد

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

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

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

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

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

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

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

لاستخدام بيانات الاعتماد التلقائية للتطبيق، استخدِم أداة سطر أوامر 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.