عند تقديم طلبك الأول لاسترداد رسائل المحادثة، تعرض واجهة برمجة التطبيقات جزءًا من سجلّ المحادثات أو جزءًا منه استنادًا إلى مدة ذلك السجلّ. يتم ترتيب الرسائل في الردّ من الأقدم إلى الأحدث.
- يوفّر
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 . |
activePollItem |
object بيانات الاستطلاع في الرسالة كل استطلاع هو مورد liveChatMessage من النوع pollEvent ، والذي يمثل استطلاعًا نشطًا. يمكن إجراء استطلاع واحد فقط في كل محادثة. |
الأخطاء
يحدّد الجدول التالي رسائل الخطأ التي يمكن أن تعرضها واجهة برمجة التطبيقات استجابةً لطلب بيانات إلى هذه الطريقة. راجِع مستندات رسالة الخطأ للحصول على م��يد من التفاصيل.
نوع الخطأ | تفاصيل الخطأ | الوصف |
---|---|---|
forbidden (403) |
forbidden |
ليس لديك الأذونات المطلوبة لاسترداد الرسائل في المحادثة المباشرة المحدّدة. |
forbidden (403) |
liveChatDisabled |
لم يتم تفعيل المحادثة المباشرة للبث المحدّد. |
forbidden (403) |
liveChatEnded |
المحادثة المباشرة المحدّدة لم تعُد منشورة. |
notFound (404) |
liveChatNotFound |
يتعذر العثور على المحادثة المباشرة التي تحاول استردادها. تحقّق من قيمة معلَمة liveChatId للطلب للتأكّد من صحتها. |
rateLimitExceeded |
rateLimitExceeded |
تم إرسال الطلب بعد وقت قصير جدًا من الطلب السابق. يحدث هذا الخطأ عندما يتم إرسال طلبات واجهة برمجة التطبيقات لاسترداد الرسائل بمعدل تكرار أعلى من معدلات تحديث YouTube، ما يؤدي إلى هدر معدل نقل البيانات بدون داعٍ. |
تجربة
يمكنك استخدام APIs Explorer لطلب بيانات من واجهة برمجة التطبيقات هذه والاطّلاع على طلب البيانات من واجهة برمجة التطبيقات والاستجابة لها.