تنشئ 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. يوفّر هذا النطاق إمكانية الوصول إلى مقاييس نشاط المستخدِم وإلى مقاييس الأرباح وأداء الإعلانات المقدَّرة. |
الخطوة الثانية: استرداد معرّف الوظيفة للتقرير المطلوب
استدعِ الطريقة 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: تنزيل التقرير
أرسِل طلب HTTP GET إلى downloadUrl الذي تم الحصول عليه في الخطوة 4 لاسترداد التقرير.
جارٍ معالجة التقارير
أفضل الممارسات
يجب أن تتّبع التطبيقات التي تستخدم YouTube Reporting API دائمًا الممارسات التالية:
-
استخدِم صفّ عنوان التقرير لتحديد ترتيب أعمدة التقرير. على سبيل المثال، لا تفترض أنّ المشاهدات ستكون المقياس الأول الذي يتم عرضه في التقرير لمجرد أنّه المقياس الأول المُدرَج في وصف التقرير. بدلاً من ذلك، يمكنك استخدام صف العنوان في التقرير لتحديد العمود الذي يحتوي على هذه البيانات.
-
احتفِظ بسجلّ للتقارير التي نزّلتها لتجنّب تكرار معالجة التقرير نفسه. وتقترح القائمة التالية طريقتين لإجراء ذلك.
-
عند استدعاء الإجراء
reports.list، استخدِم المَعلمة createdAfter لاسترداد التقارير التي تمّ إنشاؤها بعد تاريخ محدّد فقط. (يمكنك حذف المعلَمةcreatedAfterفي المرة الأولى التي تسترد فيها التقارير).في كلّ مرة يتمّ فيها استرداد التقارير ومعالجتها بنجاح، يمكنك تخزين الطابع الزمني المقابل للتاريخ والوقت الذي تمّ فيه إنشاء أحدث هذه التقارير. بعد ذلك، يمكنك تعديل قيمة المَعلمة
createdAfterفي كل استدعاء متتابع للطريقةreports.listلضمان استرداد التقارير الجديدة فقط، بما في ذلك التقارير الجديدة التي تتضمّن بيانات سابقة، وذلك في كل مرة يتم فيها طلب واجهة برمجة التطبيقات.قبل استرداد التقرير، يُرجى التأكّد أيضًا من أنّ رقم تعريف التقرير غير مدرَج في قاعدة البيانات كإجراء وقائي.
-
خزِّن رقم التعريف لكل تقرير تم تنزيله ومعالجته. يمكنك أيضًا تخزين معلومات إضافية، مثل التاريخ والوقت الذي تم فيه إنشاء كل تقرير أو
startTimeوendTimeفي التقرير، واللذَين يحدّدان معًا الفترة التي يحتوي التقرير على بيانات لها. بالنسبة إلى التقارير التي تسترد بيانات مجمّعة لـ YouTube Analytics، من المحتمل أن يكون لكل مهمة تقارير كثيرة بما أن كل تقرير يحتوي على بيانات لمدة 24 ساعة. سيتم عرض عدد أقل من التقارير للوظائف التي يديرها النظام والتي تغطي فترات زمنية أطول.يمكنك استخدام رقم تعريف التقرير لتحديد التقارير التي لا تزال بحاجة إلى تنزيلها واستيرادها. وإذا كان هناك تقريران جديدان يتضمّنان قيم السمات
startTimeوendTimeنفسها، عليك استيراد التقرير فقط بقيمةcreateTimeالأحدث.
-
خصائص التقرير
تصدر تقارير واجهة برمجة التطبيقات بإصدار ملفات .csv (قيم مفصولة بفواصل) وتتميز بالخصائص التالية:
-
يحتوي كل تقرير على بيانات لفترة فريدة تستمر من الساعة 12:00 صباحًا بتوقيت المحيط الهادئ في تاريخ بدء التقرير حتى 11:59 مساءً بتوقيت المحيط الهادئ في تاريخ انتهاء التقرير.
-
لا يتم ترتيب بيانات التقرير.