توضّح هذه المستند أوجه التشابه والاختلاف في الطرق التي تتيح من خلالها واجهة YouTube Analytics API وواجهة YouTube Reporting API الوصول إلى بيانات "إحصاءات YouTube"، وذلك لمساعدتك في اختيار واجهة برمجة التطبيقات المناسبة لتطبيقك.
تتيح لك كلتا الواجهتين استرداد بيانات "إحصاءات YouTube". بالإضافة إلى ذلك، تتيح كلتا واجهتَي برمجة التطبيقات لمالكي قنوات YouTube ومالكي المحتوى على YouTube الوصول إلى مجموعة محدّدة من التقارير:
-
تحتوي تقارير القنوات على مقاييس نشاط المستخدمين لقناة محدّدة.
-
تجمع تقارير مالك المحتوى المقاييس من كل القنوات المرتبطة بمالك محتوى محدّد على YouTube. على سبيل المثال، يمكن لشركة إنتاج الحصول على تقرير يتضمّن إحصاءات مجمّعة لكل قنوات YouTube الخاصة بجميع الفنانين الذين يتعاملون مع شركة الإنتاج. تتضمّن بعض تقارير مالكي المحتوى مقاييس نشاط المستخدمين، بينما تتضمّن تقارير أخرى مقاييس مرتبطة بالإيرادات وأداء الإعلانات.
تتيح Reporting API أيضًا لبعض مالكي المحتوى الوصول إلى تقارير أرباح الإعلانات التي يديرها النظام. لا يمكن استرداد البيانات في التقارير المُدارة من قِبل النظام إلا باستخدام Reporting API.
يجب أن يسمح صاحب القناة أو مالك المحتوى الذي يملك البيانات المطلوبة بإرسال جميع طلبات البيانات من واجهات برمجة التطبيقات لإعداد التقارير في YouTube و"إحصاءات YouTube".
محتوى التقرير
تحتوي التقارير التي تستردّها واجهات برمجة التطبيقات على نوعَين من البيانات:
-
السمات هي معايير شائعة تُستخدَم لتجميع البيانات، مثل التاريخ الذي حدث فيه نشاط المستخدِم أو البلد الذي كان يتواجد فيه المستخدِمون.
في التقرير، يحتوي كل صف من البيانات على مجموعة فريدة من قيم السمات. وبالتالي، تعمل مجموعة قيم السمات في كل صف كمفتاح أساسي لهذا الصف.
-
المقاييس هي قياسات فردية لنشاط المستخدم أو أداء الإعلان أو الإيرادات المقدّرة. تشمل مقاييس نشاط المستخدمين عدد مشاهدات الفيديو والتقييمات (إبداء الإعجاب وعدم الإعجاب).
اختيار واجهة برمجة التطبيقات المناسبة لتطبيقك
- 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 Analytics API وReporting API.
| الميزة | YouTube Analytics API | واجهة برمجة التطبيقات لإعداد التقارير في YouTube |
|---|---|---|
| عملية استرداد البيانات | يحدّد كل طلب من واجهة برمجة التطبيقات السمات والمقاييس التي سيتم عرضها بالإضافة إلى الفترة الزمنية التي سيتم عرض البيانات فيها. | تجدول التطبيقات مهام إعداد التقارير. بالنسبة إلى كل مهمة، ينشئ YouTube تقارير يومية يمكن تنزيلها بشكل غير متزامن. |
| النطاقات الزمنية | تحدّد بعض تقارير واجهة برمجة التطبيقات التاريخ الذي حدث فيه نشاط المستخدم. تتيح بعض هذه التقارير سمات لتجميع مقاييس نشاط المستخدمين حسب الشهر. | تحدّد جميع تقارير واجهة برمجة التطبيقات اليوم الذي حدث فيه نشاط المستخدم. يمكن للتطبيقات التي تستخدم واجهة برمجة التطبيقات تنفيذ ميزات لتجميع البيانات على فترات دورية. |
| فلترة البيانات | يمكنك فلترة التقارير لتضمين الصفوف التي تتضمّن السمة قيمة معيّنة فقط. تتيح واجهة برمجة التطبيقات أيضًا بعض السمات، مثل continent و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.