يجب توفّر بيانات اعتماد تطبيق 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 لتجربة بيانات اعتماد التطبيق و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:
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 /v21/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 /v21/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 /v21/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: MANAGER_CUSTOMER_ID
linked-customer-id: LINKED_CUSTOMER_ID
عناوين الاستجابة
يتم عرض العناوين التالية في استجابات HTTP من واجهة برمجة التطبيقات.
معرّف الطلب
request-id هي سلسلة تحدّد طلب واجهة برمجة التطبيقات بشكلٍ فريد. عند تصحيح الأخطاء أو تحديد المشاكل وحلّها في طلبات معيّنة من واجهة برمجة التطبيقات، يكون request-id معرّفًا مهمًا يجب توفّره عند التواصل مع فريق الدعم للمطوّرين في Google.
request-id: 2a5Cj89VV7CNhya1DZjjrC