LiveChatMessages: list

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

وقتی اولین درخواستتان را برای بازیابی پیام‌های گپ ارسال می‌کنید، بسته به طول سابقه گپ، API بخشی از سابقه گپ یا کل آن را برمی‌گرداند. پیام‌ها در پاسخ از قدیمی‌ترین به جدیدترین مرتب شده‌اند.
  • ‫nextPageToken در پاسخ، کدی ارائه می‌دهد که در درخواست بعدی شما، مجموعه بعدی نتایجی را که کارخواه میانای برنامه‌سازی کاربردی شما باید بازیابی کند شناسایی می‌کند.
  • ویژگی pollingIntervalMillis نشان می‌دهد که کارخواه میانای برنامه‌سازی کاربردی شما چقدر باید قبل‌از درخواست نتایج بیشتر صبر کند.
وقتی نتایج بیشتری درخواست می‌کنید، پارامتر 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 است.

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

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

امتحان کنید!

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