LiveChatMessages: list

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

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

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

طلب

طلب 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.
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 لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب البيانات والاستجابة.