LiveChatMessages: streamList

این روش یک اتصال استریمینگ سرور برقرار می‌کند که به شما امکان می‌دهد پیام‌های چت زنده را برای یک چت خاص با تأخیر کم دریافت کنید. این کارآمدترین روش برای استفاده از پیام‌های چت زنده است، زیرا پیام‌های جدید را به محض در دسترس بودن به کلاینت شما ارسال می‌کند، به جای اینکه شما را ملزم به نظرسنجی برای به‌روزرسانی‌ها کند.

وقتی برای اولین بار متصل می‌شوید، API مجموعه‌ای از پیام‌ها حاوی تاریخچه چت‌های اخیر را ارسال می‌کند. با ارسال پیام‌های جدید، سرور به ارسال آنها از طریق اتصال باز ادامه می‌دهد.

پیام‌های هر پاسخ سرور از قدیمی‌ترین به جدیدترین مرتب می‌شوند. هر پاسخ همچنین شامل یک nextPageToken است. اگر کلاینت شما قطع شود، می‌توانید از این توکن برای از سرگیری پخش جریان استفاده کنید. برای انجام این کار، آخرین nextPageToken دریافتی را به عنوان مقدار پارامتر pageToken در درخواست اتصال جدید خود ارائه دهید. سپس API ارسال پیام‌ها را از نقطه‌ای که متوقف شده بودید، از سر می‌گیرد.

نسخه آزمایشی

برای نمایش نمایشی پایتون از این نقطه پایانی، به راهنمای گفتگوی زنده استریمینگ مراجعه کنید.

درخواست

پارامترها

جدول زیر پارامترهایی را که این پرس و جو پشتیبانی می‌کند، فهرست می‌کند. همه پارامترهای ذکر شده، پارامترهای پرس و جو هستند.

پارامترها
پارامترهای مورد نیاز
liveChatId string
پارامتر liveChatId شناسه چتی را مشخص می‌کند که پیام‌های آن بازگردانده می‌شوند. شناسه چت زنده مرتبط با یک پخش، در ویژگی snippet.liveChatId از منبع liveBroadcast بازگردانده می‌شود.
part string
پارامتر part بخش‌های منبع liveChatMessage را که پاسخ API شامل آنها خواهد بود، مشخص می‌کند. مقادیر پشتیبانی شده عبارتند از id ، snippet و authorDetails .
پارامترهای اختیاری
hl string
پارامتر hl به API دستور می‌دهد تا یک رشته نمایش واحد پول محلی را برای یک زبان برنامه خاص که وب‌سایت YouTube از آن پشتیبانی می‌کند ، بازیابی کند. برای مثال، در انگلیسی، واحد پول به صورت $1.50 نمایش داده می‌شود، اما در فرانسوی، به صورت 1,50$ نمایش داده می‌شود.

مقدار پارامتر باید یک کد زبان باشد که در لیست برگردانده شده توسط متد i18nLanguages.list قرار دارد.
maxResults unsigned integer

پارامتر maxResults حداکثر تعداد پیام‌هایی را که باید در مجموعه نتایج برگردانده شوند، مشخص می‌کند. مقادیر قابل قبول 200 تا 2000 هستند. مقدار پیش‌فرض 500 است.

درخواست اولیه‌ای که بدون توکن ادامه ارسال شود، فقط شامل جدیدترین رویدادها خواهد بود. این مقدار در صورت ارائه، ممکن است از maxResults کوچکتر باشد.

این API رویدادهایی را که قدیمی‌تر از رویدادهایی هستند که با درخواست اولیه‌ی بدون توکن ادامه، برگردانده شده‌اند، بازیابی نمی‌کند.

pageToken string
پارامتر pageToken یک صفحه خاص را در مجموعه نتایج شناسایی می‌کند که باید بازگردانده شود. در یک پاسخ API، ویژگی nextPageToken صفحات دیگری را که می‌توانند بازیابی شوند، شناسایی می‌کند.
profileImageSize unsigned integer
پارامتر profileImageSize اندازه تصاویر پروفایل کاربر را که باید در مجموعه نتایج برگردانده شوند، مشخص می‌کند. تصاویر مربعی شکل هستند. مقدار پیش‌فرض 88 است، به این معنی که تصاویر ۸۸ پیکسل در ۸۸ پیکسل خواهند بود. مقادیر قابل قبول در محدوده 16 تا 720 هستند.

درخواست بدنه

هنگام فراخوانی این متد، بدنه درخواست (request body) ارائه ندهید.

پاسخ

در صورت موفقیت، این متد یک بدنه پاسخ با ساختار زیر برمی‌گرداند:

{
  "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
نوع منبع API را مشخص می‌کند. مقدار آن youtube#liveChatMessageListResponse خواهد بود.
etag etag
برچسب E این منبع.
nextPageToken string
توکنی که می‌تواند به عنوان مقدار پارامتر pageToken برای بازیابی صفحه بعدی در مجموعه نتایج استفاده شود.
offlineAt datetime
تاریخ و زمانی که پخش زنده‌ی مورد نظر آفلاین شده است. این ویژگی فقط در صورتی وجود دارد که پخش از قبل آفلاین باشد. مقدار آن در قالب ISO 8601 ( YYYY-MM-DDThh:mm:ss.sZ ) مشخص شده است.
pageInfo object
شیء pageInfo اطلاعات صفحه‌بندی را برای مجموعه نتایج کپسوله‌سازی می‌کند.
pageInfo. totalResults integer
تعداد کل نتایج در مجموعه نتایج.
pageInfo. resultsPerPage integer
تعداد نتایج موجود در پاسخ API.
items[] list
فهرستی از پیام‌ها. هر آیتم در این فهرست یک منبع liveChatMessage است.
activePollItem object
داده‌های نظرسنجی در پیام. هر نظرسنجی یک منبع liveChatMessage با نوع pollEvent است که نشان دهنده یک نظرسنجی فعال است. در هر چت فقط می‌توان یک نظرسنجی داشت.

خطاها

جدول زیر پیام‌های خطایی را که API می‌تواند در پاسخ به فراخوانی این متد برگرداند، مشخص می‌کند. برای جزئیات بیشتر به مستندات پیام خطا مراجعه کنید.

هنگام استفاده از 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 (eg check quota) درخواست خیلی سریع پس از درخواست قبلی ارسال شد. این خطا زمانی رخ می‌دهد که درخواست‌های API برای بازیابی پیام‌ها با سرعت بیشتری نسبت به نرخ به‌روزرسانی یوتیوب ارسال می‌شوند که باعث اتلاف غیرضروری پهنای باند می‌شود.

* به دلیل محدودیت gRPC، تشخیص تفاوت بین حالت LIVE_CHAT_DISABLED و LIVE_CHAT_ENDED بر اساس کد خطا امکان‌پذیر نیست. یوتیوب به طور فعال روی راه‌حلی برای رفع این مشکل کار می‌کند.

هنگام استفاده از ترافیک وب برای اتصال:

نوع خطا جزئیات خطا توضیحات
HttpStatus.FORBIDDEN (403) forbidden شما مجوزهای لازم برای بازیابی پیام‌های مربوط به گفتگوی زنده مشخص شده را ندارید.
HttpStatus.BAD_REQUEST (400) Reason for invalid request, eg 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 درخواست خیلی سریع پس از درخواست قبلی ارسال شد. این خطا زمانی رخ می‌دهد که درخواست‌های API برای بازیابی پیام‌ها با سرعت بیشتری نسبت به نرخ به‌روزرسانی یوتیوب ارسال می‌شوند که باعث اتلاف غیرضروری پهنای باند می‌شود.