يجب توفّر بيانات اعتماد OAuth 2.0 ورمز مميز للمطوّر عند إجراء طلب إلى Google Ads API. إذا كنت تجري طلبات إلى واجهة برمجة التطبيقات باستخدام حساب إداري على "إعلانات Google"، عليك أيضًا تحديد عنوان login-customer-id مع كل طلب. توضّح هذه الصفحة كيفية ضبط هذه القيم وتتضمّن مستندات حول العديد من عناوين HTTP الإضافية الخاصة بواجهة برمجة التطبيقات والتي يتم إرسالها واستلامها عند استخدام واجهة REST.
بيانات اعتماد OAuth 2.0
تستخدم Google Ads API بروتوكول OAuth 2.0 للموافقة على طلبات واجهة برمجة التطبيقات. يتوفّر كل من مسار مصادقة المستخدم في OAuth 2.0 ومسار حساب الخدمة. لمزيد من التفاصيل، اطّلِع على بروتوكول OAuth 2.0 في Google Ads API.
إذا كنت جديدًا على Google APIs، يمكنك استخدام gcloud CLI أو مساحة بروتوكول OAuth 2.0 لتجربة بيانات اعتماد OAuth 2.0 وGoogle Ads API قبل كتابة الرمز البرمجي لتطبيقك.
ننصحك باستخدام إحدى مكتبات OAuth 2.0 المتوفّرة على https://oauth.net/code/ لتنفيذ إجراءات الموافقة في OAuth 2.0. ومع ذلك، أدرجنا تعليمات curl في حال أردت تنفيذها بنفسك.
حسابات الخدمة
اتّبِع الخطوات اللازمة لإعداد مشروع على Google Cloud لواجهة برمجة التطبيقات Google Ads API. سجِّل البريد الإلكتروني لحساب الخدمة ومفتاح حساب الخدمة. بعد ذلك، اتّبِع التعليمات الشائعة في دليل حسابات الخدمة لإعداد حساب الخدمة من أجل الوصول إلى حسابك على "إعلانات Google".
مصادقة المستخدم
اتّبِع الخطوات لإعداد مشروع على Google Cloud Console من أجل
Google Ads API. سجِّل معرّف العميل وسر العميل. بعد ذلك، اتّبِع تعليمات مسار تطبيق الكمبيوتر أو تعليمات مسار تطبيق الويب لإنشاء رمز إعادة تحميل ورمز وصول. scope هو https://www.googleapis.com/auth/adwords.
إنشاء رموز دخول جديدة
حسابات الخدمة
بعد الحصول على عنوان البريد الإلكتروني لحساب الخدمة ومفتاح حساب الخدمة، اتّبِع دليل استخدام بروتوكول OAuth 2.0 للتطبيقات من خادم إلى خادم لإنشاء مجموعة طلبات JWT، والتي يمكن استبدالها بعد ذلك للحصول على رمز وصول OAuth 2.0 المميز. احرص على اختيار علامة التبويب HTTP/REST أثناء اتّباع الدليل. نطاق OAuth 2.0 scope المستخدَم للوصول إلى واجهة برمجة التطبيقات مع "إعلانات Google" هو
https://www.googleapis.com/auth/adwords. بالإضافة إلى ذلك، يمكنك تخطّي المَعلمة
sub عند إنشاء مجموعة مطالبات JWT، لأنّ خطوات الإعداد
تمنح حساب الخدمة إذن الوصول المباشر إلى حساب "إعلانات Google"، وبالتالي
تجنُّب الحاجة إلى انتحال هوية مستخدم في "إعلانات Google".
بعد ذلك، يمكنك استخدام رمز الدخول في عنوان HTTP Authorization لكل طلب يتم إرساله إلى واجهة برمجة التطبيقات مع "إعلانات Google":
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
مصادقة المستخدم
بعد الحصول على معرّف العميل وسر العميل ورمز إعادة التحميل لبروتوكول 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://www.googleapis.com/oauth2/v3/tokenبعد ذلك، يمكنك استخدام رمز الدخول الذي يعرضه طلب curl في عنوان HTTP Authorization لكل طلب يتم إرساله إلى Google Ads API:
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
عناوين الطلبات
الرمز المميز للمطوِّر
تتطلّب Google Ads API أيضًا رمزًا مميزًا للمطوِّر لإجراء طلبات إلى واجهة برمجة التطبيقات. إذا كان لديك رمز مميز للمطوِّر، يمكنك العثور عليه من خلال الانتقال إلى https://ads.google.com/aw/apicenter. سجِّل الدخول إلى حسابك الإداري على "إعلانات Google" إذا طُلب منك ذلك. إذا لم يكن لديك رمز مميّز، اتّبِع التعليمات للاشتراك للحصول على رمز مميّز للمطوّرين.
يجب تضمين قيمة الرمز المميز للمطوِّر في عنوان developer-token HTTP
لكل طلب يتم إرساله إلى واجهة برمجة التطبيقات مع "إعلانات Google":
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
معرّف تسجيل الدخول للعميل
بالنسبة إلى طلبات Google Ads API التي يقدّمها حساب إداري إلى حساب عميل (أي عند تسجيل الدخول كحساب إداري لتقديم طلبات API إلى أحد حسابات العملاء)، عليك أيضًا تقديم عنوان HTTP login-customer-id. تمثّل هذه القيمة رقم تعريف العميل على "إعلانات Google" الخاص بالمدير الذي يجري طلب البيانات من واجهة برمجة التطبيقات.
إنّ تضمين هذا العنوان يعادل اختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة. عند تحديد رقم تعريف العميل، احرص على إزالة أي شرطات (-).
على سبيل المثال: 1234567890، وليس 123-456-7890. راجِع دليل نموذج الوصول إلى "إعلانات Google" لمعرفة المزيد عن الرقم التعريفي للعميل المستخدَم في تسجيل الدخول.
GET /v22/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
الرقم التعريفي للعميل المرتبط
لا يتم استخدام عنوان Linked customer ID إلا من قِبل [مقدّمي خدمة إحصاءات التطبيقات التابعين لجهات خارجية عند تحميل الإحالات الناجحة إلى حساب مرتبط على "إعلانات Google". لمزيد من التفاصيل، راجِع دليل بنية طلبات البيانات من واجهة برمجة التطبيقات.
...
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
linked-customer-id: LINKED_CUSTOMER_ID
عناوين الاستجابة
يتم عرض العناوين التالية في استجابات HTTP من واجهة برمجة التطبيقات.
معرّف الطلب
request-id هي سلسلة تحدّد طلب واجهة برمجة التطبيقات بشكلٍ فريد. عند تصحيح الأخطاء أو تحديد المشاكل وحلّها في ما يتعلّق بطلبات معيّنة من واجهة برمجة التطبيقات، يكون request-id معرّفًا مهمًا يجب توفّره عند التواصل مع فريق الدعم الخاص بالمطوّرين في Google.
request-id: 2a5Cj89VV7CNhya1DZjjrC