LiveChatMessages: list

تعرض هذه الطريقة رسائل المحادثة المباشرة لمحادثة معيّنة.

عند إجراء أول طلب لاسترداد رسائل المحادثة، تعرض واجهة برمجة التطبيقات بعض سجلّ المحادثة أو كلّه، وذلك حسب طول هذا السجلّ. تكون الرسائل في الردّ مرتّبة من الأقدم إلى الأحدث.
  • يوفّر الرمز nextPageToken في الردّ رمزًا سيحدّد في طلبك التالي المجموعة التالية من النتائج التي يجب أن يستردّها عميل واجهة برمجة التطبيقات.
  • تشير السمة pollingIntervalMillis إلى المدة التي يجب أن ينتظرها عميل واجهة برمجة التطبيقات قبل طلب نتائج إضافية.
عند طلب نتائج إضافية، اضبط المَعلمة pageToken على قيمة nextPageToken ويعرض خادم واجهة برمجة التطبيقات رسائل محادثة إضافية، إذا كانت متوفّرة. مرة أخرى، تكون الرسائل ضمن مجموعة النتائج هذه مرتّبة من الأقدم إلى الأحدث.

تأثير الحصة: تبلغ تكلفة الحصة لطلب البيانات من هذه الطريقة 5 وحدات.

حالات الاستخدام الشائعة

طلب

طلب HTTP

GET https://www.googleapis.com/youtube/v3/liveChat/messages

المعلمات

يسرد الجدول التالي المَعلمات التي يتيحها طلب البحث هذا. وكل المَعلمات المدرَجة هي مَعلمات طلب بحث.

المعلمات
المعلمات المطلوبة
liveChatId string
تحدّد المَعلمة liveChatId رقم تعريف المحادثة التي سيتم عرض رسائلها. ويتم عرض رقم تعريف المحادثة المباشرة المرتبط ببث في السمة snippet.liveChatId في مصدر liveBroadcast.
part string
تحدّد المَعلمة part أجزاء مصدر liveChatMessage التي سيتضمّنها الردّ من واجهة برمجة التطبيقات. القيمتان المسموح بهما هما id وsnippet وauthorDetails.
المعلمات الاختيارية
hl string
تطلب المَعلمة hl من واجهة برمجة التطبيقات استرداد سلسلة عرض عملة مترجَمة للغة تطبيق معيّنة يتيحها موقع YouTube الإلكتروني. على سبيل المثال، يتم عرض العملة باللغة الإنجليزية على النحو $1.50، ولكن يتم عرضها باللغة الفرنسية على النحو 1,50$.

يجب أن تكون قيمة المَعلمة رمز لغة مضمّنًا في القائمة التي تعرضها طريقة i18nLanguages.list.
maxResults unsigned integer

تحدّد المَعلمة maxResults الحد الأقصى لعدد الرسائل التي يجب عرضها في مجموعة النتائج. القيمتان المقبولتان هما 200 و2000، بما في ذلك هاتان القيمتان. القيمة التلقائية هي 500.

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

لا تستردّ واجهة برمجة التطبيقات الرسائل الأقدم من تلك التي تم عرضها في الطلب الأولي الذي تم إجراؤه بدون رمز متابعة.
pageToken string
تحدّد المَعلمة pageToken صفحة معيّنة في مجموعة النتائج يجب عرضها. في الردّ من واجهة برمجة التطبيقات، تحدّد السمة nextPageToken صفحات أخرى يمكن استردادها.
profileImageSize unsigned integer
تحدّد المَعلمة profileImageSize حجم صور ملفات المستخدمين الشخصية التي يجب عرضها في مجموعة النتائج. الصور مربّعة. القيمة التلقائية هي 88، ما يعني أنّ الصور ستكون بحجم 88 × 88 بكسل. القيم المقبولة هي في النطاق 16 إلى 720، بما في ذلك هاتان القيمتان.

نص الطلب

لا تُدرِج نص طلب عند طلب البيانات من هذه الطريقة.

الردّ

إذا كانت الاستجابة ناجحة، تعرض هذه الطريقة نص ردّ بالبنية التالية:

{
  "kind": "youtube#liveChatMessageListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pollingIntervalMillis": unsigned integer,
  "offlineAt": datetime,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    liveChatMessage Resource
  ],
  "activePollItem": liveChatMessage Resource
}

الخصائص

يحدّد الجدول التالي الخصائص التي تظهر في هذا المصدر:

الخصائص
kind string
يحدّد نوع مصدر واجهة برمجة التطبيقات. ستكون القيمة youtube#liveChatMessageListResponse.
etag etag
علامة Etag لهذا المصدر.
nextPageToken string
الرمز الذي يمكن استخدامه كقيمة للمَعلمة pageToken لاسترداد الصفحة التالية في مجموعة النتائج.
pollingIntervalMillis unsigned integer
مقدار الوقت بالملّي ثانية الذي يجب أن ينتظره العميل قبل استطلاع رسائل المحادثة المباشرة الجديدة مرة أخرى.
offlineAt datetime
التاريخ والوقت اللذان أصبح فيهما البث المباشر الأساسي غير متوفّر. لا تظهر هذه السمة إلا إذا كان البث غير متوفّر حاليًا. يتم تحديد القيمة بتنسيق ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
pageInfo object
يغلّف عنصر pageInfo معلومات تقسيم الصفحات لمجموعة النتائج.
pageInfo.totalResults integer
العدد الإجمالي للنتائج في مجموعة النتائج.
pageInfo.resultsPerPage integer
عدد النتائج المضمّنة في الردّ من واجهة برمجة التطبيقات.
items[] list
قائمة بالرسائل كل عنصر في القائمة هو مصدر liveChatMessage.
activePollItem object
بيانات الاستطلاع في الرسالة كل استطلاع هو مصدر liveChatMessage من النوع pollEvent، ما يمثّل استطلاعًا نشطًا. لا يمكن أن يكون هناك سوى استطلاع واحد لكل محادثة.

الأخطاء

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

نوع الخطأ تفاصيل الخطأ الوصف
forbidden (403) forbidden ليس لديك الأذونات المطلوبة لاسترداد رسائل المحادثة المباشرة المحدّدة.
forbidden (403) liveChatDisabled المحادثة المباشرة غير مفعَّلة للبث المحدّد.
forbidden (403) liveChatEnded لم تعُد المحادثة المباشرة المحدّدة نشطة.
notFound (404) liveChatNotFound تعذّر العثور على المحادثة المباشرة التي تحاول استردادها. تحقَّق من قيمة المَعلمة liveChatId في الطلب للتأكّد من أنّها صحيحة.
rateLimitExceeded rateLimitExceeded تم إرسال الطلب بسرعة كبيرة بعد الطلب السابق. يحدث هذا الخطأ عندما يتم إرسال طلبات البيانات من واجهة برمجة التطبيقات لاسترداد الرسائل بوتيرة أعلى من معدّلات التحديث في YouTube، ما يؤدي إلى إهدار النطاق الترددي بلا داعٍ.

جرِّبها الآن.

استخدِم APIs Explorer لطلب البيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب واجهة برمجة التطبيقات والردّ.