تتيح لك واجهة YouTube Analytics API إنشاء تقارير مخصّصة تتضمّن بيانات "إحصاءات YouTube". تتيح واجهة برمجة التطبيقات إنشاء تقارير للقنوات ومالكي المحتوى. يتم تصنيف حقول التقارير على أنّها سمات أو مقاييس:
السمات هي معايير شائعة تُستخدَم لتجميع البيانات، مثل التاريخ الذي حدث فيه إجراء معيّن أو البلد الذي كان فيه المستخدمون.
في أي تقرير، يحتوي كل صف من البيانات على مجموعة فريدة من قيم السمات. وبالتالي، تحدّد السمات التي تختارها لتقرير معيّن الطريقة التي يتّبعها YouTube لاحتساب قيم المقاييس في هذا التقرير.
المقاييس هي قياسات فردية تتعلّق بنشاط المستخدم أو أداء الإعلان أو الإيرادات المقدَّرة. تشمل مقاييس نشاط المستخدمين عناصر مثل عدد مشاهدات الفيديو والتقييمات (الإعجابات وعدم الإعجابات).
توفّر واجهة Analytics API مَعلمات للفلترة والترتيب، لذا لا يحتاج التطبيق الذي يطلب البيانات إلى أن يكون متوافقًا مع هذه الوظائف بشكلٍ أصلي. تتيح لك واجهة برمجة التطبيقات أيضًا استرداد البيانات لمجموعات "إحصاءات YouTube"، حيث تكون المجموعة عبارة عن مجموعة مخصّصة تضم ما يصل إلى 500 فيديو أو قائمة تشغيل أو قناة أو مادة عرض.
اختيار مَعلمات التقارير
عند طلب تقرير باستخدام طريقة reports.query في واجهة برمجة التطبيقات، يحتوي طلب واجهة برمجة التطبيقات على خمس مَعلمات تحدّد كيفية احتساب قيم التقرير:
تحدّد المَعلمتان
startDateوendDateالفترة الزمنية التي سيحتوي التقرير على بياناتها. يتضمّن الردّ من واجهة برمجة التطبيقات في الواقع بيانات حتى آخر يوم محدّد تتوفّر فيه جميع المقاييس في طلب البحث في وقت إجراء الطلب.تحدّد المَعلمة
metricsالقياسات التي سيتم تضمينها في التقرير. في تقارير القنوات، تقيس المقاييس نشاط المستخدمين وتتضمّن قيمًا مثل المشاهدات والمعجبون. تقيس بعض المقاييس أيضًا أداء الإعلانات أو الإيرادات المقدَّرة.توضّح المَعلمة
dimensionsكيفية تجميع المقاييس.توضّح المَعلمة
filtersكيفية فلترة بيانات التقرير. على سبيل المثال، بدلاً من عرض كل البيانات الخاصة بقناة معيّنة، يمكن فلترة التقرير ليتضمّن فقط المقاييس الخاصة ببلد أو فيديو أو مجموعة فيديوهات معيّنة.ملاحظة: تتيح لك واجهة برمجة التطبيقات تحديد قيم متعددة لفلاتر الفيديو وقائمة التشغيل والقناة. في هذه الحالة، يمكنك أيضًا تضمين هذا الفلتر في قائمة السمات ليتم تجميع المقاييس التي يتم عرضها حسب الفيديو أو قائمة التشغيل أو القناة.
خيارات الإبلاغ عن العيّنات
على سبيل المثال، لنفترض أنّ مالك قناة يريد استرداد تقرير حول نوع الجهاز المستخدم لمشاهدة الفيديوهات من أجل تحديد عدد مشاهدات فيديوهات القناة على الأجهزة الجوّالة ووحدات تحكّم الألعاب وأجهزة التلفزيون وما إلى ذلك.
يضبط مالك القناة المَعلمة
startDateعلى2015-06-01والمَعلمةendDateعلى2015-07-31. استنادًا إلى هذه القيم، سيحتوي التقرير على بيانات لفترة شهرين.يتيح تقرير نوع الجهاز استخدام مقياسَي views وestimatedMinutesWatched، لذا يضبط مالك القناة المَعلمة
metricsعلىviews,estimatedMinutesWatched.بالنسبة إلى المَعلمة
dimensions، يتوفّر لمالك القناة عدد من الخيارات. يتم عرض اثنين منهما في القائمة التالية، وتتم مناقشة الثالث في شرح قيمة المَعلمةfiltersلاحقًا في هذا القسم.يعني ضبط قيمة المَعلمة على
deviceTypeأنّه سيتم تجميع عدد المشاهدات ووقت المشاهدة حسب نوع الجهاز لكامل الفترة التي يغطيها التقرير. لذا، باستخدام هذه القيمة، ستجيب بيانات التقرير عن أسئلة مثل:كم مرّة تمّت مشاهدة فيديوهات القناة على الأجهزة الجوّالة بين 1 حزيران (يونيو) 2015 و31 تموز (يوليو) 2015؟
كم مرّة تمّت مشاهدة فيديوهات القناة على وحدات تحكّم الألعاب بين 1 حزيران (يونيو) 2015 و31 تموز (يوليو) 2015؟
سيحتوي التقرير على إجمالي عدد المشاهدات ووقت المشاهدة لكل نوع جهاز.
يعني ضبط قيمة المَعلمة على
day,deviceTypeأنّه سيتم احتساب عدد المشاهدات ووقت المشاهدة حسب نوع الجهاز لكل يوم خلال الفترة المشمولة بالتقرير. لذا، باستخدام هذه القيمة، ستجيب بيانات التقرير عن أسئلة مثل:كم مرة تمت مشاهدة فيديوهات القناة على الأجهزة الجوّالة في 1 يونيو 2015؟
كم مرة تمت مشاهدة فيديوهات القناة على أجهزة التلفزيون في 14 يوليو 2015؟
أخيرًا، تتيح المَعلمة
filtersلمالك القناة حصر التقرير بالبيانات التي تتطابق مع قيم فلاتر معيّنة. يتيح التقرير العديد من خيارات الفلترة التي يصعب شرحها جميعًا، لذا تمثّل هذه الأمثلة جزءًا صغيرًا فقط من التقارير التي يمكنك إنشاؤها.يمكن لمالك القناة فلترة الطلب لعرض القيم لنظام التشغيل Android فقط. (كم عدد المشاهدات التي تم تسجيلها على أجهزة Android الجوّالة خلال الفترة المشمولة بالتقارير؟)
ويمكن لمالك القناة فلترة الطلب لعرض القيم الخاصة ببلد معيّن فقط. (كم عدد المرات التي تمت فيها مشاهدة الفيديوهات في كندا في كل يوم من الفترة المشمولة بالتقرير؟)
ويمكن لمالك القناة فلترة الطلب لعرض قيم لفيديوهات معيّنة فقط. ومع ذلك، يتيح فلتر video استخدام قائمة قيم مفصولة بفاصلة، لذا يمكن أن يحتوي التقرير على بيانات لعدة فيديوهات.
بالإضافة إلى ذلك، إذا كان فلتر video يحدّد قيمًا متعددة، يمكن أيضًا تحديد video كسمة. وهذا يعني أنّ المَعلمة
dimensionsتتيح أيضًا استخدام القيمتَينdeviceType,videoوday,deviceType,video.- إذا أدرج مالك القناة الفيديو في قائمة السمات، تحدّد المقاييس قيمًا فردية لكل فيديو. (كم مرة تمت مشاهدة الفيديو XYZ على وحدة تحكم الألعاب في 1 يونيو 2015؟)
- إذا لم يدرج مالك القناة video في قائمة السمات، ستحدّد المقاييس القيم الإجمالية التي تشمل جميع الفيديوهات المحدّدة. (كم مرة تمت مشاهدة الفيديوهات ABC وDEF وXYZ على وحدة تحكم الألعاب في 1 يونيو 2015؟)
سرعة توفُّر البيانات ووقت الاستجابة
على الرغم من أنّ YouTube Analytics API تتيح استخدام الطلبات المستهدفة، فإنّ بيانات الإحصاءات الأساسية لا تكون في الوقت الفعلي. تؤدي معالجة البيانات عادةً إلى حدوث تأخير
يتراوح بين 48 و72 ساعة. لذلك، لا تحتوي الردود من واجهة برمجة التطبيقات على بيانات الأيام الأخيرة، ولا يتضمّن endDate لتقريرك سوى البيانات حتى آخر يوم تمت فيه معالجة جميع المقاييس المطلوبة بالكامل.
بسبب وقت استجابة البيانات، قد تلاحظون اختلافات بين البيانات التي تعرضها واجهة برمجة التطبيقات والمقاييس في الوقت الفعلي التي تظهر في "استوديو YouTube". إذا كان تطبيقك يتطلّب إحصاءات في الوقت الفعلي لفيديوهات فردية، مثل عدد المشاهدات أو المعجبين أو التعليقات الحالية، استخدِم طريقة videos.list في YouTube Data API بدلاً من YouTube Analytics API.
جارٍ استرداد التقارير
لاسترداد تقرير، أرسِل طلب استرداد بيانات باستخدام GET إلى طريقة reports.query في واجهة برمجة التطبيقات، مع تحديد المَعلمات التي تحدّد التقرير الذي تريد استرداده.
يمكنك الاطّلاع على مستندات تقارير القنوات وتقارير مالكي المحتوى للحصول على قائمة بالتقارير التي تتيحها واجهة برمجة التطبيقات. يحدّد كل تعريف تقرير القيم التي يسمح بها التقرير لمَعلمات metrics وdimensions وfilters.
أفضل الممارسات
يجب أن تتّبع التطبيقات التي تستخدم YouTube Analytics API هذه الممارسات دائمًا:
- استخدِم صف عنوان الردّ لتحديد ترتيب أعمدة التقرير. على سبيل المثال، لا تفترض أنّ المشاهدات ستكون المقياس الأول الذي يتم عرضه في الردّ لمجرد أنّه المقياس الأول المُدرَج في وصف التقرير. بدلاً من ذلك، استخدِم صف عنوان الردّ لتحديد العمود الذي يحتوي على هذه البيانات.
- استخدِم YouTube Data API لاسترداد بيانات وصفية إضافية للموارد المحدّدة في ردود YouTube Analytics API. كما هو موضّح في سياسات مطوّري خدمات YouTube API (الأقسام من III.E.4.b إلى III.E.4.d)، على عملاء واجهة برمجة التطبيقات إما حذف أو إعادة تحميل البيانات الوصفية للموارد المخزّنة من واجهة برمجة التطبيقات هذه بعد 30 يومًا.
المقاييس المجمّعة والعناصر المحذوفة
لا تحتوي الردود من واجهة برمجة التطبيقات YouTube Analytics API على تفاصيل المقاييس للعناصر المحذوفة. على سبيل المثال، إذا حذف مالك القناة فيديو، لن يظهر هذا الفيديو في ردّ من واجهة برمجة التطبيقات يعرض المقاييس لكل فيديو على حدة. ومع ذلك، فإن التقارير التي تجمع المقاييس لمجموعة من الموارد لا تزال تتضمن المقاييس المرتبطة بالعناصر المحذوفة.
على سبيل المثال، لنفترض أنّ مالك قناة يستردّ تقريرَين. يعرض التقرير الأول إجمالي عدد المشاهدات اليومية لجميع فيديوهات القناة خلال فترة زمنية معيّنة. أمّا التقرير الثاني، فيعرض إجمالي عدد المشاهدات اليومية لكل فيديو على حدة خلال الفترة الزمنية نفسها.
في هذه الحالة، ستشمل الأرقام في التقرير الأول مشاهدات الفيديوهات التي تم حذفها لاحقًا لأنّ التقرير الأول يحتوي على إجماليات يومية. ومع ذلك، لن يتضمّن التقرير الثاني المشاهدات المرتبطة بالعناصر المحذوفة لأنّه يعرض المشاهدات لكل فيديو على حدة. نتيجةً لذلك، إذا حذفت القناة فيديوهات خلال الفترة الزمنية التي يغطيها التقرير، قد يكون إجمالي عدد المشاهدات اليومية في التقرير الأول أعلى من مجموع عدد المشاهدات اليومية لكل فيديو في التقرير الثاني.
إخفاء هوية البيانات
تكون بعض بيانات "إحصاءات YouTube" محدودة عندما لا تستوفي المقاييس حدًا معيّنًا. ويمكن أن يحدث ذلك في مجموعة متنوّعة من التقارير. من الناحية العملية، يعني ذلك أنّ التقرير قد لا يتضمّن كل بياناتك (أو أيًا منها) في الحالات التالية:
إذا كان عدد الزيارات إلى فيديو أو قناة محدودًا خلال فترة زمنية محددة
أو
إذا اخترت فلترًا أو سمة، مثل مصدر الزيارات أو البلد، ولم تتوفر بيانات كافية مرتبطة بهما
في الحالات التي تكون فيها البيانات محدودة، قد تلاحظ تباينًا بين القيم الإجمالية الواردة في تقارير مختلفة استنادًا إلى كيفية تجميع البيانات في هذه التقارير.
على سبيل المثال، لنفترض أنّ مالك قناة يستردّ تقريرَين. يعرض التقرير الأول إجمالي عدد المشاهدات لفيديو معيّن، ويعرض التقرير الثاني إجمالي عدد المشاهدات لهذا الفيديو حسب البلد. لِنفترض أيضًا أنّه خلال الفترة الزمنية المحدّدة تمت مشاهدة الفيديو 1,000 مرة، منها 500 مشاهدة في الكويت، و498 مشاهدة في مصر، ومشاهدتَين في البحرين.
في هذا المثال، يشير التقرير الأول إلى أنّه تمّت مشاهدة الفيديو 1, 000 مرة. سيشير التقرير الثاني فقط إلى أنّه تمّت مشاهدة الفيديو 500 مرّة في الكويت و498 مرّة في مصر. بالتالي، ستلاحظ تباينًا بين إجمالي عدد المشاهدات في التقريرَين. يُرجى العِلم أنّ التقرير الثاني لن يتضمّن أي إشارة إلى أنّ الفيديو حصد أيضًا مشاهدتَين (أو أنّه حصد أي مشاهدات في فرنسا).
أنواع البيانات المحدودة
قد تكون البيانات التالية محدودة في تقارير "إحصاءات YouTube":
- بيانات الخصائص الديمغرافية، مثل العمر والجنس
- البيانات الجغرافية، بما في ذلك المقاييس أو السمات المتعلّقة بالبلدان أو المناطق التي يقيم فيها المشاهدون، مثل بلدانهم أو مناطقهم يُرجى العِلم أنّ التقارير لا تطبّق الحدود الدنيا للمواقع الجغرافية على مقاييس الإيرادات.
- المقاييس المرتبطة بمصادر زيارات معيّنة، مثل عبارات البحث أو عناوين URL الخارجية التي أدّت إلى مشاهدة فيديوهاتك على سبيل المثال، لن تظهر في التقارير عبارات البحث وعناوين URL التي تجذب عددًا قليلاً جدًا من المشاهدات، ولكن ستظهر العبارات وعناوين URL التي تجذب عددًا كبيرًا من المشاهدين إلى محتواك.
يمكنك الانتقال إلى مركز مساعدة YouTube للحصول على مزيد من المعلومات حول البيانات المحدودة في تقارير "إحصاءات YouTube".
مقدار استخدام الحصة
يتم احتساب كل طلب بيانات من واجهة برمجة التطبيقات كوحدة واحدة من حصة استخدام واجهة برمجة التطبيقات. تظهر حدود الحصص في لوحة الحصص في Google Cloud Console.