LiveChatMessages: list

پیام‌های چت زنده را برای یک چت خاص فهرست می‌کند.

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

موارد استفاده رایج

درخواست کنید

درخواست HTTP 

GET https://www.googleapis.com/youtube/v3/liveChat/messages

پارامترها

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

پارامترها
پارامترهای مورد نیاز
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 برای بازیابی صفحه بعدی در مجموعه نتایج استفاده شود.
pollingIntervalMillis unsigned integer
مقدار زمانی، بر حسب میلی ثانیه، که مشتری باید قبل از نظرسنجی مجدد برای پیام‌های چت زنده جدید منتظر بماند.
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 می تواند در پاسخ به تماس با این روش بازگرداند. برای جزئیات بیشتر به مستندات پیام خطا مراجعه کنید.

نوع خطا جزئیات خطا توضیحات
forbidden (403) forbidden شما مجوزهای لازم برای بازیابی پیام ها برای چت زنده مشخص شده را ندارید.
forbidden (403) liveChatDisabled چت زنده برای پخش مشخص شده فعال نیست.
forbidden (403) liveChatEnded چت زنده مشخص شده دیگر زنده نیست.
notFound (404) liveChatNotFound چت زنده ای که می خواهید بازیابی کنید پیدا نمی شود. مقدار پارامتر liveChatId درخواست را بررسی کنید تا مطمئن شوید که درست است.
rateLimitExceeded rateLimitExceeded درخواست خیلی سریع بعد از درخواست قبلی ارسال شد. این خطا زمانی رخ می‌دهد که درخواست‌های API برای بازیابی پیام‌ها بیشتر از نرخ‌های تازه‌سازی YouTube ارسال می‌شوند، که به‌طور غیر ضروری پهنای باند را هدر می‌دهد.

آن را امتحان کنید!

از APIs Explorer برای فراخوانی این API و مشاهده درخواست و پاسخ API استفاده کنید.