YouTube Reporting API - Get Bulk Data Reports

ينشئ YouTube تلقائيًا مجموعة من تقارير أرباح الإعلانات التي يديرها النظام لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير المقابلة في استوديو YouTube. تم تصميم هذه التقارير لتوفير إمكانية الوصول آليًا إلى البيانات المتوفّرة أيضًا في التقارير التي يمكن تنزيلها يدويًا والتي يمكن الوصول إليها في قائمة التقارير في "استوديو YouTube".

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

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

استرداد التقارير

توضّح الخطوات التالية كيفية استرداد التقارير التي يديرها النظام من خلال واجهة برمجة التطبيقات.

الخطوة 1: استرداد بيانات اعتماد التفويض

يجب أن يتم السماح بإرسال جميع طلبات البيانات من YouTube Reporting API. يوضّح دليل التفويض كيفية استخدام بروتوكول OAuth 2.0 لاسترداد رموز التفويض المميزة.

تستخدم طلبات YouTube Reporting API نطاقات التفويض التالية:

المستويات
https://www.googleapis.com/auth/yt-analytics.readonly عرض تقارير "إحصاءات YouTube" للمحتوى في YouTube يوفّر هذا النطاق إمكانية الوصول إلى مقاييس نشاط المستخدمين، مثل عدد المشاهدات وعدد التقييمات.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly عرض تقارير "إحصاءات YouTube" المالية للمحتوى في YouTube يتيح هذا النطاق الوصول إلى مقاييس نشاط المستخدمين وإلى المقاييس المقدَّرة للأرباح وأداء الإعلانات.

الخطوة 2: استرداد معرّف مهمة التقرير المطلوب

استدعِ طريقة jobs.list لاسترداد قائمة بالمهام التي يديرها النظام. اضبط المَعلمة includeSystemManaged على true.

تحدّد السمة reportTypeId في كل مورد Job تم عرضه نوع التقرير الذي يديره النظام والمرتبط بهذه المهمة. يحتاج تطبيقك إلى قيمة السمة id من المرجع نفسه في الخطوة التالية.

يسرد مستند التقارير التقارير المتاحة ومعرّفات أنواع التقارير والحقول التي تتضمّنها. يمكنك أيضًا استخدام طريقة reportTypes.list لاسترداد قائمة بأنواع التقارير المتوافقة.

الخطوة 3: استرداد عنوان URL لتنزيل التقرير

استدعِ طريقة jobs.reports.list لاسترداد قائمة بالتقارير التي تم إنشاؤها للمهمة. في الطلب، اضبط المَعلمة jobId على معرّف مهمة التقرير الذي تريد استرداده.

يمكنك فلترة قائمة التقارير باستخدام أيّ من المَعلمات التالية أو جميعها:

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

  • استخدِم المَعلمة startTimeBefore للإشارة إلى أنّ استجابة واجهة برمجة التطبيقات يجب أن تتضمّن التقارير فقط إذا كانت البيانات الأقدم في التقرير قبل التاريخ المحدّد. في حين أنّ المَعلمة createdAfter تتعلّق بوقت إنشاء التقرير، يشير هذا التاريخ إلى البيانات الواردة في التقرير.

  • استخدِم المَعلمة startTimeAtOrAfter للإشارة إلى أنّ استجابة واجهة برمجة التطبيقات يجب أن تحتوي على تقارير فقط إذا كانت البيانات الأقدم في التقرير في التاريخ المحدّد أو بعده. مثل المَعلمة startTimeBefore، تتوافق قيمة هذه المَعلمة مع البيانات الواردة في التقرير وليس مع وقت إنشاء التقرير.

يتضمّن الردّ من واجهة برمجة التطبيقات قائمة بموارد Report لهذا العمل. يشير كل مرجع إلى تقرير يحتوي على بيانات لفترة زمنية فريدة.

  • تحدّد السمتان startTime وendTime الخاصتان بالمرجع الفترة الزمنية التي تغطيها بيانات التقرير.
  • تحدّد السمة downloadUrl الخاصة بالمرجع عنوان URL الذي يمكن استرداد التقرير منه.
  • تحدّد السمة createTime الخاصة بالمرجع تاريخ ووقت إنشاء التقرير. يجب أن يخزّن تطبيقك هذه القيمة ويستخدمها لتحديد ما إذا كانت التقارير التي تم تنزيلها سابقًا قد تغيّرت.

الخطوة 4: تنزيل التقرير

أرسِل طلب استرداد بيانات باستخدام GET HTTP إلى downloadUrl الذي تم الحصول عليه في الخطوة 4 لاسترداد التقرير.

تقارير المعالجة

أفضل الممارسات

يجب أن تلتزم التطبيقات التي تستخدم YouTube Reporting API دائمًا بالممارسات التالية:

  • استخدِم صف العنوان في التقرير لتحديد ترتيب أعمدة التقرير. على سبيل المثال، لا تفترض أنّ المشاهدات ستكون المقياس الأول الذي يتم عرضه في التقرير لمجرّد أنّه المقياس الأول المُدرَج في وصف التقرير. بدلاً من ذلك، استخدِم صف العناوين في التقرير لتحديد العمود الذي يحتوي على هذه البيانات.

  • احتفظ بسجلّ للتقارير التي نزّلتها لتجنُّب معالجة التقرير نفسه بشكل متكرّر. تقترح القائمة التالية طريقتَين لإجراء ذلك.

    • عند استدعاء طريقة reports.list، استخدِم المَعلمة createdAfter لاسترداد التقارير التي تم إنشاؤها بعد تاريخ معيّن فقط. (احذف المَعلمة createdAfter في المرة الأولى التي تستردّ فيها التقارير).

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

      كإجراء وقائي، قبل استرداد تقرير، تحقَّق أيضًا للتأكّد من أنّ معرّف التقرير غير مُدرَج في قاعدة البيانات.

    • احفظ المعرّف لكل تقرير نزّلته وعالجته. يمكنك أيضًا تخزين معلومات إضافية، مثل التاريخ والوقت اللذين تم فيهما إنشاء كل تقرير أو startTime وendTime للتقرير، واللذين يحدّدان معًا الفترة التي يتضمّن التقرير بياناتها. بالنسبة إلى التقارير التي تستردّ بيانات مجمّعة من "إحصاءات YouTube"، من المحتمل أن تتضمّن كل مهمة العديد من التقارير لأنّ كل تقرير يحتوي على بيانات لفترة 24 ساعة. ستتضمّن المهام التي يديرها النظام والتي تغطي فترات زمنية أطول عددًا أقل من التقارير.

      استخدِم رقم تعريف التقرير لتحديد التقارير التي لا يزال عليك تنزيلها واستيرادها. ومع ذلك، إذا كان تقريران جديدان يتضمّنان قيمتَي السمتَين startTime وendTime نفسيهما، ما عليك سوى استيراد التقرير الذي يتضمّن قيمة createTime الأحدث.

خصائص التقرير

تقارير واجهة برمجة التطبيقات هي ملفات .csv (قيم مفصولة بفواصل) تتضمّن الخصائص التالية:

  • يحتوي كل تقرير على بيانات لفترة فريدة تمتد من الساعة 12:00 صباحًا بتوقيت المحيط الهادئ في تاريخ بدء التقرير إلى الساعة 11:59 مساءً بتوقيت المحيط الهادئ في تاريخ انتهاء التقرير.

  • لم يتم فرز بيانات التقرير.