تحتاج إلى بيانات اعتماد OAuth 2.0 ورمز مميّز للمطوّر عند طلب Google Ads API. إذا كنت تجري طلبات من واجهة برمجة التطبيقات باستخدام حساب إداري على "إعلانات Google"، عليك أيضًا تحديد عنوان login-customer-id مع كل طلب. توضّح هذه الصفحة كيفية ضبط هذه القيم وتوثّق عدة عناوين HTTP إضافية خاصة بواجهة برمجة التطبيقات يتم إرسالها واستلامها عند استخدام واجهة REST.
بيانات اعتماد OAuth 2.0
تستخدم Google Ads API بروتوكول OAuth 2.0 للموافقة على طلبات واجهة برمجة التطبيقات. يتوافق هذا البروتوكول مع مسار مصادقة المستخدم في OAuth 2.0 user authentication flow ومسار حساب الخدمة service account flow. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة 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 Ads API هو
https://www.googleapis.com/auth/adwords. بالإضافة إلى ذلك، يمكنك تخطّي المَعلمة sub عند إنشاء مجموعة طلبات JWT، لأنّ خطوات الإعداد تمنح حساب الخدمة إمكانية الوصول المباشر إلى حساب "إعلانات Google"، ما يجنّبك الحاجة إلى انتحال صفة مستخدم على "إعلانات Google".
بعد ذلك، استخدِم رمز الدخول في عنوان HTTP Authorization لكل طلب بيانات من واجهة برمجة التطبيقات إلى Google Ads API:
GET /v24/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 /v24/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 /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
رقم تعريف العميل لتسجيل الدخول
بالنسبة إلى طلبات Google Ads API التي يرسلها حساب إداري إلى حساب عميل (أي عند تسجيل الدخول بصفتك مديرًا لإجراء طلبات من واجهة برمجة التطبيقات إلى أحد حسابات العملاء)، عليك أيضًا تقديم عنوان HTTP login-customer-id. تمثّل هذه القيمة رقم تعريف عميل "إعلانات Google" للمدير الذي يجري طلب بيانات من واجهة برمجة التطبيقات.
إنّ تضمين هذا العنوان يعادل اختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفّك الشخصي في أعلى يسار الصفحة. عند تحديد رقم تعريف العميل، احرص على إزالة أي شرطات (—). على سبيل المثال: 1234567890 بدلاً من 123-456-7890. يُرجى الرجوع إلى دليل نموذج الوصول إلى "إعلانات Google" لمزيد من المعلومات عن رقم تعريف العميل لتسجيل الدخول.
GET /v24/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_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