CommentThreads: list

فهرستی از رشته‌های نظر را که با پارامترهای درخواست API مطابقت دارند برمی‌گرداند.

تأثیر سهمیه: تماس با این روش هزینه سهمیه ۱ واحدی دارد.

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

درخواست

درخواست HTTP

GET https://www.googleapis.com/youtube/v3/commentThreads

پارامترها

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

پارامترها
پارامترهای الزامی
part string
پارامتر part فهرست جداشده با کاما از یک یا چند ویژگی منبع commentThread را که پاسخ میانای برنامه‌سازی کاربردی شامل خواهد شد مشخص می‌کند.

فهرست زیر حاوی نام‌های part است که می‌توانید در مقدار پارامتر اضافه کنید:
  • id
  • replies
  • snippet
فیلترها (دقیقاً یکی از پارامترهای زیر را مشخص کنید)
allThreadsRelatedToChannelId string
پارامتر allThreadsRelatedToChannelId به API دستور می‌دهد تا تمام رشته‌های نظرات مرتبط با کانال مشخص‌شده را برگرداند.
id string
پارامتر id فهرستی از شناسه‌های رشته نظر جداشده با کاما را برای منابعی که باید بازیابی شوند مشخص می‌کند.
videoId string
پارامتر videoId به API دستور می‌دهد تا رشته‌های نظرات مرتبط با شناسه ویدیو مشخص‌شده را برگرداند.
پارامترهای اختیاری
maxResults unsigned integer
پارامتر maxResults حداکثر تعداد مواردی را که باید در مجموعه نتایج برگردانده شود مشخص می‌کند.

توجه: این پارامتر برای استفاده همراه با پارامتر id پشتیبانی نمی‌شود. مقادیر پذیرفتنی از 1 تا 100 است. مقدار پیش‌فرض 20 است.
moderationStatus string
این پارامتر فقط در درخواست‌های مجاز قابل‌استفاده است. این پارامتر را برای محدود کردن رشته‌های نظر برگردانده‌شده به یک وضعیت نظارت خاص تنظیم کنید.

توجه: این پارامتر برای استفاده در ارتباط با پارامتر id پشتیبانی نمی‌شود. مقدار پیش‌فرض published است.

مقادیر پذیرفتنی عبارت‌اند از:
  • heldForReview – رشته‌های نظری را که درانتظار بررسی توسط یک تعدیل‌گر هستند، بازیابی کنید. اگر نظر سطح بالا یا حداقل یکی از پاسخ‌ها به آن نظر در انتظار بازبینی باشد، رشته نظر می‌تواند در پاسخ گنجانده شود.
  • likelySpam – بازیابی رشته نظراتی که به‌عنوان احتمالاً هرزنامه طبقه‌بندی شده‌اند. اگر نظر سطح بالا یا حداقل یکی از پاسخ‌های آن نظر احتمالاً هرزنامه درنظر گرفته شود، رشته نظر می‌تواند در پاسخ گنجانده شود.
  • published – رشته‌های نظرات منتشرشده را بازیابی کنید. این مقدار پیش‌فرض است. اگر نظر سطح بالای رشته نظر منتشر شده باشد، می‌توان آن را در پاسخ گنجاند.
order string
پارامتر order ترتیب فهرست شدن رشته‌های نظر در پاسخ میانای برنامه‌سازی کاربردی را مشخص می‌کند. مقادیر معتبر عبارت‌اند از:
  • time - رشته‌های نظرات براساس زمان مرتب شده‌اند. این رفتار پیش‌فرض است.
  • relevance - رشته‌های نظر براساس مربوط بودن مرتب شده‌اند.
توجه: این پارامتر برای استفاده همراه با پارامتر id پشتیبانی نمی‌شود.
pageToken string
پارامتر pageToken صفحه خاصی را در مجموعه نتایج شناسایی می‌کند که باید برگردانده شود. در پاسخ میانای برنامه‌سازی کاربردی، ویژگی nextPageToken صفحه بعدی نتیجه را که قابل‌بازیابی است شناسایی می‌کند.

توجه: این پارامتر برای استفاده همراه با پارامتر id پشتیبانی نمی‌شود.
searchTerms string
پارامتر searchTerms به API دستور می‌دهد که پاسخ API را محدود کند تا فقط شامل نظراتی باشد که حاوی عبارات جستجوی مشخص‌شده هستند.

توجه: این پارامتر برای استفاده همراه با پارامتر id پشتیبانی نمی‌شود.
textFormat string
مقدار این پارامتر را روی html یا plainText تنظیم کنید تا به API دستور دهید نظراتی را که کاربران گذاشته‌اند در قالب html یا نوشتار ساده برگرداند. مقدار پیش‌فرض html است.

مقادیر پذیرفتنی عبارت‌اند از:
  • html – نظرات را در قالب HTML برمی‌گرداند. این مقدار پیش‌فرض است.
  • plainText – نظرات را در قالب نوشتار ساده برمی‌گرداند.

متن درخواست

هنگام فراخوانی این روش، بدنه درخواست ارائه نکنید.

پاسخ

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

{
  "kind": "youtube#commentThreadListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    commentThread Resource
  ]
}

مشخصات

جدول زیر ویژگی‌هایی را که در این منبع ظاهر می‌شوند تعریف می‌کند:

مشخصات
kind string
نوع منبع «میانای برنامه‌سازی کاربردی» را مشخص می‌کند. مقدار youtube#commentThreadListResponse خواهد بود.
etag etag
Etag این منبع.
nextPageToken string
نشانه‌ای که می‌تواند به‌عنوان مقدار پارامتر pageToken برای بازیابی صفحه بعدی در مجموعه نتایج استفاده شود.
pageInfo object
شیء pageInfo اطلاعات صفحه‌بندی را برای مجموعه نتایج کپسوله‌سازی می‌کند.
pageInfo.totalResults integer
تعداد کل نتایج در مجموعه نتایج.
pageInfo.resultsPerPage integer
تعداد نتایج موجود در پاسخ میانای برنامه‌سازی کاربردی.
items[] list
فهرستی از رشته‌های نظر که با معیارهای درخواست مطابقت دارند.

خطاها

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

نوع خطا جزئیات خطا شرح
badRequest (400) operationNotSupported فیلتر id فقط با نظرات مبتنی بر Google+‎ سازگار است.
badRequest (400) processingFailure سرور میانای برنامه‌سازی کاربردی نتوانست درخواست را با موفقیت پردازش کند. اگرچه این خطا می‌تواند موقتی باشد، اما معمولاً نشان می‌دهد که ورودی درخواست نامعتبر است. ساختار منبع commentThread را در بدنه درخواست بررسی کنید تا مطمئن شوید معتبر است.
forbidden (403) commentsDisabled ویدیو شناسایی‌شده با پارامتر videoId نظرات را غیرفعال کرده است.
forbidden (403) forbidden یک یا چند رشته نظر درخواستی به‌دلیل ناکافی بودن اجازه‌ها قابل‌بازیابی نیست. ممکن است درخواست به‌درستی مجاز نشده باشد.
notFound (404) channelNotFound کانال شناسایی‌شده با پارامتر allThreadsRelatedToChannelId پیدا نشد.
notFound (404) commentThreadNotFound یک یا چند رشته نظر مشخص‌شده پیدا نشد. مقادیر پارامتر id درخواست را بررسی کنید تا مطمئن شوید درست است.
notFound (404) videoNotFound ویدیویی که با پارامتر videoId مشخص شده است پیدا نشد.

امتحان کنید!

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