يوضِّح هذا الدليل البنية الشائعة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدم مكتبة برامج للتفاعل مع واجهة برمجة التطبيقات، فلن يجب أن تقلق بشأن تفاصيل الطلب الأساسية. ومع ذلك، فمعرفة بعض المعلومات عنها يمكن أن تكون مفيدة عند الاختبار وتصحيح الأخطاء.
Google Ads API هي إحدى واجهات gRPC API، عمليات ربط REST وهذا يعني أنّ هناك طريقتان لإجراء طلبات بيانات من واجهة برمجة التطبيقات.
[Preferred] إنشاء نص الطلب على أنه المخزن المؤقت للبروتوكول، إرساله إلى الخادم باستخدام HTTP/2: إلغاء تسلسل الاستجابة لبروتوكول المورد الاحتياطي وتفسير النتائج. تصف معظم وثائقنا استخدام gRPC.
[اختياري] إنشاء نص الطلب كـ JSON، أرسِله إلى الخادم باستخدام HTTP 1.1، إلغاء تسلسل الاستجابة ككائن JSON، وتفسير النتائج. ارجع إلى يمكنك الاطّلاع على دليل واجهة RST للحصول على مزيد من المعلومات عن استخدام راحة.
أسماء الموارد
ويتم تعريف معظم العناصر في واجهة برمجة التطبيقات من خلال سلاسل أسماء الموارد الخاصة بها. هذه تعمل السلاسل أيضًا كعنوان URL عند استخدام واجهة REST. الاطّلاع على REST أسماء موارد الواجهة البنية.
أرقام التعريف المركّبة
إذا لم يكن رقم تعريف أحد العناصر فريدًا بشكل عام، يجب استخدام رقم تعريف مركب لهذا الكائن. يتم إنشاؤها عن طريق إضافة المعرف الأصلي والتلدة (~) في البداية.
على سبيل المثال، نظرًا لأن الرقم التعريفي لإعلان المجموعة الإعلانية ليس فريدًا في جميع أنحاء العالم، فإننا نضيفه أولاً رقم تعريف العنصر الأصلي (المجموعة الإعلانية) إليه لإنشاء رقم تعريف مركب فريد:
AdGroupIdمن123+~+AdGroupAdIdمن45678= إعلان مركب الرقم التعريفي لإعلان المجموعة123~45678.
عناوين الطلبات
هذه هي عناوين HTTP (أو grpc البيانات الوصفية) المصاحبة نص الطلب:
التفويض
يجب تضمين رمز الدخول OAuth2 في شكل
Authorization: Bearer YOUR_ACCESS_TOKEN التي تحدِّد
حساب إداري يعمل نيابةً عن عميل أو معلِن بشكل مباشر
إدارة حساباتهم الخاصة. إرشادات استرداد رمز الدخول
يمكن العثور عليها في دليل OAuth2. إنّ
يكون رمز الدخول صالحًا لمدة ساعة بعد الحصول عليه عندما
انتهاء الصلاحية، يُرجى إعادة تحميل رمز الدخول لاسترداد رمز جديد. لاحظ أن
تقوم مكتبات العملاء بتحديث الرموز المميزة المنتهية الصلاحية تلقائيًا.
developer-token
الرمز المميز للمطوِّر هو سلسلة مكونة من 22 حرفًا وتحدد بشكل فريد
مطوّر برامج Google Ads API مثال على سلسلة الرمز المميز للمطور
ABcdeFGH93KL-NOPQ_STUv يجب تضمين الرمز المميز للمطوِّر في
من developer-token : ABcdeFGH93KL-NOPQ_STUv.
login-customer-id
هذا هو الرقم التعريفي للعميل المفوَّض لاستخدامه في الطلب،
بدون واصلات (-). إذا كان وصولك إلى حساب العميل يتم من خلال
حساب إداري، هذا العنوان مطلوب ويجب ضبطه على الرقم التعريفي للعميل
الحساب الإداري.
https://googleads.googleapis.com/v17/customers/1234567890/campaignBudgets:mutate
يتساوى ضبط login-customer-id مع اختيار حساب في
واجهة مستخدم "إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى الصفحة
صحيح. إذا لم يتم تضمين هذا العنوان، فسيتم ضبطه افتراضيًا على عمود التشغيل
لعميلك.
linked-customer-id
لا يستخدم هذا العنوان إلا مقدمي خدمة تحليلات التطبيقات التابعين لجهات خارجية عند جارٍ تحميل الإحالات الناجحة إلى حساب مرتبط على "إعلانات Google" الحساب.
يجب مراعاة السيناريو الذي يمنح فيه المستخدمون في الحساب A إذن الوصول للقراءة والتعديل
إلى كياناتها لحساب B من خلال
ThirdPartyAppAnalyticsLink
بعد الربط، يمكن لمستخدم في الحساب B إجراء طلبات بيانات من واجهة برمجة التطبيقات مقابل الحساب A،
وفقًا للأذونات التي يتضمنها الرابط. في هذه الحالة، لا يمكن استدعاء واجهة برمجة التطبيقات
يتم تحديد الأذونات للحساب A من خلال رابط الجهة الخارجية إلى الحساب B،
بدلاً من علاقة الحساب الإداري المستخدمة في طلبات البيانات من واجهة برمجة التطبيقات الأخرى.
يُجري موفِّر خدمة تحليلات التطبيقات من جهة خارجية طلب بيانات من واجهة برمجة التطبيقات على النحو التالي:
linked-customer-id: حساب إحصاءات التطبيقات التابع لجهة خارجية الذي يحمِّل البيانات (الحسابB).customer-id: حساب "إعلانات Google" الذي يتم تحميل البيانات إليه (الحسابA).- العنوان
login-customer-idوAuthorization: مجموعة من القيم التعرّف على مستخدم لديه إذن الوصول إلى الحسابB
عناوين الردود
يجب أن تتضمن العناوين التالية (أو grpc tracking-metadata) مع نص الاستجابة. نوصيك بتسجيل هذه القيم لأغراض تصحيح الأخطاء.
معرّف الطلب
والسمة request-id هي سلسلة تعرِّف هذا الطلب بشكل فريد.