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

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

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

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

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

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

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

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

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

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

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

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

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

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

مراعاة الحصص في إعداد التقارير

يتم فرض الاستخدام المسؤول لميزات إعداد التقارير في "مساحة العرض والفيديو 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.