LiveChatMessages: streamList

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

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

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

عرض توضيحي

للحصول على عرض توضيحي بلغة 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.
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، ما يؤدي إلى استهلاك النطاق الترددي بدون داعٍ.