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