يتم عادةً إجراء طلبات البيانات إلى 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 trailing-metadata) مع نص الاستجابة. ننصحك بتسجيل هذه القيم لأغراض debugging.
معرّف الطلب
عنوان request-id هو سلسلة تحدّد الطلب بشكل فريد.