رؤوس 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، يمكنك استخدام oauth2l أو مساحة OAuth 2.0 التجريبية لتجربة بيانات اعتماد التطبيق وGoogle Ads API قبل كتابة الرمز البرمجي لتطبيقك.

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

اتّبِع الخطوات لضبط مشروع على Google API Console لواجهة برمجة التطبيقات Google Ads API. سجِّل معرِّف العميل و سر العميل، ثم ارجع إلى هذه الصفحة.

بعد إنشاء عميل 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 فيAuthorization عنوان HTTP لكل طلب واجهة برمجة تطبيقات إلى Google Ads API:

GET /v19/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

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

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

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

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

GET /v19/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

رقم تعريف العميل لتسجيل الدخول

بالنسبة إلى طلبات البيانات من واجهة برمجة التطبيقات في "إعلانات Google" التي يُجريها حساب مدير إلى حساب عميل (أي عند تسجيل الدخول بصفتك مديرًا لإجراء طلبات بيانات من واجهة برمجة التطبيقات إلى أحد حسابات العملاء)، يجب أيضًا تقديم عنوان HTTP login-customer-id. تمثّل هذه القيمة رقم تعريف عميل "إعلانات Google" الخاص بالمدير الذي يُجري طلب بيانات من واجهة برمجة التطبيقات.

ويؤدي تضمين هذا العنوان إلى اختيار حساب في واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة. عند تحديد رقم تعريف العميل، احرص على إزالة أيّ شرطات (—)، على سبيل المثال: 1234567890 وليس 123-456-7890.

GET /v19/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