LiveChatMessages: streamList

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

عند الاتصال لأول مرة، ترسل واجهة برمجة التطبيقات سلسلة من الرسائل التي تحتوي على سجلّ المحادثات الأخير. وعند نشر رسائل جديدة، سيواصل الخادم إرسالها من خلال الاتصال المفتوح.

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

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

عرض توضيحي

للحصول على عرض توضيحي بلغة Python لنقطة النهاية هذه، يُرجى الاطّلاع على دليل البث المباشر للمحادثة المباشرة.

طلب

المعلمات

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

المعلمات
المَعلمات المطلوبة
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 لاسترداد الصفحة التالية في مجموعة النتائج.
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، ويمثّل استطلاعًا نشطًا. يمكن إنشاء استطلاع واحد فقط لكل محادثة.

الأخطاء

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

عند استخدام gRPC للاتصال:

رمز خطأ gRPC تفاصيل الخطأ الوصف
PERMISSION_DENIED (7) The caller does not have permission ليس لديك الأذونات المطلوبة لاسترداد الرسائل من المحادثة المباشرة المحدّدة.
INVALID_ARGUMENT (3) Request contains an invalid argument تعذّر تحليل المَعلمات المقدَّمة. تأكَّد من أنّ مَعلمة liveChatId والمَعلمات الأخرى بالتنسيق الصحيح.
FAILED_PRECONDITION (9)* Precondition check failed LIVE_CHAT_DISABLED. المحادثة المباشرة المحدّدة غير مفعَّلة.
FAILED_PRECONDITION (9)* Precondition check failed LIVE_CHAT_ENDED. ولا يمكنك استرداد رسائل المحادثة المباشرة المنتهية.
NOT_FOUND (5) Requested entity was not found تعذّر العثور على المحادثة المباشرة التي تحاول استردادها. تحقَّق من قيمة مَعلمة liveChatId في الطلب للتأكّد من صحتها.
RESOURCE_EXHAUSTED (8) Resource has been exhausted (e.g. check quota) تم إرسال الطلب بسرعة كبيرة بعد الطلب السابق. يحدث هذا الخطأ عندما يتم إرسال طلبات بيانات من واجهة برمجة التطبيقات لاسترداد الرسائل بوتيرة أسرع من معدّلات إعادة التحميل في YouTube، ما يؤدي إلى إهدار النطاق الترددي بدون داعٍ.

* بسبب قيود gRPC، لا يمكن التمييز بين حالة LIVE_CHAT_DISABLED وحالة LIVE_CHAT_ENDED استنادًا إلى رمز الخطأ. ويعمل فريق YouTube جاهدًا على حلّ هذه المشكلة.

عند استخدام حركة المرور على الموقع الإلكتروني للاتصال:

نوع الخطأ تفاصيل الخطأ الوصف
HttpStatus.FORBIDDEN (403) forbidden ليس لديك الأذونات المطلوبة لاسترداد الرسائل من المحادثة المباشرة المحدّدة.
HttpStatus.BAD_REQUEST (400) Reason for invalid request, e.g. pageTokenInvalid تعذّر تحليل المَعلمات المقدَّمة. تأكَّد من أنّ مَعلمة liveChatId والمَعلمات الأخرى بالتنسيق الصحيح.
HttpStatus.FORBIDDEN (403) liveChatDisabled LIVE_CHAT_DISABLED. المحادثة المباشرة المحدّدة غير مفعَّلة.
HttpStatus.FORBIDDEN (403) liveChatEnded LIVE_CHAT_ENDED. لا يمكنك استرداد الرسائل من المحادثة المباشرة المنتهية.
HttpStatus.NOT_FOUND (404) liveChatNotFound تعذّر العثور على المحادثة المباشرة التي تحاول استردادها. تحقَّق من قيمة مَعلمة liveChatId في الطلب للتأكّد من صحتها.
HttpStatus.FORBIDDEN (403) rateLimitExceeded تم إرسال الطلب بسرعة كبيرة بعد الطلب السابق. يحدث هذا الخطأ عندما يتم إرسال طلبات بيانات من واجهة برمجة التطبيقات لاسترداد الرسائل بمعدّل أعلى من معدّلات إعادة التحميل في YouTube، ما يؤدي إلى إهدار معدل نقل البيانات بدون داعٍ.