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

مثل واجهات 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 إلى الدليل الرئيسي وعدِّله لتحديد موقع ملف مفتاح حساب الخدمة وعنوان البريد الإلكتروني للمستخدم الذي تريد انتحال هويته:

  # 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'
  # 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"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

يمكنك أيضًا تمرير المعلومات آليًا في وقت التشغيل، وذلك باستخدام googleauth gem لإنشاء بيانات اعتماد من ملف JSON لحساب الخدمة:

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 = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

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

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

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

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

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

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  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 إلى الدليل الرئيسي وعدِّله ليشمل الرمز المميز للمطوّر ومعرّف العميل وسر العميل ورمز التحديث ورقم تعريف العميل:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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 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_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
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.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  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 كيفية استرداد قائمة بجميع الحسابات التي يمكن للمستخدم الوصول إليها مباشرةً. يمكن بعد ذلك استخدام هذه الحسابات كقيم صالحة للإعداد LoginCustomerId.

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

تتيح مكتبة برامج Ruby أيضًا المصادقة باستخدام بيانات الاعتماد التلقائية للتطبيق (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 على "صحيح":

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # 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_DEVELOPER_TOKEN وGOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

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

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # 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 oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

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