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

  # 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 لإنشاء بيانات الاعتماد من ملف 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

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

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

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

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

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

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

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

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

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

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

gcloud auth application-default login

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

ننصحك باستخدام ملف إعداد. انسخ ملف 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.

المصادقة والتفويض تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.