يصف هذا الدليل البنية الشائعة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدِم مكتبة عملاء للتفاعل مع واجهة برمجة التطبيقات، لن تحتاج إلى القلق بشأن تفاصيل الطلب الأساسية. ومع ذلك، قد يكون من المفيد معرفة بعض المعلومات عنها عند الاختبار وتصحيح الأخطاء.
Google Ads API هي واجهة برمجة تطبيقات gRPC، مع عمليات ربط REST. وهذا يعني أنّ هناك طريقتَين لإجراء طلبات البيانات من واجهة برمجة التطبيقات.
[الخيار المفضّل] أنشئ نص الطلب على هيئة مخازن بروتوكول، وأرسِله إلى الخادم باستخدام HTTP/2، وفكِّ ترميز الاستجابة إلى ملف تخزين بروتوكول، وفسِّر النتائج. توضّح معظم مستنداتنا كيفية استخدام gRPC.
[اختياري] أنشئ نص الطلب كعنصر JSON، وأرسِله إلى الخادم باستخدام HTTP 1.1، وفكِّك ترميز الاستجابة كعنصر JSON، وفسِّر النتائج. يُرجى الرجوع إلى دليل واجهة REST للحصول على مزيد من المعلومات عن استخدام واجهة REST.
أسماء الموارد
يتم تحديد معظم العناصر في واجهة برمجة التطبيقات من خلال سلاسل أسماء الموارد. وتُستخدَم هذه السلسلتَين أيضًا كعناوين 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/v19/customers/1234567890/campaignBudgets:mutate
يعادل ضبط الإعداد login-customer-id اختيار حساب في واجهة مستخدم
"إعلانات Google" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى
اليسار. في حال عدم تضمين هذا العنوان، سيتم ضبطه تلقائيًا على operating
customer.
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 trailing-metadata) مع نص الاستجابة. ننصحك بتسجيل هذه القيمة أغراض تصحيح الأخطاء.
request-id
request-id هي سلسلة تحدِّد هذا الطلب بشكل فريد.