YouTube Analytics API - Data Model

تتيح لك واجهة YouTube Analytics API إنشاء تقارير مخصّصة تتضمّن بيانات "إحصاءات YouTube". تتيح واجهة برمجة التطبيقات إعداد تقارير للقنوات ومالكي المحتوى. يتم تصنيف حقول التقارير على أنّها سمات أو مقاييس:

• السمات هي معايير شائعة تُستخدَم لتجميع البيانات، مثل تاريخ وقوع إجراء معيّن أو البلد الذي كان يتواجد فيه المستخدِمون.

  في التقرير، يحتوي كل صف من البيانات على مجموعة فريدة من قيم السمات. وبالتالي، تحدّد السمات التي تختارها لتقرير معيّن الطريقة التي يحتسب بها YouTube قيم المقاييس في هذا التقرير.

• المقاييس هي قياسات فردية مرتبطة بنشاط المستخدم أو أداء الإعلان أو الأرباح المقدّرة. تشمل مقاييس نشاط المستخدمين عدد مشاهدات الفيديو والتقييمات (إبداء الإعجاب وعدم الإعجاب).

توفّر واجهة برمجة التطبيقات لإعداد التقارير مَعلمات الفلترة والترتيب، لذلك لا يحتاج التطبيق الذي يتم استدعاؤه إلى توفير هذه الوظائف بشكلٍ أصلي. تتيح لك واجهة برمجة التطبيقات أيضًا استرداد بيانات مجموعات "إحصاءات YouTube"، حيث تكون المجموعة عبارة عن مجموعة مخصّصة تضمّ ما يصل إلى 500 فيديو أو قائمة تشغيل أو قناة أو مادة عرض.

اختيار مَعلمات التقرير

عند طلب تقرير باستخدام طريقة reports.query في واجهة برمجة التطبيقات، يتضمّن طلب البيانات من واجهة برمجة التطبيقات خمس مَعلمات تحدّد طريقة احتساب قيم التقرير:

• تحدّد المَعلمتان startDate وendDate الفترة الزمنية التي سيتضمّن التقرير بياناتها. في الواقع، يحتوي ردّ واجهة برمجة التطبيقات على بيانات حتى آخر يوم محدّد تتوفّر فيه جميع المقاييس في طلب البحث في وقت طلب البحث.

• تحدّد المَعلمة metrics القياسات التي سيتم تضمينها في التقرير. في تقارير القنوات، تقيس المقاييس نشاط المستخدمين وتشمل قيمًا مثل المشاهدات والإعجابات. تقيس بعض المقاييس أيضًا أداء الإعلان أو الإيرادات المقدّرة.

• توضّح المَعلمة dimensions كيفية تجميع المقاييس.

• توضّح المَعلمة filters كيفية فلترة بيانات التقرير. لذلك، بدلاً من عرض كل البيانات الخاصة بقناة معيّنة، يمكن فلترة التقرير ليحتوي فقط على مقاييس خاصة ببلد أو فيديو أو مجموعة فيديوهات معيّنة.

  ملاحظة: تتيح لك واجهة برمجة التطبيقات تحديد قيم متعددة لفلاتر الفيديو وقائمة التشغيل والقناة. في حال إجراء ذلك، يمكنك أيضًا تضمين هذا الفلتر في قائمة السمات ليتم أيضًا تجميع المقاييس التي تم إرجاعها حسب الفيديو أو قائمة التشغيل أو القناة.

خيارات إعداد التقارير النموذجية

على سبيل المثال، لنفترض أنّ مالك قناة يريد استرداد تقرير عن نوع جهاز الفيديو لتحديد عدد مشاهدات فيديوهات القناة على الأجهزة الجوّالة ووحدات تحكّم الألعاب وأجهزة التلفزيون وما إلى ذلك.

• يضبط مالك القناة المَعلمة startDate على 2015-06-01 والمَعلمة endDate على 2015-07-31. استنادًا إلى هذه القيم، سيحتوي التقرير على بيانات لفترة شهرَين.

• يتوافق تقرير "نوع الجهاز" مع مقياسَي المشاهدات وestimatedMinutesWatched، لذا يضبط مالك القناة المَعلمة metrics على views,estimatedMinutesWatched.

• بالنسبة إلى المَعلمة dimensions، يتوفّر لمالك القناة عدد من الخيارات. يتم عرض اثنتَين منها في القائمة التالية، ويتم تناول الثالثة في شرح قيمة المَعلمة filters لاحقًا في هذا القسم.

  • ضبط قيمة المَعلمة على deviceType يعني أنّه سيتم تجميع عدد المشاهدات وعدد ساعات المشاهدة حسب نوع الجهاز طوال الفترة التي يغطيها التقرير. وبالتالي، باستخدام هذه القيمة، ستجيب بيانات التقرير عن أسئلة مثل:

    • كم مرّة تمت مشاهدة فيديوهات القناة على الأجهزة الجوّالة بين 1 يونيو 2015 و31 يوليو 2015؟
    • كم مرّة تمت مشاهدة فيديوهات القناة على وحدات تحكّم الألعاب بين 1 يونيو 2015 و31 يوليو 2015؟

    سيتضمّن التقرير إجمالي عدد المشاهدات ووقت المشاهدة لكل نوع جهاز.

  • يعني ضبط قيمة المَعلمة على day,deviceType أنّه سيتم احتساب عدد المشاهدات وعدد ساعات المشاهدة حسب نوع الجهاز لكل يوم خلال الفترة المحدّدة في التقرير. وبالتالي، باستخدام هذه القيمة، ستجيب بيانات التقرير عن أسئلة مثل:

    • كم مرّة تمت مشاهدة فيديوهات القناة على الأجهزة الجوّالة في 1 يونيو 2015؟
    • كم مرّة تمت مشاهدة فيديوهات القناة على أجهزة التلفزيون في 14 يوليو 2015؟

• أخيرًا، تسمح المَعلمة filters لصاحب القناة بحصر التقرير ليشمل فقط البيانات التي تطابق قيم فلتر معيّنة. يتيح التقرير عددًا كبيرًا جدًا من خيارات الفلترة التي لا يمكن شرحها كلها، لذا تمثّل هذه الأمثلة جزءًا صغيرًا فقط من التقارير التي يمكنك إنشاؤها.

  • يمكن لمالك القناة فلترة الطلب لعرض القيم الخاصة بنظام التشغيل Android فقط. (كم عدد المشاهدات التي حدثت على أجهزة Android الجوّالة خلال الفترة المشمولة بالتقارير؟)

  • يمكن لمالك القناة فلترة الطلب لعرض القيم الخاصة ببلد معيّن فقط. (كم مرّة تمت مشاهدة الفيديوهات في كندا في كل يوم من الفترة المشمولة بالتقرير؟)

  • يمكن لمالك القناة فلترة الطلب لعرض قيم لفيديوهات معيّنة فقط. ومع ذلك، يتيح فلتر الفيديو إدخال قائمة قيم مفصولة بينها فواصل، لذا قد يحتوي التقرير في الواقع على بيانات خاصة بالعديد من الفيديوهات.

    بالإضافة إلى ذلك، إذا كان فلتر الفيديو يحدّد قيمًا متعددة، يمكن أيضًا تحديد الفيديو كمكوّن. وهذا يعني أنّ المَعلمة dimensions تتوافق أيضًا مع القيمتَين deviceType,video وday,deviceType,video.

    • إذا أدرج مالك القناة الفيديو في قائمة السمات، ستحدّد المقاييس قيمًا فردية لكل فيديو. (كم مرّة تمت مشاهدة الفيديو XYZ على وحدة تحكّم بالألعاب في 1 يونيو 2015؟)
    • إذا لم يدرِج مالك القناة الفيديو في قائمة السمات، ستحدّد المقاييس القيم الإجمالية التي تشمل كل الفيديوهات المحدّدة. (كم مرّة تمت مشاهدة الفيديوهات ABC وDEF وXYZ على وحدة تحكّم بالألعاب في 1 يونيو 2015؟)

استرداد التقارير

لاسترداد تقرير، أرسِل طلب GET معتمدًا إلى طريقة reports.query في واجهة برمجة التطبيقات، مع تحديد المَعلمات التي تحدّد التقرير الذي تريد استرداده.

اطّلِع على مستندات تقارير القنوات وتقارير مالكي المحتوى للحصول على قائمة بالتقارير التي تتيحها واجهة برمجة التطبيقات. يحدّد كل تعريف تقرير القيم التي يسمح بها التقرير للمَعلمات metrics وdimensions وfilters.

أفضل الممارسات

يجب أن تلتزم التطبيقات التي تستخدم YouTube Analytics API دائمًا بالممارسات التالية:

• استخدِم صف العنوان الخاص بالردّ لتحديد ترتيب أعمدة التقرير. على سبيل المثال، لا تفترض أنّ المشاهدات ستكون المقياس الأول الذي يتم عرضه في الردّ لمجرّد أنّه المقياس الأول المُدرَج في وصف التقرير. بدلاً من ذلك، استخدِم صف العناوين في الردّ لتحديد العمود الذي يحتوي على هذه البيانات.
• استخدِم YouTube Data API لاسترداد بيانات وصفية إضافية للمراجع المحدّدة في ردود YouTube Analytics API. كما هو موضّح في سياسات مطوّر خدمات واجهة برمجة تطبيقات YouTube (الفقرات من III.E.4.b إلى III.E.4.d)، يجب أن يحذف عملاء واجهة برمجة التطبيقات بيانات وصفية للموارد المخزّنة من واجهة برمجة التطبيقات هذه أو يعيد تحميلها بعد 30 يومًا.

المقاييس المجمّعة والعناصر المحذوفة

لا تحتوي ردود YouTube Analytics API على تقسيمات مقاييس للعناصر المحذوفة. على سبيل المثال، إذا حذف مالك قناة فيديو، لن يتم إدراج هذا الفيديو بعد ذلك في ردّ واجهة برمجة التطبيقات الذي يعرض المقاييس على أساس كل فيديو على حدة. ومع ذلك، لا تزال التقارير التي تجمع المقاييس لمجموعة من المراجع تتضمّن مقاييس مرتبطة بالعناصر المحذوفة.

على سبيل المثال، لنفترض أنّ مالك قناة يستردّ تقريرَين. يسرد التقرير الأول إجمالي المشاهدات اليومية لجميع فيديوهات القناة خلال فترة زمنية معيّنة. يسرد التقرير الثاني إجمالي المشاهدات اليومية لكل فيديو على حدة خلال الفترة الزمنية نفسها.

في هذه الحالة، ستتضمّن الأرقام الواردة في التقرير الأول مشاهدات الفيديوهات التي تم حذفها لاحقًا لأنّ التقرير الأول يحتوي على إحصاءات مجمّعة يومية. ومع ذلك، لن يتضمّن التقرير الثاني المشاهدات المرتبطة بالعناصر المحذوفة لأنّه يعرض المشاهدات على أساس كل فيديو على حدة. نتيجةً لذلك، إذا حذفت القناة فيديوهات خلال الفترة الزمنية التي يغطيها التقرير، قد يكون إجمالي عدد المشاهدات اليومية الوارد في التقرير الأول أعلى من مجموع عدد المشاهدات اليومية الخاصة بالفيديوهات في التقرير الثاني.

إخفاء هوية البيانات

تكون بعض بيانات "إحصاءات YouTube" محدودة عندما لا تستوفي المقاييس حدًا معيّنًا. يمكن أن يحدث ذلك في مجموعة متنوّعة من التقارير. في الواقع، يعني ذلك أنّ التقرير قد لا يتضمّن كل بياناتك (أو أيًا منها) في الحالات التالية:

1. إذا كان عدد الزيارات إلى الفيديو أو القناة محدودًا خلال فترة زمنية محدّدة

   أو

2. إذا اخترت فلترًا أو سمة، مثل مصدر الزيارات أو البلد، ولم تتوفر بيانات كافية مرتبطة بهما

في الحالات التي تكون فيها البيانات محدودة، قد تلاحظ تباينًا بين القيم الإجمالية الواردة في تقارير مختلفة استنادًا إلى كيفية تجميع البيانات في هذه التقارير.

على سبيل المثال، لنفترض أنّ مالك قناة يستردّ تقريرَين. يعرض التقرير الأول إجمالي عدد المشاهدات لفيديو معيّن، بينما يعرض التقرير الثاني إجمالي عدد المشاهدات لهذا الفيديو في كل بلد. لنفترض أيضًا أنّه خلال الفترة الزمنية المحدّدة تمت مشاهدة الفيديو 1,000 مرة، منها 500 مشاهدة في الولايات المتحدة، و498 مشاهدة في كندا، ومشاهدتَين في فرنسا.

في هذا المثال، يشير التقرير الأول إلى أنّه تمّت مشاهدة الفيديو 1, 000 مرّة. سيشير التقرير الثاني فقط إلى أنّه تمّت مشاهدة الفيديو 500 مرّة في الولايات المتحدة و498 مرّة في كندا. بالتالي، ستلاحظ تباينًا بين إجمالي عدد المشاهدات في التقريرَين. يُرجى العِلم أنّ التقرير الثاني لن يتضمّن أي إشارة إلى أنّ الفيديو حصد أيضًا مشاهدتَين (أو أي مشاهدات في فرنسا).

إنّ الحدّ الأدنى المطلوب لاعتبار البيانات كافية ليس منشورًا للعلن، وهو عرضة للتغيير وفقًا لتقدير YouTube.

أنواع البيانات المحدودة

قد تكون البيانات التالية محدودة في تقارير "إحصاءات YouTube":

• بيانات الخصائص الديمغرافية، مثل العمر والجنس
• البيانات الجغرافية، بما في ذلك المقاييس أو السمات المتعلّقة بالبلدان أو المناطق التي يقيم فيها المشاهدون، مثل بلدانهم أو مناطقهم يُرجى العِلم أنّ التقارير لا تطبّق حدودًا جغرافية على مقاييس الأرباح.
• مقاييس مرتبطة بمصادر زيارات معيّنة، مثل عبارات البحث أو عناوين URL الخارجية التي أدّت إلى مشاهدة فيديوهاتك على سبيل المثال، لن تظهر عبارات البحث وعناوين URL التي تؤدي إلى عدد قليل جدًا من المشاهدات في التقارير، ولكن ستظهر تلك التي تجذب عددًا كبيرًا من المشاهدين إلى محتوى قناتك.

يمكنك الانتقال إلى مركز المساعدة في YouTube للحصول على مزيد من المعلومات حول البيانات المحدودة في تقارير "إحصاءات YouTube".

مقدار استخدام الحصة

يُحتسب كل طلب ترسله إلى واجهة برمجة التطبيقات كوحدة واحدة من حصة استخدام واجهة برمجة التطبيقات. تظهر حدود الحصة في لوحة الحصص في "وحدة تحكّم Google API".