يتم عادةً إجراء الطلبات إلى Search Ads 360 Reporting API من خلال مكتبة العملاء. اطّلِع على شرح مكتبات العميل للحصول على مزيد من المعلومات. ومع ذلك، يمكن أن تكون معرفة بنية تفاصيل الطلب الأساسية مفيدة عند الاختبار وتصحيح الأخطاء.
Search Ads 360 Reporting API هي واجهة برمجة تطبيقات gRPC تتضمّن عمليات ربط 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 tracking-metadata) مع نص الاستجابة. ننصحك بتسجيل هذه القيم لأغراض debugging.
معرّف الطلب
عنوان request-id هو سلسلة تحدّد الطلب بشكل فريد.