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 است.
pageToken string
پارامتر pageToken صفحه خاصی را در مجموعه نتایج مشخص می کند که باید برگردانده شود. در یک پاسخ API، ویژگی 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
نوع منبع API را مشخص می کند. مقدار 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
تعداد نتایج موجود در پاسخ 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 برای بازیابی پیام‌ها بیشتر از نرخ‌های تازه‌سازی YouTube ارسال می‌شوند، که به‌طور غیر ضروری پهنای باند را هدر می‌دهد.

* به دلیل محدودیت 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 برای بازیابی پیام‌ها بیشتر از نرخ‌های تازه‌سازی YouTube ارسال می‌شوند، که به‌طور غیر ضروری پهنای باند را هدر می‌دهد.