أفضل ممارسات إعداد التقارير

إنشاء تقارير جديدة في واجهة المستخدم أولاً

تخضع التقارير لعدد من القيود والمتطلبات المتعلقة بأنواع التقارير والفلاتر والسمات والمقاييس. يتم فرض هذه القيود في واجهة برمجة التطبيقات، ما يؤدي إلى عرض خطأ HTTP 400. لتجنُّب حدوث أخطاء عند إنشاء التقارير، ننصحك أولاً بإنشاء تقارير جديدة في واجهة مستخدم "مساحة العرض والفيديو 360".

بعد إنشاء تقريرك، انقر على ميزة "تجربة واجهة برمجة التطبيقات هذه" في صفحة "المستندات المرجعية" لتنفيذ queries.get لمورد Query. يمكنك استخدام JSON المعروض لإنشاء تقارير مستقبلية.

استخدام المقاييس والفلاتر المخصّصة لنوع التقرير

تخصّ بعض قيم المقاييس والفلترة أنواعًا معيّنة من التقارير. بالإضافة إلى إنشاء تقاريرك في واجهة المستخدم أولاً، يمكنك أيضًا تحديد المقاييس والفلاتر التي تنتمي إلى قيم ReportType معيّنة من خلال قيمة واجهة برمجة التطبيقات في "مدير عرض الأسعار".

في ما يلي بعض الطرق لتحديد قيم المقاييس وفلتر واجهة برمجة التطبيقات لإدارة عروض الأسعار ذات الصلة. لا يشكّل هذا الجدول قائمة شاملة للفلاتر والمقاييس التي يمكن استخدامها في هذه الأنواع من التقارير. لا يمكن استخدام جميع القيم معًا في تقرير واحد.

حفظ التقارير وإعادة استخدامها

نوصي بإنشاء وحفظ تقارير لطلبات البحث التي تنفّذها بانتظام لأن إدراج نفس التقرير وحذفه مرات عديدة يؤدي إلى إهدار الموارد. يؤدي استخدام قيم مجموعة Range، مثل PREVIOUS_DAY أو LAST_7_DAYS، في الحقل dataRange إلى تسهيل إعادة استخدام التقارير.

جدولة التقارير

يمكن أن تكون التقارير المخصصة أو لمرة واحدة مهدرة للموارد لأنه يتم تشغيلها بشكل فردي وقد يتم تنفيذها على مجموعة بيانات غير كاملة. تستفيد التقارير المجدولة إلى أقصى حد من موارد إعداد التقارير لأنها يتم تشغيلها بشكل مجمّع وضمان عدم تنفيذها حتى اكتمال معالجة بيانات اليوم السابق. راجِع حقول الجدولة المتاحة للحصول على التفاصيل.

دمج التقارير المتشابهة

إذا كنت تنشئ تقارير بانتظام باستخدام مقاييس ونطاقات زمنية متطابقة لمختلف المعلنِين أو الشركاء، ننصحك بدمج التقارير لتحسين حجم تقاريرها.

يمكنك دمج التقارير المتشابهة من خلال إلحاق فلاتر جميع التقارير وإضافة جميع أنواع الفلاتر باعتبارها سمات. وبعد الإنشاء، يمكنك تقسيم صفوف التقرير الناتج على طول قيم الفلتر الأصلية لإنتاج التقارير الأصلية.

ننصحك بإعداد التقارير عن الحصص.

يتم فرض الاستخدام المسؤول لميزة إعداد التقارير في "مساحة العرض والفيديو 360" من خلال حصص الاستخدام التالية على مستوى المنتج.

عدد عمليات تنفيذ التقارير المخصّصة في اليوم

يحدّ هذا الخيار من عدد التقارير المخصّصة التي يمكن للمستخدِم تنفيذها خلال فترة 24 ساعة. للبقاء ضمن هذه الحصة:

• دمج التقارير المتشابهة لتقليل حجم التقارير
• جدولة التقارير المخصّصة المتكرّرة لتقليل حجم التقارير المخصّصة على وجه التحديد
• أوقِف النصوص البرمجية غير الضرورية لواجهة برمجة التطبيقات.

التقارير المُجدوَلة النشطة

يحدّ هذا الخيار من عدد التقارير التي يمكن للمستخدم جدولتها بشكل نشط في وقت معيّن. للبقاء ضمن هذه الحصة:

• دمج التقارير المجدوَلة المتشابهة لتقليل العدد الإجمالي للتقارير المُجدوَلة
• أوقِف التقارير المُجدوَلة غير الضرورية.
• أوقِف النصوص البرمجية غير الضرورية لواجهة برمجة التطبيقات.

التقارير المتزامنة

يحدّ من عدد التقارير التي يمكن للمستخدم تشغيلها في آنٍ واحد. للبقاء ضمن هذه الحصة:

• جدولة التقارير التي يتم تشغيلها بانتظام.
• أوقِف النصوص البرمجية غير الضرورية لواجهة برمجة التطبيقات.
• يمكنك تتبُّع أوقات انتهاء تقاريرك من خلال الاستطلاعات باستخدام منطق التراجع الأسي.

إذا كنت قد حسَّنت عملية تنفيذ إعداد التقارير ولا تزال تتجاوز الحصة المحددة، يُرجى التواصل مع فريق دعم "مساحة العرض والفيديو 360" باستخدام نموذج التواصل.

استخدام ميزة "التراجع الأُسيّ" عند البحث عن حالة التقرير

لا يمكن التنبؤ بالمدة التي سيستغرقها تشغيل التقرير. يمكن أن تتراوح المدة من ثوانٍ إلى ساعات اعتمادًا على العديد من العوامل بما في ذلك النطاق الزمني ومقدار البيانات التي ستتم معالجتها، على سبيل المثال. وليس هناك أيضًا ارتباط بين وقت تشغيل التقرير وعدد الصفوف المعروضة في التقرير. لذلك، عليك استرداد مورد التقرير بانتظام باستخدام طريقة queries.reports.get والتحقّق مما إذا كان قد تم تعديل حقل metadata.status.state للمورد إلى DONE أو FAILED لتحديد ما إذا كان قد انتهى عرضه. وتُعرف هذه العملية باسم "الاقتراع".

ورغم أهمية استطلاعات الرأي، إلا أن التنفيذ غير الفعال قد يستنفد حصّتك بسرعة عند العمل على تقرير طويل الأمد. ولذلك نوصي باستخدام التراجع الأُسيّ للحد من إعادات المحاولة والحفاظ على الحصة.

تراجع أسي

التراجع الأسي هو استراتيجية عادية لمعالجة الأخطاء لتطبيقات الشبكة التي يعيد فيها العميل محاولة الطلب بشكل دوري على مدار فترة زمنية متزايدة. ويؤدي استخدام ميزة "التراجع الأسي" إلى زيادة كفاءة استخدام معدل نقل البيانات، وتقليل عدد الطلبات المطلوبة للحصول على استجابة ناجحة، وزيادة سرعة معالجة الطلبات في البيئات المتزامنة إلى أقصى حد، وذلك عند استخدامها بشكل صحيح.

في ما يلي الخطوات التي يجب اتّباعها لتنفيذ تراجع أسي بسيط:

1. يمكنك تقديم طلب queries.reports.get إلى واجهة برمجة التطبيقات.
2. استرجع كائن التقرير. إذا لم يكن الحقل metadata.status.state ليس DONE أو FAILED، هذا يعني أنّ التقرير لم يكتمل ويجب مواصلة الاستطلاع.
3. انتظِر لمدة 5 ثوانٍ بالإضافة إلى عدد عشوائي بالملي ثانية ثم أعِد محاولة إجراء الطلب.
4. استرجع كائن التقرير. إذا لم يكن الحقل metadata.status.state ليس DONE أو FAILED، هذا يعني أنّ التقرير لم يكتمل ويجب مواصلة الاستطلاع.
5. انتظِر لمدة 10 ثوانٍ بالإضافة إلى عدد عشوائي بالملي ثانية وأعِد محاولة إجراء الطلب.
6. استرجع كائن التقرير. إذا لم يكن الحقل metadata.status.state ليس DONE أو FAILED، هذا يعني أنّ التقرير لم يكتمل ويجب مواصلة الاستطلاع.
7. انتظِر لمدة 20 ثانية بالإضافة إلى عدد عشوائي بالملي ثانية وأعِد محاولة إجراء الطلب.
8. استرجع كائن التقرير. إذا لم يكن الحقل metadata.status.state ليس DONE أو FAILED، هذا يعني أنّ التقرير لم يكتمل ويجب مواصلة الاستطلاع.
9. انتظِر لمدة 40 ثانية بالإضافة إلى عدد عشوائي بالملي ثانية وأعِد محاولة إجراء الطلب.
10. استرجع كائن التقرير. إذا لم يكن الحقل metadata.status.state ليس DONE أو FAILED، هذا يعني أنّ التقرير لم يكتمل ويجب مواصلة الاستطلاع.
11. انتظِر لمدة 80 ثانية بالإضافة إلى عدد عشوائي بالملي ثانية ثم أعِد محاولة إجراء الطلب.
12. استمر في هذا النمط حتى يتم تحديث كائن التقرير أو يتم الوصول إلى الحد الأقصى للوقت المنقضي.

إذا انتهى تشغيل التقرير وانتهى بالحالة DONE، يمكنك استرداد ملف التقرير الذي تم إنشاؤه من Google Cloud Storage في المسار المحدّد في الحقل metadata.googleCloudStoragePath.