رؤوس HTTP والتفويض

الفيديو: المصادقة

تحتاج إلى كلٍّ من بيانات اعتماد تطبيق OAuth 2.0 والرمز المميز للمطوِّر عند طلب بيانات Google Ads API. إذا كنت تجري طلبات بيانات من واجهة برمجة التطبيقات باستخدام حساب إداري على "إعلانات Google"، عليك أيضًا تحديد عنوان login-customer-id مع كل طلب. تصف هذه الصفحة كيفية ضبط هذه القيم وتوثّق العديد من عناوين HTTP الإضافية الخاصة بواجهة برمجة التطبيقات التي يتم إرسالها واستلامها عند استخدام واجهة REST.

بيانات اعتماد OAuth 2.0

تستخدم Google Ads API بيانات اعتماد التطبيقات لتحديد طلبات البيانات من واجهة برمجة التطبيقات واعتمادها. يمكن ضبط كل من برامج OAuth 2.0 وحسابات الخدمة. لمزيد من التفاصيل عن ضبط التفويض من جهة العميل، يُرجى الاطّلاع على OAuth2 في Google Ads API.

إذا كنت مستخدِمًا جديدًا لـ Google APIs، يمكنك استخدام oauth2l أو OAuth 2.0 Playground لتجربة بيانات اعتماد التطبيق وGoogle Ads API قبل كتابة رمز تطبيقك.

استخدام مسارات تطبيق سطح المكتب أو تطبيق الويب

اتّبِع الخطوات من أجل ضبط مشروع على وحدة تحكُّم Google API لواجهة برمجة التطبيقات مع "إعلانات Google". سجِّل معرّف العميل وسر العميل، ثم ارجع إلى هذه الصفحة.

بعد إنشاء عميل OAuth، اتّبِع تعليمات مسار تطبيق الكمبيوتر المكتبي أو تعليمات مسار تطبيق الويب لإنشاء رمز مميّز لإعادة التحميل ورمز دخول.

استخدام حسابات الخدمة

اتّبِع التعليمات الشائعة الواردة في دليل حسابات الخدمة لإعداد إمكانية الوصول إلى حساب الخدمة لواجهة Google Ads API.

بعد إعداد حساب خدمة للوصول إلى حسابك على "إعلانات Google"، اتبع دليل استخدام OAuth 2.0 لتطبيقات خادم إلى خادم مع التأكد من اختيار علامة التبويب HTTP/REST. scope الذي يمكن استخدامه للوصول إلى Google Ads API هو https://www.googleapis.com/auth/adwords.

إنشاء رموز دخول جديدة

بعد الحصول على معرّف العميل وسر العميل والرمز المميّز لإعادة التحميل، يمكنك إنشاء رمز دخول جديد لاستخدامه في طلبات البيانات من واجهة برمجة التطبيقات باستخدام أداة سطر الأوامر curl:

ملاحظة: الإصدار v3 في عنوان URL لنقطة نهاية OAuth غير مرتبط بإصدار Google Ads API، ويجب عدم تغييره عند نقل البيانات إلى الإصدارات الأحدث من Google Ads API.

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 /v16/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

عناوين الطلبات

الرمز المميز للمطوِّر

تتطلّب Google Ads API أيضًا رمزًا مميّزًا للمطوِّر من أجل إجراء طلبات بيانات من واجهة برمجة التطبيقات. يمكنك تقديم طلب للحصول على رمز مميّز لحسابك الإداري مباشرةً من واجهة مستخدم "إعلانات Google". لمزيد من التفاصيل حول إعداد الرمز المميز للمطوِّر، راجِع مقالة الحصول على الرمز المميّز للمطوِّر.

يجب تضمين قيمة الرمز المميّز للمطوِّر في عنوان HTTP developer-token لكل طلب بيانات من واجهة برمجة التطبيقات إلى Google Ads API:

GET /v16/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.

GET /v16/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID

نقطة رئيسية: في حال عدم منح التفويض بصفتك حسابًا إداريًا، أي بعبارة أخرى، إذا كانت بيانات اعتماد OAuth 2.0 خاصة بأحد مستخدمي حساب عميل "إعلانات Google" المستهدف مباشرةً، لن تحتاج إلى توفير عنوان login-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