يتم عادةً إجراء الطلبات إلى Search Ads 360 Reporting API من خلال مكتبة البرامج في حسابك. راجِع شرح مكتبات العملاء للحصول على مزيد من المعلومات. ومع ذلك، يمكن أن تكون معرفة بنية تفاصيل الطلب الأساسية مفيدة عند الاختبار وتصحيح الأخطاء.
Search Ads 360 Reporting API هي واجهة برمجة تطبيقات gRPC API تتضمّن عمليات ربط REST. يعني ذلك أنّه يمكنك إجراء اتصالات بواجهة برمجة التطبيقات بطريقتَين بديلتَين:
- الطريقة المفضّلة
- استخدام مكتبة برامج:
- إنشاء نص الطلب باعتباره مخزنًا مؤقتًا للبروتوكول.
- أرسل الطلب إلى الخادم باستخدام HTTP/2.
- إلغاء تسلسل الاستجابة لاستجابة بروتوكول المخزن المؤقت
- تفسير النتائج.
- طريقة بديلة اختيارية
- استخدام REST:
- إنشاء نص الطلب ككائن JSON.
- أرسل الطلب إلى الخادم باستخدام HTTP 1.1.
- إظهار الاستجابة ككائن JSON
- تفسير النتائج.
يمكنك الاطّلاع على Google Cloud APIs للحصول على مزيد من المعلومات.
تنطبق الأقسام التالية على كل من بروتوكولَي gRPC وREST.
أسماء الموارد
يتم تحديد معظم الكائنات في واجهة برمجة التطبيقات من خلال سلاسل اسم المورد الخاصة بها. تعمل هذه السلاسل أيضًا على أنّها عناوين URL عند استخدام واجهة REST.
يمكنك الاطّلاع على المرجع > REST للحصول على مزيد من المعلومات حول الموارد المتوافقة وتمثيل مسارها. يتم استخدام نفس التنسيق مع خدمات أخرى.
أرقام التعريف المركّبة
إذا لم يكن معرّف أحد العناصر فريدًا من نوعه، يتم إنشاء معرّف مركب لذلك العنصر من خلال إضافة معرّفه الأصلي وتلدة (~).
على سبيل المثال، بما أن رقم تعريف إعلان المجموعة الإعلانية ليس فريدًا عالميًا، يتم إرفاق رقم تعريف العنصر الرئيسي (المجموعة الإعلانية) به سابقًا، ما يؤدي إلى إنشاء رقم تعريف مركّب فريد.
مثال: AdGroupId من 123 + ~ + AdGroupAdId من إجمالي 45678
= رقم تعريف إعلان المجموعة الإعلانية المركّبة 123~45678.
عناوين الطلبات
يجب تضمين عناوين HTTP (أو البيانات الوصفية gRPC) في الأقسام التالية في نص الطلب.
التفويض
تحتاج إلى تضمين رمز دخول OAuth2 في النموذج:
Authorization: Bearer [OAUTH_2.0_ACCESS_TOKEN]
ويجب أن يحدّد الرمز المميّز إمّا حسابًا إداريًا يتصرّف نيابةً عن عميل أو معلِن يدير حساب المدير الفرعي أو حساب العميل مباشرةً. اطّلع على لمحة عن الحسابات الإدارية على "إعلانات شبكة البحث 360" والمصادقة لمزيد من المعلومات.
عنوان الرقم التعريفي للعميل المتعلق بتسجيل الدخول
يجب إدخال العنوان login-customer-id عند استخدام حساب إداري للوصول إلى حساب مدير فرعي أو حساب عميل. وهذا الإجراء ليس مطلوبًا عند الوصول إلى
حساب مدير فرعي أو حساب عميل مباشرةً. على الرغم من أنّ هذا ليس ضروريًا تمامًا، فإنّنا ننصحك دائمًا بتحديد login-customer-id للمستخدمين الذين تمت مصادقتهم والذين يمكنهم الوصول إلى أكثر من حساب واحد. يساعد ذلك في تجنب الغموض ويمنع ضبط السياق عن غير قصد على الحساب غير الصحيح.
يجب أن يتضمّن الطلب الرقم التعريفي للعميل للمستخدم المفوَّض، بدون
واصلات (-)، على سبيل المثال:
https://searchads360.googleapis.com/VERSION_NUMBER/customers/CUSTOMER_ID/campaignBudgets
يعادل ضبط login-customer-id اختيار حساب في واجهة مستخدم "إعلانات شبكة البحث 360" بعد تسجيل الدخول أو النقر على صورة ملفك الشخصي في أعلى يسار الصفحة.
عناوين الاستجابة
يتم عرض العناوين التالية (أو البيانات الوصفية اللاحقة gRPC) مع نص الاستجابة. ننصحك بتسجيل هذه القيم لأغراض تصحيح الأخطاء.
معرّف الطلب
العنوان request-id هو سلسلة تُعرّف الطلب بشكلٍ فريد.