تحتاج إلى بيانات اعتماد 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 أو مساحة بروتوكول 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