يصف هذا الدليل البنية الشائعة لجميع طلبات البيانات من واجهة برمجة التطبيقات.
إذا كنت تستخدِم مكتبة عملاء للتفاعل مع واجهة برمجة التطبيقات، لن تحتاج إلى معرفة تفاصيل الطلب الأساسية. ومع ذلك، يمكن أن تكون معرفة قليلة ببنية طلب البيانات من واجهة برمجة التطبيقات مفيدة عند الاختبار ومحاولة تصحيح الأخطاء.
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/v20/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 هي سلسلة تحدِّد هذا الطلب بشكل فريد.