تحتاج إلى بيانات اعتماد 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 Ads API
https://www.googleapis.com/auth/adwords. بالإضافة إلى ذلك، يمكنك تخطّي المَعلمة sub عند إنشاء مجموعة مطالبات JWT، لأنّ خطوات الإعداد تمنح حساب الخدمة إمكانية الوصول المباشر إلى حساب "إعلانات Google"، وبالتالي تجنُّب الحاجة إلى انتحال هوية مستخدم "إعلانات Google".
بعد ذلك، يمكنك استخدام رمز الوصول في عنوان HTTP Authorization لكل طلب بيانات من واجهة برمجة التطبيقات إلى Google Ads API:
GET /v26/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_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 /v26/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
عناوين الطلبات
توضّح الأقسام التالية رؤوس HTTP المطلوبة أو المستخدَمة عند إرسال طلبات إلى Google Ads API.
معرّف تسجيل الدخول للعميل
بالنسبة إلى طلبات Google Ads API التي يرسلها حساب إداري إلى حساب عميل (أي عند تسجيل الدخول كحساب إداري لإرسال طلبات إلى واجهة برمجة التطبيقات في أحد حسابات العملاء)، عليك أيضًا تقديم عنوان HTTP login-customer-id. تمثّل هذه القيمة رقم تعريف عميل "إعلانات Google"
الخاص بالحساب الإداري الذي يُجري طلب البيانات من واجهة برمجة التطبيقات.
يُعدّ تضمين هذا العنوان مكافئًا لاختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة. عند تحديد رقم تعريف العميل، احرص على إزالة أي واصلات (—)، مثلاً: 1234567890 وليس 123-456-7890. راجِع دليل نموذج الوصول إلى "إعلانات Google" لمعرفة المزيد عن الرقم التعريفي للعميل عند تسجيل الدخول.
GET /v26/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
الرقم التعريفي للعميل المرتبط
يستخدم الشركاء (مثل مقدّمي خدمة إحصاءات التطبيقات التابعة لجهة خارجية أو شركاء البيانات) عنوان "رقم تعريف العميل المرتبط" عند اتّخاذ إجراء بشأن حساب مرتبط على "إعلانات Google". لمزيد من التفاصيل، يمكنك الاطّلاع على دليل بنية طلبات البيانات من واجهة برمجة التطبيقات.
Authorization: Bearer ACCESS_TOKEN
login-customer-id: PARTNER_CUSTOMER_ID
linked-customer-id: ADVERTISER_CUSTOMER_ID
عناوين الاستجابة
يتم عرض العناوين التالية في استجابات HTTP من واجهة برمجة التطبيقات.
معرّف الطلب
request-id هو سلسلة تحدّد طلب البيانات من واجهة برمجة التطبيقات بشكل فريد. عند تصحيح الأخطاء أو تحديد المشاكل وحلّها في ما يتعلّق بطلبات معيّنة من واجهة برمجة التطبيقات، يُعدّ request-id معرّفًا مهمًا يجب توفيره عند التواصل مع فريق دعم المطوّرين في Google.
request-id: 2a5Cj89VV7CNhya1DZjjrC