LiveChatMessages: streamList

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

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

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

تأثیر سهمیه: فراخوانی این روش هزینه سهمیه ۵ واحدی دارد.

پخش نمایشی

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

درخواست

پارامترها

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

پارامترها
پارامترهای الزامی
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 صفحه خاصی را در مجموعه نتایج که باید برگردانده شود شناسایی می‌کند. در پاسخ میانای برنامه‌سازی کاربردی، ویژگی nextPageToken صفحه‌های دیگری را که می‌توان بازیابی کرد شناسایی می‌کند.
profileImageSize unsigned integer
پارامتر profileImageSize اندازه عکس‌های نمایه کاربر را که باید در مجموعه نتایج برگردانده شود مشخص می‌کند. تصاویر مربعی هستند. مقدار پیش‌فرض 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 پایان‌یافته را بازیابی کنید.
NOT_FOUND (5) Requested entity was not found گپ مستقیمی که می‌خواهید بازیابی کنید پیدا نشد. مقدار پارامتر liveChatId درخواست را بررسی کنید تا مطمئن شوید درست باشد.
RESOURCE_EXHAUSTED (8) Resource has been exhausted (e.g. check quota) درخواست خیلی زود پس‌از درخواست قبلی ارسال شد. این خطا زمانی رخ می‌دهد که درخواست‌های API برای بازیابی پیام‌ها با تناوبی بیشتر از نرخ بازآوری 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 گپ مستقیم پایان یافت. نمی‌توانید پیام‌های گپ زنده پایان‌یافته را بازیابی کنید.
HttpStatus.NOT_FOUND (404) liveChatNotFound گپ مستقیمی که می‌خواهید بازیابی کنید پیدا نشد. مقدار پارامتر liveChatId درخواست را بررسی کنید تا مطمئن شوید درست باشد.
HttpStatus.FORBIDDEN (403) rateLimitExceeded درخواست خیلی زود پس‌از درخواست قبلی ارسال شد. این خطا زمانی رخ می‌دهد که درخواست‌های API برای بازیابی پیام‌ها بیشتر از نرخ‌های بازآوری YouTube ارسال می‌شوند که باعث هدر رفتن غیرضروری پهنای باند می‌شود.