حسابات الخدمة

يتناول هذا الدليل كيفية الوصول إلى Google Ads API باستخدام حسابات الخدمة.

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

تستخدِم حسابات الخدمة مسار OAuth 2.0 الذي لا يتطلّب تفويضًا من أحد الأشخاص، بل يستخدم بدلاً من ذلك ملف مفتاح يمكن لتطبيقك فقط الوصول إليه.

يقدّم استخدام حسابات الخدمة ميزتَين رئيسيتين:

  • يتم منح التفويض للوصول إلى Google API كخطوة إعداد، وبالتالي تجنُّب التعقيدات المرتبطة بعمليات OAuth 2.0 الأخرى التي تتطلّب تفاعلات المستخدمين.

  • يتيح مسار تأكيد OAuth 2.0 لتطبيقك انتحال هوية مستخدمين آخرين إذا كان ذلك ضروريًا.

هناك طريقتان للتفويض باستخدام حسابات الخدمة: مباشرةً أو باستخدام انتحال الهوية.

التفويض بالوصول المباشر إلى الحساب

في هذا الخيار، تمنح حساب الخدمة إذن الوصول المباشر إلى حسابك على "إعلانات Google".

إعداد إمكانية الوصول إلى الحساب

  1. ابدأ بـ إنشاء حساب خدمة وبيانات اعتماد.

    نزِّل مفتاح حساب الخدمة بتنسيق JSON وسجِّل معرّف حساب الخدمة والبريد الإلكتروني.

  2. سجِّل الدخول إلى حسابك على "إعلانات Google" كمشرف. انتقِل إلى المشرف > الوصول والأمان.

  3. انقر على الزر + ضمن علامة التبويب المستخدمون.

  4. اكتب عنوان البريد الإلكتروني لحساب الخدمة في مربّع إدخال البريد الإلكتروني. اختَر مستوى الوصول المناسب إلى الحساب وانقر على الزر إضافة حساب . يُرجى العِلم أنّ مستويات الوصول "البريد الإلكتروني" و"المشرف" غير متاحة لحسابات الخدمة.

  5. يتم منح حساب الخدمة إذن الوصول.

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

اختَر علامة التبويب التي تتوافق مع لغة البرمجة للحصول على تعليمات حول كيفية ضبط مكتبة العميل.

Java

اضبط مسار مفتاح JSON الخاص في الإعدادات. إذا كنت تستخدم ملفًا بتنسيق ads.properties، أضِف ما يلي:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH

راجِع دليل الإعداد للاطّلاع على تفاصيل إضافية.

NET.

اضبط المفاتيح التالية في App.config / Web.config. اطّلِع على دليل الإعداد للحصول على تفاصيل إضافية.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

Python

اضبط مسار مفتاح JSON الخاص في الإعدادات. إذا كنت تستخدم google-ads.yaml file أو سلسلة YAML أو dict، أضِف ما يلي:

json_key_file_path: JSON_KEY_FILE_PATH

إذا كنت تستخدم متغيّرات البيئة، أضِف ما يلي إلى إعدادات Bash أو بيئته:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

PHP

اضبط المفاتيح التالية في google_ads_php.ini. اطّلِع على دليل الإعداد للحصول على تفاصيل إضافية.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Ruby

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

c.keyfile = 'JSON_KEY_FILE_PATH'

Perl

اضبط مسار ملف JSON للمفتاح الخاص ومعرّف الحساب المفوَّض في الإعدادات. إذا كنت تستخدم ملفًا بتنسيق googleads.properties، أضِف ما يلي:

jsonKeyFilePath=JSON_KEY_FILE_PATH

إذا كنت تستخدم متغيّرات البيئة، أضِف ما يلي إلى إعدادات Bash أو بيئته:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH

التفويض باستخدام انتحال الهوية

في هذا الخيار، تنتحل هوية مستخدم لديه إذن الوصول إلى حسابك على "إعلانات Google" باستخدام حساب الخدمة. لا تعمل هذه الطريقة إلا مع عملاء Google Workspace . لا يمكن لحساب الخدمة انتحال هوية المستخدمين (عناوين البريد الإلكتروني) إلا في Google Workspace نفسه.

المتطلبات الأساسية

  • نطاق Google Workspace تملكه، مثل mydomain.com أو mybusiness.com

  • رمز مميّز للمطوّر لواجهة برمجة التطبيقات مع "إعلانات Google" وحساب تجريبي اختياري

  • مكتبة البرامج للغة التي تستخدمها

  • مشروع على Google API Console تم إعداده لأجل Google Ads API

  • مستخدم على "إعلانات Google" لديه أذونات في حساب "إعلانات Google" الذي تريد الوصول إليه. لا تتيح "إعلانات Google" استخدام حسابات الخدمة بدون انتحال الهوية.

إعداد الوصول إلى حساب الخدمة

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

  1. ابدأ بـ إنشاء حساب خدمة وبيانات اعتماد.

    نزِّل مفتاح حساب الخدمة بتنسيق JSON وسجِّل معرّف حساب الخدمة.

  2. شارِك مع مشرف نطاقك رقم تعريف حساب الخدمة ونطاق Google Ads API (https://www.googleapis.com/auth/adwords).

    اطلب من مشرف النطاق تفويض السلطة على مستوى النطاق لحساب الخدمة.

  3. إذا كنت مشرف النطاق، أكمِل تعليمات مركز المساعدة.

يمكنك الآن استخدام حساب الخدمة للوصول إلى حسابك على "إعلانات Google" باستخدام مسار تأكيد OAuth 2.0.

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

اختَر علامة التبويب التي تتوافق مع لغة البرمجة للحصول على تعليمات حول كيفية ضبط مكتبة العميل.

Java

اضبط مسار ملف JSON للمفتاح الخاص ومعرّف الحساب المفوَّض في الإعدادات. إذا كنت تستخدم ملف ads.properties، أضِف ما يلي:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.serviceAccountUser=IMPERSONATED_EMAIL

راجِع دليل الإعداد للاطّلاع على تفاصيل إضافية.

NET.

اضبط المفاتيح التالية في App.config / Web.config. اطّلِع على دليل الإعداد للحصول على تفاصيل إضافية.

<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="JSON_KEY_FILE_PATH" />

<!-- Supply the email address of the user to impersonate. -->
<add key="OAuth2PrnEmail" value="IMPERSONATED_EMAIL" />

Python

اضبط مسار مفتاح JSON الخاص والبريد الإلكتروني الذي يتم انتحال هويته في الإعدادات. إذا كنت تستخدم google-ads.yaml file أو سلسلة YAML أو dict، أضِف ما يلي:

json_key_file_path: JSON_KEY_FILE_PATH
impersonated_email: IMPERSONATED_EMAIL

إذا كنت تستخدم متغيّرات البيئة، أضِف ما يلي إلى إعدادات Bash أو بيئته:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

PHP

اضبط المفاتيح التالية في google_ads_php.ini. اطّلِع على دليل الإعداد للحصول على تفاصيل إضافية.

; For service account flow.
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"
impersonatedEmail = "IMPERSONATED_EMAIL"

Ruby

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

c.keyfile = 'JSON_KEY_FILE_PATH'
c.impersonate = 'IMPERSONATED_EMAIL'

Perl

اضبط مسار ملف JSON للمفتاح الخاص ومعرّف الحساب المفوَّض في الإعدادات. إذا كنت تستخدم ملفًا بتنسيق googleads.properties، أضِف ما يلي:

jsonKeyFilePath=JSON_KEY_FILE_PATH
impersonatedEmail=IMPERSONATED_EMAIL

إذا كنت تستخدم متغيّرات البيئة، أضِف ما يلي إلى إعدادات Bash أو بيئته:

export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
export GOOGLE_ADS_IMPERSONATED_EMAIL=IMPERSONATED_EMAIL

المخاوف المرتبطة بالأمان

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

من الممارسات الجيدة الأخرى السماح لحسابات الخدمة بالوصول إلى الحد الأدنى من مجموعة واجهات برمجة التطبيقات المطلوبة فقط. هذا إجراء وقائي للحد من كمية البيانات التي يمكن للمهاجم الوصول إليها في حال اختراق ملف مفتاح حساب الخدمة.