يجب توفّر بيانات اعتماد 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 لاستخدام Google Ads API هو https://www.googleapis.com/auth/adwords.
إنشاء رموز دخول جديدة
حسابات الخدمة
بعد الحصول على عنوان البريد الإلكتروني لحساب الخدمة ومفتاح حساب الخدمة، اتّبِع دليل استخدام بروتوكول OAuth 2.0 للتطبيقات من خادم إلى خادم لإنشاء مجموعة طلبات JWT، والتي يمكن استبدالها بعد ذلك للحصول على رمز وصول OAuth 2.0 المميز. احرص على اختيار علامة التبويب HTTP/REST أثناء اتّباع الدليل. scope هو نطاق OAuth 2.0 الذي يجب استخدامه للوصول إلى واجهة برمجة التطبيقات مع "إعلانات Google".https://www.googleapis.com/auth/adwords بالإضافة إلى ذلك، يمكنك تخطّي المَعلمة sub عند إنشاء مجموعة مطالبات JWT، لأنّ خطوات الإعداد تمنح حساب الخدمة إذن الوصول المباشر إلى حساب "إعلانات Google"، وبالتالي تجنُّب الحاجة إلى انتحال هوية مستخدم في "إعلانات Google".
يمكنك بعد ذلك استخدام رمز الدخول في عنوان HTTP Authorization لكل طلب بيانات من واجهة برمجة التطبيقات يتم إرساله إلى Google Ads API:
GET /v25/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 /v25/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
عناوين الطلبات
توضّح الأقسام التالية عناوين HTTP المطلوبة أو المستخدَمة عند إرسال طلبات إلى Google Ads API.
الرمز المميز للمطوِّر
تتطلّب Google Ads API أيضًا رمزًا مميزًا للمطوِّر لإجراء طلبات إلى واجهة برمجة التطبيقات. إذا كان لديك رمز مميز للمطوِّر، يمكنك العثور عليه من خلال الانتقال إلى https://ads.google.com/aw/apicenter. سجِّل الدخول إلى حسابك الإداري على "إعلانات Google" إذا طُلب منك ذلك. إذا لم يكن لديك رمز مميّز، اتّبِع التعليمات للاشتراك للحصول على رمز مميّز للمطوّرين.
يجب تضمين قيمة الرمز المميز للمطوِّر في عنوان HTTP developer-token لكل طلب بيانات من واجهة برمجة التطبيقات يتم إرساله إلى Google Ads API:
GET /v25/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 /v25/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: PARTNER_CUSTOMER_ID
linked-customer-id: ADVERTISER_CUSTOMER_ID
عناوين الاستجابة
يتم عرض العناوين التالية في استجابات HTTP من واجهة برمجة التطبيقات.
معرّف الطلب
request-id هي سلسلة تحدّد طلب بيانات من واجهة برمجة التطبيقات بشكلٍ فريد. عند تصحيح الأخطاء أو تحديد المشاكل وحلّها في ما يتعلّق بطلبات معيّنة من واجهة برمجة التطبيقات، يكون request-id
معرّفًا مهمًا يجب توفّره عند التواصل مع فريق الدعم للمطوّرين في Google.
request-id: 2a5Cj89VV7CNhya1DZjjrC