يوضّح هذا المستند أوجه التشابه والاختلاف في الطرق التي تتيح بها واجهة برمجة التطبيقات 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 لصنّاع المحتوى. تتيح هذه التقارير إمكانية الوصول الآلي إلى بيانات أرباح الإعلانات. - نشاط المستخدم المتعلّق بالترجمة
- بيانات الاحتفاظ بالجمهور لقوائم التشغيل
- تقارير الأرباح المقدَّرة لمالكي المحتوى (يتوفّر تقريران مختلفان)
- تقارير مواد العرض لمالكي المحتوى (يتوفّر 11 تقريرًا مختلفًا)
التقارير المتاحة
يحدّد الجدول التالي الأنواع المختلفة من التقارير التي يمكنك استردادها باستخدام واجهات برمجة التطبيقات. وتتوفر طلبات البحث المستهدفة عبر YouTube Analytics API، وتتوفر التقارير المجمّعة عبر YouTube Reporting API.
فالبيانات المتوفرة في إحدى واجهات برمجة التطبيقات قد لا تكون متوفرة في الأخرى. على سبيل المثال، تتيح لك واجهة برمجة تطبيقات YouTube Analytics استرداد مقاييس نشاط المستخدم على أساس أسبوعي أو شهري، ولكن تتطلب منك واجهة برمجة التطبيقات لإعداد التقارير في YouTube تجميع تلك البيانات بنفسك. من ناحية أخرى، تتيح واجهة برمجة التطبيقات لإعداد التقارير في YouTube إمكانية إعداد تقارير مواد العرض لمالكي المحتوى، ولكن لا تتوفر هذه البيانات من واجهة برمجة تطبيقات YouTube Analytics.
| أنواع التقارير | |
|---|---|
| تقارير الفيديوهات | هذا الخيار متاح للقنوات (طلب بحث أو مجمّع) ومالكي المحتوى (طلب أو مجمّع). تقدّم تقارير الفيديو إحصاءات حول جميع أنشطة المستخدمين المرتبطة بالفيديوهات المنشورة على القناة أو بفيديوهات مالك المحتوى. على سبيل المثال، تتضمّن هذه التقارير عدد المشاهدات التي حصدتها فيديوهاتك. في YouTube Analytics API، تتضمّن بعض تقارير فيديوهات مالك المحتوى أيضًا مقاييس الأرباح وأداء الإعلانات المقدّرة. |
| تقارير قوائم التشغيل | هذا الخيار متاح للقنوات (طلب بحث أو مجمّع) ومالكي المحتوى (طلب أو مجمّع). تقدّم تقارير قوائم التشغيل إحصاءات مرتبطة تحديدًا بمشاهدات الفيديو التي تتم في سياق قائمة تشغيل. تتيح YouTube Reporting API إعداد تقارير حول الاحتفاظ بالجمهور لقوائم التشغيل، ولكن لا يمكن استخدام تقرير مماثل في YouTube Analytics API. |
| تقارير أداء الإعلان | يتوفر هذا الخيار لمالكي المحتوى (طلب بحث أو مجمّع). توفّر تقارير أداء الإعلانات مقاييس مستندة إلى مرّات الظهور للإعلانات التي تمّ عرضها خلال عمليات تشغيل الفيديوهات. تأخذ هذه المقاييس في الحسبان كل مرة ظهور للإعلان، ويمكن أن تؤدي كل عملية تشغيل للفيديو إلى مرات ظهور متعددة. |
| تقارير الأرباح المقدَّرة | هذا الخيار متاح لمالكي المحتوى (بشكل مجمّع). تقدّم تقارير الأرباح المقدّرة إجمالي الأرباح المقدّرة للفيديوهات الواردة من مصادر الإعلانات التي تبيعها Google والمصادر غير الإعلانية. تحتوي هذه التقارير أيضًا على بعض مقاييس أداء الإعلانات. تجدر الإشارة إلى أنّ التقارير التي يديرها النظام تتضمّن الأرباح الفعلية. |
| تقارير مواد العرض | هذا الخيار متاح لمالكي المحتوى (بشكل مجمّع). تقدّم تقارير مواد العرض مقاييس نشاط المستخدم المتعلّقة بالفيديوهات المرتبطة بمواد عرض مالك المحتوى. يتم تضمين فيديو في تقرير مالك المحتوى إذا كان مالك المحتوى قد طالب بملكية هذا الفيديو على أنّه محتوى مطابق لإحدى مواد العرض الخاصة به. من الممكن أن يكون قد حمّل الفيديو مالك المحتوى أو مستخدم آخر على YouTube. |
| التقارير التي يديرها النظام | تتوفر هذه الميزة لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير المناسبة في قائمة "التقارير" في "استوديو صنّاع المحتوى على YouTube". تقدّم التقارير التي يديرها النظام بيانات الأرباح الفعلية التي حقّقتها مواد العرض والفيديوهات. يتضمّن التقرير الإضافي قائمة بالفيديوهات التي تمّت المطالبة بملكيتها ومواد العرض التي تتطابق مع هذه الفيديوهات. تجدر الإشارة إلى أنّ واجهة برمجة التطبيقات لا تتوفّر حاليًا بعض تقارير "استوديو صنّاع المحتوى". ملاحظة: تنشئ منصة YouTube تلقائيًا تقارير يديرها النظام لمالكي المحتوى الذين يمكنهم الوصول إلى التقارير المقابلة في "استوديو صنّاع المحتوى". ونتيجةً لذلك، تختلف عملية استرداد هذه التقارير عن الأنواع الأخرى من التقارير في هذه القائمة. راجع وثائق التقارير التي يديرها النظام للحصول على مزيد من المعلومات. |
الاختلافات الرئيسية
يسلّط الجدول التالي الضوء على الاختلافات المهمة بين "إحصاءات YouTube" وواجهات برمجة التطبيقات لإعداد التقارير.
| إبراز | YouTube Analytics API | واجهة برمجة التطبيقات لإعداد التقارير في YouTube |
|---|---|---|
| عملية استرداد البيانات | يحدّد كل طلب من واجهة برمجة التطبيقات السمات والمقاييس التي سيتم عرضها، بالإضافة إلى الفترة الزمنية التي سيتم عرض البيانات خلالها. | وظائف إعداد تقارير بشأن جداول التطبيقات ينشئ YouTube تقارير يومية يمكن تنزيلها بشكل غير متزامن لكل مهمة. |
| النطاقات الزمنية | تحدّد بعض تقارير واجهة برمجة التطبيقات تاريخ حدوث نشاط المستخدم. وتتيح بعض هذه التقارير سمات لتجميع مقاييس نشاط المستخدم حسب الشهر. | تحدد جميع تقارير واجهة برمجة التطبيقات يوم حدوث نشاط المستخدم. يمكن للتطبيقات التي تستخدم واجهة برمجة التطبيقات تنفيذ ميزات لتجميع البيانات على فترات دورية. |
| فلترة البيانات | يمكنك فلترة التقارير لتضمين الصفوف التي يكون للسمة فيها قيمة معيّنة فقط. وتدعم واجهة برمجة التطبيقات أيضًا بعض الأبعاد، مثل القارة وsubContinent، التي تُستخدم كفلاتر فقط. | تتيح واجهة برمجة التطبيقات إجراء عمليات تنزيل مجمّعة لمجموعات البيانات الكاملة. ولا تتيح هذه الميزة فلترة البيانات أو عرضها للسمات المخصّصة للفلتر فقط. يخزن تطبيق العميل البيانات التي يتم تنزيلها وينفذ ميزاته الخاصة لتصفية البيانات. |
| التصنيف | يمكن ترتيب التقارير استنادًا إلى قيم المقاييس المعروضة. تحتوي بعض التقارير على عدد محدود فقط من النتائج. على سبيل المثال، يعرض التقرير الذي يعرض أكثر الفيديوهات مشاهدةً على القناة 200 صف كحدٍّ أقصى. | تتيح واجهة برمجة التطبيقات هذه إجراء عمليات تنزيل مجمّعة لمجموعات البيانات الكاملة. يمكن لتطبيقات العميل تنفيذ ميزاتها الخاصة لفرز البيانات التي يتم تنزيلها. |
| عمليات التعداد | تحتوي تقارير واجهة برمجة التطبيقات على قيم نصية، مثل "ANDROID" أو "CHANNEL"، لتحديد قيم السمات العددية. | تحتوي تقارير واجهة برمجة التطبيقات على أعداد صحيحة يمكن ربطها بقيم نصية. |
| الحصة | يقيّم خادم واجهة برمجة التطبيقات كل طلب بحث لتحديد تكلفة الحصة. يشرح قسم استخدام الحصة المنهجية بمزيد من التفصيل. | لا يمثل استخدام الحصة مشكلة لأنه يتم استرداد البيانات مرة واحدة ثم تصفيتها وفرزها والاستعلام عنها داخل التطبيق. |
| التقارير الفريدة |
|
|
| السمات الفريدة | group (سمة للفلتر فقط) continent (سمة الفلتر فقط) subContinent (سمة متعلقة بالفلتر فقط) الشهر isCurated==1 (مكوّن للفلتر فقط) viewsPerPlaylistStart averageTimeInPlaylist |
annotation_id annotation_type asset_id card_id card_type live_or_on_demand subscribed_status subtitle_language |
| المقاييس الفريدة | الفريدات relativeRetentionPerformance viewsPerPlaylistStart averageTimeInPlaylist |
card_click_rate card_clicks card_impressions<br class="ph-1-6" card_clicks<br class="ph-impression_rate<br class="br class="ph-1-1"> . card_teaser_click_ratecard_teaser_clickscard_teaser_impressionsestimated_partner_adsense_revenueestimated_partner_doubleclick_revenueplaylist_saves_addedplaylist_saves_removed |
الاختلافات في التسمية بين واجهات برمجة التطبيقات
تستخدِم واجهتا برمجة التطبيقات حاليًا اصطلاحات تسمية مختلفة لتحديد السمات والمقاييس. في الوقت الحالي، تستخدم أسماء YouTube Analytics API CamlCase، بينما تستخدم أسماء واجهة برمجة التطبيقات لإعداد التقارير في YouTube أسماءً يتم الفصل بينها باستخدام الشرطة السفلية.
تحدد الجداول التالية الأسماء المختلفة التي تستخدمها واجهتا برمجة التطبيقات لتحديد المقاييس والأبعاد نفسها. في بعض الحالات، يكون الفرق بين الاسمين أكبر مما ستحصل عليه بعد تحويل الاسم من CamlCase إلى شرطات سفلية. على سبيل المثال، تتم تسمية السمة video في واجهة برمجة تطبيقات YouTube Analytics باسم video_id في YouTube Reporting API.