يوضّح هذا المستند أوجه التشابه والاختلاف في الطرق التي تتيح من خلالها واجهة YouTube Analytics API وواجهة YouTube Reporting API الوصول إلى بيانات "إحصاءات YouTube"، وذلك لمساعدتك في اختيار واجهة برمجة التطبيقات المناسبة لتطبيقك.
تتيح لك كلتا الواجهتين استرداد بيانات "إحصاءات YouTube". بالإضافة إلى ذلك، تتيح كلتا واجهتَي برمجة التطبيقات لمالكي قنوات YouTube ومالكي المحتوى على YouTube الوصول إلى مجموعة محدّدة من التقارير:
-
تحتوي تقارير القنوات على مقاييس نشاط المستخدمين لقناة محدّدة.
-
تجمع تقارير مالك المحتوى المقاييس من كل القنوات المرتبطة بمالك محتوى محدّد على YouTube. على سبيل المثال، يمكن لشركة إنتاج الحصول على تقرير يتضمّن إحصاءات مجمّعة لكل قنوات YouTube الخاصة بجميع الفنانين الذين يتعاملون مع شركة الإنتاج. تتضمّن بعض تقارير مالكي المحتوى مقاييس لنشاط المستخدمين، بينما تتضمّن تقارير أخرى مقاييس متعلّقة بالأرباح وأداء الإعلانات.
تتيح Reporting API أيضًا لبعض مالكي المحتوى الوصول إلى تقارير إيرادات الإعلانات التي يديرها النظام. لا يمكن استرداد البيانات في التقارير المُدارة من قِبل النظام إلا باستخدام Reporting API.
يجب أن يوافق صاحب القناة أو مالك المحتوى الذي يملك البيانات المطلوبة على جميع طلبات البيانات من واجهات إحصاءات YouTube وYouTube Reporting API.
محتوى التقرير
تحتوي التقارير التي تستردّها واجهات برمجة التطبيقات على نوعَين من البيانات:
-
السمات هي معايير شائعة تُستخدَم لتجميع البيانات، مثل التاريخ الذي حدث فيه نشاط المستخدم أو البلد الذي كان يتواجد فيه المستخدمون.
في التقرير، يحتوي كل صف من البيانات على مجموعة فريدة من قيم السمات. وبالتالي، تعمل مجموعة قيم السمات في كل صف كمفتاح أساسي لهذا الصف.
-
المقاييس هي قياسات فردية لنشاط المستخدم أو أداء الإعلان أو الأرباح المقدّرة. تشمل مقاييس نشاط المستخدمين عدد مشاهدات الفيديو والتقييمات (إبداء الإعجاب وعدم الإعجاب).
اختيار واجهة برمجة التطبيقات المناسبة لتطبيقك
- YouTube Analytics API
- تتيح YouTube Analytics API استخدام الطلبات المستهدَفة في الوقت الفعلي لإنشاء تقارير مخصّصة في "إحصاءات YouTube". توفّر واجهة برمجة التطبيقات مَعلمات الفلترة والترتيب، لذا لا يحتاج التطبيق الذي يتم استدعاؤه إلى توفير هذه الوظائف بشكلٍ أصلي.
يحدّد كل طلب بيانات من واجهة برمجة التطبيقات النطاق الزمني الذي سيتم عرض البيانات الخاصة به. تتيح لك واجهة برمجة التطبيقات أيضًا استرداد مجموعات البيانات الأسبوعية والشهرية. وبالتالي، لا يحتاج تطبيق الاتصال إلى تخزين مجموعات البيانات التي تم استردادها أو تجميع الإحصاءات على مستوى النطاقات الزمنية. - واجهة برمجة التطبيقات لإعداد التقارير في YouTube
- تتيح YouTube Reporting API استرداد التقارير المجمّعة التي تتضمّن بيانات "إحصاءات YouTube" لقناة أو مالك محتوى. وهي مصمَّمة للتطبيقات التي يمكنها استيراد مجموعات بيانات كبيرة وتوفير أدوات لفلترة تلك البيانات وترتيبها وتحليلها.
يحتوي كل تقرير على مجموعة محدّدة مسبقًا من الحقول. يمكنك استخدام واجهة برمجة التطبيقات لجدولة مهام إعداد التقارير، ويحدّد كل منها تقريرًا يجب أن ينشئه YouTube. بعد ذلك، ينشئ YouTube تقريرًا يوميًا يمكن تنزيله بشكل غير متزامن. يحتوي كل تقرير على بيانات لفترة 24 ساعة فريدة.
بالإضافة إلى ذلك، ينشئ YouTube تلقائيًا مجموعة من التقارير التي يديرها النظام لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير ذات الصلة في استوديو صنّاع المحتوى في YouTube. توفر هذه التقارير إمكانية الوصول الآلي إلى بيانات إيرادات الإعلانات.
التقارير المتاحة
يوضّح الجدول التالي الأنواع المختلفة من التقارير التي يمكنك استردادها باستخدام واجهات برمجة التطبيقات. تتوفّر الطلبات المستهدَفة باستخدام YouTube Analytics API، وتتوفّر التقارير المجمّعة باستخدام YouTube Reporting API.
قد لا تتوفّر البيانات المتاحة في إحدى واجهات برمجة التطبيقات في الأخرى. على سبيل المثال، تتيح لك واجهة YouTube Analytics API استرداد مقاييس نشاط المستخدم على أساس أسبوعي أو شهري، ولكن تتطلّب منك واجهة YouTube Reporting API تجميع هذه البيانات بنفسك. من ناحية أخرى، تتيح واجهة YouTube Reporting API لمالكي المحتوى إعداد تقارير مواد العرض، ولكنّ هذه البيانات غير متاحة من خلال واجهة YouTube Analytics API.
| أنواع التقارير | |
|---|---|
| تقارير الفيديو | تتوفّر هذه الطريقة للقنوات (طلب أو مجمّع) ومالكي المحتوى (طلب أو مجمّع). تقدّم تقارير الفيديوهات إحصاءات حول جميع أنشطة المستخدمين المرتبطة بفيديوهات قناة أو فيديوهات مالك محتوى. على سبيل المثال، تحتوي هذه التقارير على عدد المشاهدات التي حقّقتها فيديوهاتك. في YouTube Analytics API، تتضمّن بعض تقارير الفيديو الخاصة بمالك المحتوى أيضًا مقاييس الأرباح المقدّرة وأداء الإعلان. |
| تقارير مستوى وصول المحتوى إلى الجمهور | متاحة للقنوات (بشكل مجمّع) ومالكي المحتوى (بشكل مجمّع). تتوفّر مقاييس "مستوى الوصول إلى الجمهور" أيضًا في تقارير الفيديو لطلبات البحث المستهدَفة. تقدّم تقارير "الوصول إلى الجمهور" إحصاءات عن مرّات ظهور الصور المصغّرة للفيديوهات ونِسب النقر إلى الظهور. |
| تقارير قوائم التشغيل | تتوفّر هذه الطريقة للقنوات (طلب أو مجمّع) ومالكي المحتوى (طلب أو مجمّع). تقدّم تقارير قوائم التشغيل إحصاءات مرتبطة تحديدًا بمشاهدات الفيديوهات التي تحدث في سياق قائمة تشغيل. تتيح واجهة YouTube Reporting API إعداد تقارير الاحتفاظ بالجمهور لقوائم التشغيل، ولكنّ واجهة YouTube Analytics API لا تتيح إعداد تقرير مماثل. |
| تقارير أداء الإعلان | متاحة لمالكي المحتوى (طلب بحث أو عمليات مجمّعة). توفّر تقارير أداء الإعلانات مقاييس مستندة إلى عدد مرّات الظهور للإعلانات التي تم عرضها أثناء تشغيل الفيديوهات. تأخذ هذه المقاييس في الاعتبار كل مرة ظهور للإعلان، ويمكن أن يؤدي كل تشغيل للفيديو إلى مرات ظهور متعددة. |
| تقارير الأرباح المقدَّرة | متاحة لمالكي المحتوى (عمليات مجمّعة). تقدّم تقارير الأرباح المقدّرة إجمالي الأرباح المقدّرة من الفيديوهات من مصادر الإعلانات التي تبيعها Google ومن المصادر غير الإعلانية. تحتوي هذه التقارير أيضًا على بعض مقاييس أداء الإعلانات. يُرجى العِلم أنّ التقارير المُدارة بواسطة النظام تتضمّن الإيرادات الفعلية. |
| تقارير مواد العرض | متاحة لمالكي المحتوى (عمليات مجمّعة). تقدّم تقارير مواد العرض مقاييس نشاط المستخدمين المرتبطة بالفيديوهات التي تم ربطها بمواد عرض تابعة لمالك المحتوى. يتم تضمين فيديو في تقرير مالك المحتوى إذا طالب هذا المالك بملكية الفيديو على أنّه محتوى مطابق لإحدى مواد العرض الخاصة به. قد يكون مالك المحتوى أو مستخدم آخر على YouTube قد حمّل الفيديو. |
| التقارير التي يديرها النظام | تتوفّر هذه الميزة لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير ذات الصلة في قائمة "التقارير" في "استوديو YouTube". تقدّم التقارير المُدارة بواسطة النظام بيانات فعلية عن الإيرادات الناتجة من مواد العرض والفيديوهات. يتضمّن تقرير إضافي قائمة بالفيديوهات التي تمّت المطالبة بملكيتها ومواد العرض التي تتطابق مع هذه الفيديوهات. لا تتوفّر جميع تقارير "استوديو YouTube" في واجهة برمجة التطبيقات. ملاحظة: ينشئ YouTube تلقائيًا تقارير تديرها الأنظمة لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير المقابلة في "استوديو YouTube". نتيجةً لذلك، تختلف عملية استرداد هذه التقارير عن أنواع التقارير الأخرى في هذه القائمة. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات التقارير التي يديرها النظام. |
الاختلافات الرئيسية
يوضّح الجدول التالي الاختلافات المهمة بين واجهتَي إحصاءات YouTube API وReporting API.
| الميزة | YouTube Analytics API | واجهة برمجة التطبيقات لإعداد التقارير في YouTube |
|---|---|---|
| عملية استرداد البيانات | يحدّد كل طلب بيانات من واجهة برمجة التطبيقات السمات والمقاييس المطلوب عرضها بالإضافة إلى الفترة الزمنية التي سيتم عرض البيانات الخاصة بها. | تجدول التطبيقات مهام إعداد التقارير. بالنسبة إلى كل مهمة، ينشئ YouTube تقارير يومية يمكن تنزيلها بشكل غير متزامن. |
| النطاقات الزمنية | تحدّد بعض تقارير واجهة برمجة التطبيقات التاريخ الذي حدث فيه نشاط المستخدم. تتيح بعض هذه التقارير استخدام سمات لتجميع مقاييس نشاط المستخدمين حسب الشهر. | تحدّد جميع تقارير واجهة برمجة التطبيقات اليوم الذي حدث فيه نشاط المستخدم. يمكن للتطبيقات التي تستخدم واجهة برمجة التطبيقات تنفيذ ميزات لتجميع البيانات على فترات منتظمة. |
| فلترة البيانات | يمكنك فلترة التقارير لتضمين الصفوف التي تتضمّن السمة قيمة معيّنة فقط. تتيح واجهة برمجة التطبيقات أيضًا بعض السمات، مثل القارة وsubContinent، التي تُستخدَم كفلاتر فقط. | تتيح واجهة برمجة التطبيقات تنزيل مجموعات كاملة من البيانات بشكل مجمّع. لا يتيح فلترة البيانات أو عرضها للسمات التي يمكن استخدامها كفلاتر فقط. يخزِّن تطبيق العميل البيانات التي تم تنزيلها وينفِّذ ميزاته الخاصة لتصفية البيانات. |
| ترتيب | يمكن ترتيب التقارير استنادًا إلى قيم المقاييس التي تم عرضها. تتيح بعض التقارير عددًا محدودًا فقط من النتائج. على سبيل المثال، يعرض التقرير الذي يسرد الفيديوهات الأكثر مشاهدة في قناة ما 200 صف كحدّ أقصى. | تتيح واجهة برمجة التطبيقات هذه تنزيل مجموعات كاملة من البيانات بشكل مجمّع. يمكن لتطبيقات العميل تنفيذ ميزاتها الخاصة لترتيب البيانات التي تم تنزيلها. |
| التعدادات | تحتوي تقارير واجهة برمجة التطبيقات على قيم نصية، مثل "ANDROID" أو "CHANNEL"، لتحديد قيم السمات المُعدَّدة. | تحتوي تقارير واجهة برمجة التطبيقات على أعداد صحيحة يمكن ربطها بقيم نصية. |
| الحصة | يقيّم خادم واجهة برمجة التطبيقات كل طلب لتحديد تكلفة الحصة. يوضّح قسم استخدام الحصة المنهجية بمزيد من التفصيل. | لا يشكّل استخدام الحصة مشكلة لأنّه يتم استرداد البيانات مرة واحدة ثم يتم فلترتها وفرزها والاستعلام عنها داخل التطبيق. |
| التقارير الفريدة |
|
|
| السمات الفريدة | group (سمة خاصة بالفلاتر فقط) continent (سمة خاصة بالفلاتر فقط) subContinent (سمة خاصة بالفلاتر فقط) month viewsPerPlaylistStart averageTimeInPlaylist |
annotation_id annotation_type asset_id card_id card_type live_or_on_demand subscribed_status subtitle_language |
| المقاييس الفريدة | uniques relativeRetentionPerformance viewsPerPlaylistStart averageTimeInPlaylist |
card_click_rate card_clicks card_impressions card_teaser_click_rate card_teaser_clicks card_teaser_impressions estimated_partner_adsense_revenue estimated_partner_doubleclick_revenue playlist_saves_added playlist_saves_removed |
الاختلافات في التسمية بين واجهات برمجة التطبيقات
تستخدم واجهتا برمجة التطبيقات قواعد تسمية مختلفة لتحديد السمات والمقاييس. تستخدم أسماء YouTube Analytics API أسلوب camelCase، مثل adType. تكون أسماء واجهة YouTube Reporting API بأحرف صغيرة وتستخدم شرطات سفلية، مثل ad_type.
تحدّد الجداول التالية الأسماء المختلفة التي تستخدمها واجهتا برمجة التطبيقات لتحديد المقاييس والسمات نفسها. في بعض الحالات، يكون الفرق بين الاسمين أكبر من الفرق الذي ستحصل عليه بعد تحويل اسم من camelCase إلى شرطات سفلية. على سبيل المثال، يُطلق على السمة video في YouTube Analytics API الاسم video_id في YouTube Reporting API.