ملاحظة مهمة: تتطلّب طلبات واجهة برمجة التطبيقات التي يتم إرسالها إلى هذه الطريقة الآن إذن الوصول إلى نطاق https://www.googleapis.com/auth/youtube.readonly
.
تتيح لك هذه الطريقة استرداد العديد من تقارير "إحصاءات Google" المختلفة. يستخدم كل طلب مَعلمات طلب البحث لتحديد معرّف قناة أو مالك محتوى وتاريخ بدء وتاريخ انتهاء ومقياس واحد على الأقل. يمكنك أيضًا تقديم مَعلمات طلب بحث إضافية، مثل السمات والفلاتر وتعليمات الترتيب.
- المقاييس هي قياسات فردية لنشاط المستخدم، مثل عدد مشاهدات الفيديو أو التقييمات (الإعجاب وعدم الإعجاب).
- السمات هي معايير شائعة تُستخدَم لتجميع البيانات، مثل التاريخ الذي حدث فيه نشاط المستخدم أو البلد الذي كان يتواجد فيه المستخدمون. في التقرير، يحتوي كل صف من البيانات على مجموعة فريدة من قيم السمات.
- الفلاتر هي قيم سمات تحدّد البيانات التي سيتم استردادها. على سبيل المثال، يمكنك استرداد البيانات لبلد معيّن أو فيديو معيّن أو مجموعة من الفيديوهات.
ملاحظة: لا يمكن الوصول إلى تقارير مالك المحتوى إلا لشركاء المحتوى في YouTube المشاركين في برنامج شركاء YouTube.
حالات الاستخدام الشائعة
طلب
طلب HTTP
GET https://youtubeanalytics.googleapis.com/v2/reports
يجب أن يتم السماح بإرسال جميع طلبات البيانات من YouTube Analytics API. يوضّح دليل التفويض كيفية استخدام بروتوكول OAuth 2.0 لاسترداد رموز التفويض المميزة.
تستخدم طلبات البيانات من YouTube Analytics API نطاقات الأذونات التالية:
المستويات | |
---|---|
https://www.googleapis.com/auth/yt-analytics.readonly | عرض تقارير "إحصاءات YouTube" للمحتوى في YouTube يوفّر هذا النطاق إمكانية الوصول إلى مقاييس نشاط المستخدمين، مثل عدد المشاهدات وعدد التقييمات. |
https://www.googleapis.com/auth/yt-analytics-monetary.readonly | عرض تقارير "إحصاءات YouTube" المالية للمحتوى في YouTube يتيح هذا النطاق الوصول إلى مقاييس نشاط المستخدمين وإلى المقاييس المقدَّرة للأرباح وأداء الإعلانات. |
https://www.googleapis.com/auth/youtube | إدارة حسابك على YouTube في YouTube Analytics API، يستخدم مالكو القنوات هذا النطاق لإدارة مجموعات "إحصاءات YouTube" وعناصر المجموعات. |
https://www.googleapis.com/auth/youtubepartner | عرض وإدارة أصول YouTube والمحتوى المرتبط بها على YouTube في YouTube Analytics API، يستخدم مالكو المحتوى هذا النطاق لإدارة مجموعات "إحصاءات YouTube" وعناصر المجموعات. |
المعلمات
تعرض الجداول التالية مَعلمات طلب البحث المطلوبة والاختيارية لطلبات البيانات من واجهة برمجة التطبيقات من أجل استرداد تقارير طلبات البحث. إنّ مَعلمات طلب البحث العادية المدرَجة في الجدول اختيارية أيضًا وتتوافق مع العديد من واجهات Google APIs.
المعلمات | ||
---|---|---|
المَعلمات المطلوبة | ||
endDate |
string تاريخ انتهاء جلب بيانات YouTube Analytics. يجب أن تكون القيمة بالتنسيق YYYY-MM-DD .يحتوي ردّ واجهة برمجة التطبيقات على بيانات حتى آخر يوم تتوفّر فيه جميع المقاييس في طلب البحث في وقت طلب البحث. على سبيل المثال، إذا كان الطلب يحدّد تاريخ انتهاء في 5 يوليو 2017، وكانت قيم جميع المقاييس المطلوبة متاحة فقط حتى 3 يوليو 2017، سيكون هذا هو آخر تاريخ يتم تضمين البيانات فيه في الردّ. (ينطبق ذلك حتى إذا كانت بيانات بعض المقاييس المطلوبة متاحة ليوم 4 يوليو 2017). ملاحظة: في الإصدار 1 من واجهة برمجة التطبيقات، كان اسم هذه المَعلمة end-date |
|
ids |
string تحدّد هذه السمة قناة YouTube أو مالك المحتوى الذي تستردّ بيانات YouTube Analytics له.
|
|
metrics |
string قائمة مفصولة بفواصل تتضمّن مقاييس YouTube Analytics، مثل views أو likes,dislikes . راجِع مستندات تقارير القنوات أو تقارير مالك المحتوى للاطّلاع على قائمة بالتقارير التي يمكنك الحصول عليها والمقاييس المتاحة في كل تقرير. (يحتوي مستند المقاييس على تعريفات لجميع المقاييس).
|
|
startDate |
string تاريخ البدء لجلب بيانات YouTube Analytics. يجب أن تكون القيمة بالتنسيق YYYY-MM-DD .ملاحظة: في الإصدار 1 من واجهة برمجة التطبيقات، كان اسم هذه المَعلمة
start-date |
|
المَعلمات الاختيارية | ||
currency |
string تمثّل هذه السمة العملة التي ستستخدمها واجهة برمجة التطبيقات لتحديد مقاييس الأرباح المقدّرة التالية: estimatedRevenue وestimatedAdRevenue وestimatedRedPartnerRevenue وgrossRevenue وcpm وplaybackBasedCpm. القيم التي تعرضها واجهة برمجة التطبيقات لهذه المقاييس هي تقديرات يتم احتسابها باستخدام أسعار صرف تتغيّر يوميًا. إذا لم يتم طلب أي من هذه المقاييس، سيتم تجاهل المَعلمة. قيمة المَعلمة هي رمز عملة مكوّن من ثلاثة أحرف وفقًا لمعيار ISO 4217 من قائمة العملات أدناه. تعرض واجهة برمجة التطبيقات رسالة خطأ إذا تم تحديد عملة غير متوافقة. القيمة التلقائية هي USD . |
|
dimensions |
string تمثّل هذه المَعلمة قائمة مفصولة بفواصل لسمات "إحصاءات YouTube"، مثل video أو ageGroup,gender . يمكنك مراجعة وثائق تقارير القنوات أو تقارير مالك المحتوى للاطّلاع على قائمة بالتقارير التي يمكنك استردادها والسمات المستخدَمة في هذه التقارير. (يحتوي مستند السمات على تعريفات لجميع السمات).
|
|
filters |
string قائمة بالفلاتر التي يجب تطبيقها عند استرداد بيانات YouTube Analytics. تحدّد مستندات تقارير القنوات وتقارير مالكي المحتوى السمات التي يمكن استخدامها لفلترة كل تقرير، ويحدّد مستند السمات هذه السمات. إذا كان الطلب يستخدم فلاتر متعددة، ادمجها معًا باستخدام فاصلة منقوطة ( ; )، وسيلبّي جدول النتائج المعروض كلا الفلترَين. على سبيل المثال، تؤدي قيمة المَعلمة filters التي تبلغ video==dMH0bHeiRNg;country==IT إلى حصر مجموعة النتائج لتشمل بيانات الفيديو المحدّد في إيطاليا.تحديد قيم متعدّدة لفلتر تتيح واجهة برمجة التطبيقات إمكانية تحديد قيم متعدّدة للفلاتر video وplaylist وchannel . لإجراء ذلك، حدِّد قائمة مفصولة بمعرّفات الفيديوهات أو قوائم التشغيل أو القنوات التي يجب فلترة استجابة واجهة برمجة التطبيقات لها. على سبيل المثال، تؤدي قيمة المَعلمة filters التي تبلغ video==pd1FJh59zxQ,Zhawgd0REhA;country==IT إلى حصر مجموعة النتائج لتشمل بيانات الفيديوهات المحدّدة في إيطاليا. يمكن أن تحدّد قيمة المَعلمة ما يصل إلى 500 معرّف.عند تحديد قيم متعدّدة للفلتر نفسه، يمكنك أيضًا إضافة هذا الفلتر إلى قائمة السمات التي تحدّدها للطلب. وينطبق ذلك حتى إذا لم يتم إدراج الفلتر كسمة متوافقة مع تقرير معيّن. في حال أضفت الفلتر إلى قائمة السمات، تستخدم واجهة برمجة التطبيقات أيضًا قيم الفلتر لتجميع النتائج. على سبيل المثال، لنفترض أنّك تسترجع تقرير مصدر الزيارات الخاص بقناة معيّنة، والذي يجمع إحصاءات المشاهدة استنادًا إلى الطريقة التي وصل بها المشاهدون إلى محتوى الفيديو الخاص بالقناة. لنفترض أيضًا أنّ طلب المَعلمة filters في طلبك يحدّد قائمة تضم 10 فيديوهات يجب عرض البيانات الخاصة بها.
|
|
includeHistoricalChannelData |
boolean ملاحظة: لا تنطبق هذه المَعلمة إلا على تقارير مالك المحتوى. تحدّد هذه المَعلمة ما إذا كان يجب أن يتضمّن ردّ واجهة برمجة التطبيقات بيانات وقت المشاهدة وعدد المشاهدات للقنوات من الفترة الزمنية التي سبقت ربط القنوات بمالك المحتوى. قيمة المَعلمة التلقائية هي false ، ما يعني أنّ استجابة واجهة برمجة التطبيقات تتضمّن فقط بيانات وقت المشاهدة وعدد المشاهدات من التواريخ التي تم فيها ربط القنوات بمالك المحتوى.من المهم تذكُّر أنّه قد تم ربط قنوات مختلفة بمالك محتوى في تواريخ مختلفة. إذا كان طلب البيانات من واجهة برمجة التطبيقات يستردّ بيانات لقنوات متعددة وكانت قيمة المَعلمة هي false ، سيتضمّن ردّ واجهة برمجة التطبيقات بيانات استنادًا إلى تاريخ الربط لكل قناة على حدة. إذا كانت قيمة المَعلمة هي true ، سيتضمّن ردّ واجهة برمجة التطبيقات بيانات تتطابق مع التواريخ المحدّدة في طلب البيانات من واجهة برمجة التطبيقات.ملاحظة: في الإصدار 1 من واجهة برمجة التطبيقات، كان اسم هذه المَعلمة include-historical-channel-data |
|
maxResults |
integer الحد الأقصى لعدد الصفوف المطلوب تضمينها في الرد. ملاحظة: في الإصدار 1 من واجهة برمجة التطبيقات، كان اسم هذه المَعلمة max-results |
|
sort |
string قائمة مفصولة بفواصل تتضمّن السمات أو المقاييس التي تحدّد ترتيب الفرز لبيانات "إحصاءات YouTube". يكون ترتيب الفرز تصاعديًا تلقائيًا. تتسبّب البادئة - في ترتيب تصاعدي.
|
|
startIndex |
integer الفهرس المستند إلى الرقم 1 الخاص بالكيان الأول المطلوب استرداده. (القيمة التلقائية هي 1 .) استخدِم هذه المَعلمة كآلية تقسيم على صفحات مع المَعلمة max-results .ملاحظة: في الإصدار 1 من واجهة برمجة التطبيقات، كان اسم هذه المَعلمة start-index |
|
المَعلمات العادية | ||
access_token |
الرمز المميّز OAuth 2.0 للمستخدم الحالي
|
|
alt |
لا تتوافق هذه المَعلمة مع الإصدار 2 من واجهة برمجة التطبيقات الذي يتوافق فقط مع استجابات JSON.تنسيق البيانات لاستجابة واجهة برمجة التطبيقات.
|
|
callback |
دالّة رد الاتصال
|
|
prettyPrint |
تعرض هذه السمة الردود مع مسافات بادئة وفواصل أسطر.
|
|
quotaUser |
كانت هذه المَعلمة متاحة في الإصدار 1 من واجهة برمجة التطبيقات، ولكن تم إيقافها نهائيًا. لا تتوافق هذه المَعلمة مع الإصدار 2 من واجهة برمجة التطبيقات. | |
userIp |
كانت هذه المَعلمة متاحة في الإصدار 1 من واجهة برمجة التطبيقات، ولكن تم إيقافها نهائيًا. لا تتوافق هذه المَعلمة مع الإصدار 2 من واجهة برمجة التطبيقات. |
نص الطلب
لا ترسِل نص طلب عند استدعاء هذه الطريقة.
الردّ
كما هو موضّح في تعريف المَعلمة alt
، يمكن أن تعرض واجهة برمجة التطبيقات الردود بتنسيق JSON أو CSV. في ما يلي معلومات عن نص الاستجابة لكل نوع:
{ "kind": "youtubeAnalytics#resultTable", "columnHeaders": [ { "name": string, "dataType": string, "columnType": string }, ... more headers ... ], "rows": [ [ {value}, {value}, ... ] ] }
الخصائص | |
---|---|
kind |
string تحدّد هذه القيمة نوع البيانات المضمّنة في الردّ من واجهة برمجة التطبيقات. بالنسبة إلى الطريقة query ، ستكون قيمة السمة kind هي youtubeAnalytics#resultTable . ومع ذلك، إذا أضافت واجهة برمجة التطبيقات إمكانية استخدام طرق أخرى، قد تتضمّن استجابات واجهة برمجة التطبيقات لهذه الطرق قيمًا أخرى للسمة kind . |
columnHeaders[] |
list تحدّد هذه القيمة معلومات حول البيانات المعروضة في الحقول rows . يحدّد كل عنصر في القائمة columnHeaders حقلًا يتم عرضه في القيمة rows ، التي تحتوي على قائمة بالبيانات المفصولة بفواصل.تبدأ القائمة columnHeaders بالسمات المحدّدة في طلب واجهة برمجة التطبيقات، يليها المقاييس المحدّدة في طلب واجهة برمجة التطبيقات. يتطابق ترتيب كلّ من السمات والمقاييس مع الترتيب في طلب البيانات من واجهة برمجة التطبيقات.على سبيل المثال، إذا كان طلب البيانات من واجهة برمجة التطبيقات يتضمّن المَعلمات dimensions=ageGroup,gender&metrics=viewerPercentage ، سيعرض ردّ واجهة برمجة التطبيقات الأعمدة بهذا الترتيب: ageGroup وgender وviewerPercentage . |
columnHeaders[].name |
string تمثّل هذه السمة اسم السمة أو المقياس. |
columnHeaders[].columnType |
string نوع العمود ( DIMENSION أو METRIC ) |
columnHeaders[].dataType |
string نوع البيانات في العمود ( STRING أو INTEGER أو FLOAT أو غير ذلك) |
rows[] |
list تحتوي القائمة على جميع صفوف جدول النتائج. كل عنصر في القائمة هو مصفوفة تحتوي على بيانات مفصولة بفواصل وتتطابق مع صف واحد من البيانات. سيتطابق ترتيب حقول البيانات المفصولة بفواصل مع ترتيب الأعمدة المُدرَجة في الحقل columnHeaders .إذا لم تتوفّر أي بيانات للاستعلام المحدّد، سيتم حذف العنصر rows من الردّ.لن يحتوي الردّ على استعلام يتضمّن السمة day على صفوف لأحدث الأيام. |
day, views, likes, ... "2012-01-01", 12.0, 3, ... "2012-01-02", 16.0, 2, ... "2012-01-03", 18.0, 8, ... ...
أمثلة
ملاحظة: قد لا تمثّل عيّنات الرموز البرمجية التالية جميع لغات البرمجة المتوافقة. اطّلِع على مستندات مكتبات البرامج للحصول على قائمة باللغات المتوافقة.
JavaScript
يطلب هذا المثال من YouTube Analytics API استرداد عدد المشاهدات اليومية والمقاييس الأخرى الخاصة بقناة المستخدم الذي منح الإذن، وذلك للسنة التقويمية 2017. يستخدم النموذج مكتبة برامج JavaScript لواجهات Google APIs.قبل تشغيل هذا النموذج محليًا للمرة الأولى، عليك إعداد بيانات اعتماد التفويض لمشروعك:
- أنشِئ مشروعًا أو اختَر مشروعًا في وحدة تحكّم Google API.
- فعِّل YouTube Analytics API لمشروعك.
- في أعلى صفحة بيانات الاعتماد، اختَر علامة التبويب شاشة طلب الموافقة على OAuth. اختَر عنوان بريد إلكتروني، وأدخِل اسم منتج إذا لم يتم ضبطه من قبل، ثم انقر على زر "حفظ".
- في صفحة بيانات الاعتماد، انقر على الزر إنشاء بيانات اعتماد واختَر معرّف عميل OAuth.
- اختَر نوع التطبيق "تطبيق الويب".
- في حقل "مصادر JavaScript المسموح بها"، أدخِل عنوان URL الذي ستعرض منه نموذج الرمز. على سبيل المثال، يمكنك استخدام شيء مثل
http://localhost:8000
أوhttp://yourserver.example.com
. يمكنك ترك حقل "معرّفات الموارد المنتظمة (URI) المعتمَدة لإعادة التوجيه" فارغًا. - انقر على الزر إنشاء للانتهاء من إنشاء بيانات الاعتماد.
- قبل إغلاق مربّع الحوار، انسخ معرّف العميل الذي ستحتاج إلى وضعه في نموذج الرمز البرمجي.
بعد ذلك، احفظ العيّنة في ملف محلي. في النموذج، ابحث عن السطر التالي واستبدِل YOUR_CLIENT_ID بمعرّف العميل الذي حصلت عليه عند إعداد بيانات اعتماد التفويض.
gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'});
أنت الآن مستعد لاختبار العيّنة فعليًا:
- افتح الملف المحلي من متصفّح ويب، ثم افتح وحدة تصحيح الأخطاء في المتصفّح. من المفترض أن تظهر لك صفحة تعرض زرَّين.
- انقر على الزر تفويض وتحميل لبدء عملية تفويض المستخدم. إذا منحت التطبيق الإذن باسترداد بيانات قناتك، من المفترض أن تظهر الأسطر التالية في وحدة التحكّم في المتصفّح:
Sign-in successful GAPI client loaded for API
- إذا ظهرت لك رسالة خطأ بدلاً من الأسطر أعلاه، تأكَّد من أنّك تحمّل النص البرمجي من عنوان URI المصرّح به لإعادة التوجيه الذي أعددته لمشروعك، ومن أنّك وضعت معرّف العميل في الرمز كما هو موضّح أعلاه.
- انقر على الزر تنفيذ لاستدعاء واجهة برمجة التطبيقات. من المفترض أن يظهر لك كائن
response
مطبوع في وحدة التحكّم في المتصفّح. في هذا العنصر، يتم ربط السمةresult
بعنصر يحتوي على بيانات واجهة برمجة التطبيقات.
<script src="https://apis.google.com/js/api.js"></script> <script> function authenticate() { return gapi.auth2.getAuthInstance() .signIn({scope: "https://www.googleapis.com/auth/yt-analytics.readonly"}) .then(function() { console.log("Sign-in successful"); }, function(err) { console.error("Error signing in", err); }); } function loadClient() { return gapi.client.load("https://youtubeanalytics.googleapis.com/$discovery/rest?version=v2") .then(function() { console.log("GAPI client loaded for API"); }, function(err) { console.error("Error loading GAPI client for API", err); }); } // Make sure the client is loaded and sign-in is complete before calling this method. function execute() { return gapi.client.youtubeAnalytics.reports.query({ "ids": "channel==MINE", "startDate": "2017-01-01", "endDate": "2017-12-31", "metrics": "views,estimatedMinutesWatched,averageViewDuration,averageViewPercentage,subscribersGained", "dimensions": "day", "sort": "day" }) .then(function(response) { // Handle the results here (response.result has the parsed body). console.log("Response", response); }, function(err) { console.error("Execute error", err); }); } gapi.load("client:auth2", function() { gapi.auth2.init({client_id: 'YOUR_CLIENT_ID'}); }); </script> <button onclick="authenticate().then(loadClient)">authorize and load</button> <button onclick="execute()">execute</button>
Python
يطلب هذا المثال من YouTube Analytics API استرداد عدد المشاهدات اليومية والمقاييس الأخرى الخاصة بقناة المستخدم الذي منح الإذن، وذلك للسنة التقويمية 2017. يستخدم النموذج مكتبة برامج Google APIs للغة Python.قبل تشغيل هذا النموذج محليًا للمرة الأولى، عليك إعداد بيانات اعتماد التفويض لمشروعك:
- أنشِئ مشروعًا أو اختَر مشروعًا في وحدة تحكّم Google API.
- فعِّل YouTube Analytics API لمشروعك.
- في أعلى صفحة بيانات الاعتماد، اختَر علامة التبويب شاشة طلب الموافقة على OAuth. اختَر عنوان بريد إلكتروني، وأدخِل اسم منتج إذا لم يتم ضبطه من قبل، ثم انقر على زر "حفظ".
- في صفحة بيانات الاعتماد، انقر على الزر إنشاء بيانات اعتماد واختَر معرّف عميل OAuth.
- اختَر نوع التطبيق غير ذلك، وأدخِل الاسم "YouTube Analytics API Quickstart"، ثم انقر على الزر "إنشاء".
- انقر على حسنًا لإغلاق مربّع الحوار الناتج.
- انقر على الزر (تنزيل JSON) على يسار معرّف العميل.
- انقل الملف الذي تم تنزيله إلى دليل العمل.
عليك أيضًا تثبيت مكتبة برامج Google APIs للغة Python وبعض المكتبات الإضافية:
pip install --upgrade google-api-python-client pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2
أنت الآن مستعد لاختبار العيّنة فعليًا:
- انسخ نموذج الرمز البرمجي أدناه إلى دليل العمل.
- في النموذج، عدِّل قيمة المتغيّر
CLIENT_SECRETS_FILE
لتتطابق مع موقع الملف الذي نزّلته بعد إعداد بيانات اعتماد التفويض. - نفِّذ نموذج الرمز في نافذة الوحدة الطرفية:
python yt_analytics_v2.py
- اتّبِع خطوات عملية التفويض. قد يتم تحميل مسار المصادقة تلقائيًا في المتصفّح، أو قد تحتاج إلى نسخ عنوان URL الخاص بالمصادقة في نافذة متصفّح. في نهاية عملية التفويض، الصِق رمز التفويض المعروض في المتصفح في نافذة الوحدة الطرفية وانقر على [return]، إذا لزم الأمر.
- يتم تنفيذ طلب البحث من واجهة برمجة التطبيقات ويتم إخراج استجابة JSON إلى نافذة المحطة الطرفية.
# -*- coding: utf-8 -*- import os import google.oauth2.credentials import google_auth_oauthlib.flow from googleapiclient.discovery import build from googleapiclient.errors import HttpError from google_auth_oauthlib.flow import InstalledAppFlow SCOPES = ['https://www.googleapis.com/auth/yt-analytics.readonly'] API_SERVICE_NAME = 'youtubeAnalytics' API_VERSION = 'v2' CLIENT_SECRETS_FILE = 'YOUR_CLIENT_SECRET_FILE.json' def get_service(): flow = InstalledAppFlow.from_client_secrets_file(CLIENT_SECRETS_FILE, SCOPES) credentials = flow.run_console() return build(API_SERVICE_NAME, API_VERSION, credentials = credentials) def execute_api_request(client_library_function, **kwargs): response = client_library_function( **kwargs ).execute() print(response) if __name__ == '__main__': # Disable OAuthlib's HTTPs verification when running locally. # *DO NOT* leave this option enabled when running in production. os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1' youtubeAnalytics = get_service() execute_api_request( youtubeAnalytics.reports().query, ids='channel==MINE', startDate='2017-01-01', endDate='2017-12-31', metrics='estimatedMinutesWatched,views,likes,subscribersGained' dimensions='day', sort='day' )
جرِّبها الآن
استخدِم APIs Explorer لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب البيانات والاستجابة.