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
  ]
}

أماكن إقامة

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

أماكن إقامة
kind string
يحدّد نوع مورد واجهة برمجة التطبيقات. ستكون القيمة youtube#liveChatMessageListResponse.
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.

الأخطاء

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

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

تجربة

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