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

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

  • يمكنك منح مستخدم واحد إذن الوصول إلى جميع حسابات "إعلانات Google" التي يجب أن يديرها التطبيق.
  • يسمح المستخدم لتطبيقك بإدارة حساباته على "إعلانات Google" نيابةً عنه، وبالتالي يمنح التطبيق إذن الوصول إلى جميع حسابات "إعلانات Google".

بما أنّ هناك مستخدمًا واحدًا فقط، يمكنك الاعتماد على أدوات مثل gcloud CLI أو مثال رمز GenerateUserCredential بدلاً من إنشاء مسار مصادقة مستخدم OAuth 2.0 الخاص بك.

من حالات الاستخدام ذات الصلة بسير العمل هذا عندما يمكن الوصول إلى حساباتك من خلال عدد قليل من عمليات تسجيل دخول المستخدمين (على سبيل المثال، من 3 إلى 4 مستخدمين)، لذا فإنّ جهد التطوير لإنشاء سير عمل كامل لمصادقة OAuth متعددة المستخدمين ليس مبررًا مقارنةً بالجهد المبذول للحصول على تفويض لـ 3 إلى 4 مستخدمين باستخدام أداة سطر أوامر مثل gcloud CLI.

السلبيات

هناك بعض العيوب في هذا المسار مقارنةً بسير عمل حساب الخدمة:

  • يتطلّب سير عمل مصادقة المستخدم إنشاء معرِّف عميل وسر OAuth 2.0 في Google API Console، ما يتطلّب خطوات ضبط أكثر من إنشاء حساب خدمة ومفتاح.
  • إذا غادر المستخدم المفوَّض الفريق أو الشركة، قد يتوقف تطبيقك عن العمل إذا أزلت المستخدم من حساباتك أو أوقفت حسابه. لا ترتبط حسابات الخدمة بمستخدمين فرديين، لذلك يتم تجنُّب هذا الخطر.
  • للحماية من اختراق الحسابات من خلال البرامج الضارة أو التصيّد الاحتيالي، على المستخدم الذي يمنح الإذن بالوصول إلى حساب "إعلانات Google" إجراء المصادقة باستخدام مفتاح مرور عند إنشاء الرموز المميّزة لإعادة التحميل في OAuth 2.0. لا تتطلّب حسابات الخدمة مفاتيح مرور، وهي أقل عرضة للهجمات الموجّهة للمستخدمين، مثل التصيّد الاحتيالي.

إنشاء بيانات الاعتماد

  1. اضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth لتطبيقك وأضِف https://www.googleapis.com/auth/adwords كنطاق OAuth 2.0. لمعرفة التفاصيل، يُرجى الاطّلاع على مقالة إعداد شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth.

  2. أنشئ معرّف عميل وسر عميل باتّباع التعليمات. بعد إنشاء عميل OAuth 2.0، نزِّل ملف JSON الخاص بالعميل من خلال النقر على الزر تنزيل JSON في مربّع حوار التأكيد. احفظ الملف باسم credentials.json.

  3. حدِّد حساب مستخدم لديه إذن الوصول إلى جميع حسابات "إعلانات Google" التي تريد إدارتها باستخدام تطبيقك. إذا كانت هناك حسابات لا تملك إذن الوصول، امنح إذن الوصول إلى الحساب لذلك المستخدم. يُرجى التأكّد من أنّ حساب المستخدم هذا قد أعدّ مفتاح مرور (قد يتم تطبيق مدة انتظار لأغراض أمنية لـ 7 أيام قبل أن يصبح مفتاح المرور الذي تم إنشاؤه حديثًا موثوقًا).

  4. نزِّل gcloud CLI وثبِّته. بعد التثبيت، يُرجى التحقّق من أنّ الأداة تعمل بشكل صحيح من خلال تنفيذ الأمر gcloud version من موجّه سطر الأوامر. تظهر النتيجة مشابهة لما يلي:

    gcloud version
    Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0

  5. أنشِئ رمزًا مميزًا لإعادة التحميل في OAuth 2.0 من خلال تشغيل أداة gcloud CLI باستخدام ملف credentials.json من الخطوة السابقة. يجب تمرير المَعلمة --client-id-file ليتم إصدار الرمز المميز لإعادة التحميل ضمن مشروعك في Google API Console بدلاً من مشروع gcloud CLI التلقائي:

    gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
  --client-id-file=PATH_TO_CREDENTIALS_JSON

  6. يفتح الأمر gcloud نافذة تسجيل الدخول إلى حساب Google في نافذة متصفّح جديدة وينقلك إلى خطوات مصادقة OAuth 2.0. سجِّل الدخول بصفتك المستخدم الذي اخترته في الخطوات السابقة وأثبِت هويتك باستخدام مفتاح مرور. إذا كان تطبيقك غير متحقق منه، قد تظهر لك شاشة تحذير. في هذه الحالات، يمكنك النقر على الرابط إعدادات متقدّمة ثم على الخيار الانتقال إلى PROJECT_NAME (غير آمن).

  7. بعد التحقّق من النطاقات، انقر على الزر متابعة لمنح الإذن. ينتقل المتصفّح إلى https://cloud.google.com/sdk/auth_success، ما يشير إلى أنّ المصادقة تمت بنجاح. تعرض الصفحة الرسالة التالية:

    Authorization code granted. Close this tab.

    يطبع الأمر gcloud الرسالة التالية:

    Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]

    افتح ملف application_default_credentials.json. محتوياته مشابهة لما يلي:

    {
  "account": "",
  "client_id": "******.apps.googleusercontent.com",
  "client_secret": "******",
  "refresh_token": "******",
  "type": "authorized_user",
  "universe_domain": "googleapis.com"
}

إعداد مكتبة العميل

اختَر علامة التبويب المقابلة للغة البرمجة التي تستخدمها للحصول على تعليمات حول كيفية ضبط مكتبة العميل. إذا كان المستخدِم المفوَّض يصل إلى حسابات العملاء من خلال حساب إداري على "إعلانات Google"، اضبط login-customer-id (أو loginCustomerId) على رقم تعريف العميل المكوَّن من 10 أرقام لهذا الحساب الإداري بدون واصلات.

جافا

اضبط المفاتيح التالية في ملف ads.properties.

api.googleads.clientId=INSERT_OAUTH2_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

يُرجى الاطّلاع على دليل الإعداد لمعرفة الخيارات الإضافية.

NET.

اضبط بيانات اعتماد OAuth 2.0 في مثيل GoogleAdsConfig واستخدِمها لإعداد عنصر GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
};
GoogleAdsClient client = new GoogleAdsClient(config);

يُرجى الاطّلاع على دليل الإعداد لمعرفة الخيارات الإضافية.

Python

اضبط المفاتيح التالية في ملف google-ads.yaml.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
use_proto_plus: True

يُرجى الاطّلاع على دليل الإعداد لمعرفة الخيارات الإضافية.

PHP

اضبط المفاتيح التالية في ملف google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

يُرجى الاطّلاع على دليل الإعداد لمعرفة الخيارات الإضافية.

Ruby

اضبط المفاتيح التالية في ملف google_ads_config.rb.

Google::Ads::GoogleAds::Config.new do |c|
  c.client_id = 'INSERT_OAUTH2_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

يُرجى الاطّلاع على دليل الإعداد لمعرفة الخيارات الإضافية.

Perl

اضبط المفاتيح التالية في ملف googleads.properties.

clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

يُرجى الاطّلاع على دليل الإعداد لمعرفة الخيارات الإضافية.

curl

ابدأ باستخدام عميل HTTP لجلب رمز الدخول OAuth 2.0. يستخدم هذا الدليل الأمر curl.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://oauth2.googleapis.com/token

يمكنك استخدام رمز الدخول في طلبات البيانات من واجهة برمجة التطبيقات. يوضّح المثال التالي كيفية تنفيذ تقرير حملة باستخدام طريقة GoogleAdsService.SearchStream لاسترداد الحملات في حسابك. لا يتناول هذا الدليل تفاصيل إعداد التقارير.

curl -i -X POST \
  https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

محتوى query.json هو كما يلي:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}
السابق
نظرة عامة
التالي
مسار عمل المصادقة المتعدّدة المستخدمين