Subscriptions: list

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

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

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

درخواست

درخواست HTTP

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

مولفه های

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

مولفه های
پارامترهای مورد نیاز
part	string پارامتر part یک لیست جدا شده با کاما از یک یا چند ویژگی منبع subscription را مشخص می کند که پاسخ API شامل می شود. اگر پارامتر خاصیتی را مشخص کند که حاوی ویژگی های فرزند است، ویژگی های فرزند در پاسخ گنجانده می شود. به عنوان مثال، در یک منبع subscription ، ویژگی snippet حاوی ویژگی های دیگری است، مانند عنوان نمایش برای اشتراک. اگر part=snippet را تنظیم کنید، پاسخ API نیز شامل تمام آن ویژگی‌های تودرتو خواهد بود. لیست زیر شامل نام part است که می توانید در مقدار پارامتر بگنجانید: contentDetails id snippet subscriberSnippet
فیلترها (دقیقا یکی از پارامترهای زیر را مشخص کنید)
channelId	string پارامتر channelId شناسه کانال YouTube را مشخص می کند. API فقط اشتراک های آن کانال را برمی گرداند.
id	string پارامتر id فهرستی از شناسه(های) اشتراک YouTube را برای منابعی که در حال بازیابی هستند، با کاما از هم جدا می کند. در یک منبع subscription ، ویژگی id شناسه اشتراک YouTube را مشخص می کند.
mine	boolean این پارامتر فقط در یک درخواست مجاز به درستی قابل استفاده است. مقدار این پارامتر را روی true تنظیم کنید تا فید اشتراک های کاربر احراز هویت شده را بازیابی کنید.
myRecentSubscribers	boolean این پارامتر فقط در یک درخواست مجاز به درستی قابل استفاده است. برای بازیابی فید مشترکین کاربر احراز هویت شده به ترتیب زمانی معکوس (ابتدا جدیدترین) مقدار این پارامتر را روی true تنظیم کنید. توجه داشته باشید که حداکثر تعداد مشترکین بازگشتی از طریق این API ممکن است محدود باشد.
mySubscribers	boolean این پارامتر فقط در یک درخواست مجاز به درستی قابل استفاده است. برای بازیابی فید مشترکین کاربر احراز هویت شده بدون ترتیب خاصی، مقدار این پارامتر را روی true تنظیم کنید. توجه داشته باشید که حداکثر تعداد مشترکین بازگشتی از طریق این API ممکن است محدود باشد.
پارامترهای اختیاری
forChannelId	string پارامتر forChannelId فهرستی از شناسه های کانال را مشخص می کند که با کاما از هم جدا شده اند. سپس پاسخ API فقط شامل اشتراک هایی خواهد بود که با آن کانال ها مطابقت دارند.
maxResults	unsigned integer پارامتر maxResults حداکثر تعداد مواردی را که باید در مجموعه نتایج برگردانده شوند را مشخص می کند. مقادیر قابل قبول شامل 0 تا 50 است. مقدار پیش فرض 5 است.
onBehalfOfContentOwner	string توجه: این پارامتر منحصراً برای شرکای محتوای YouTube در نظر گرفته شده است. پارامتر onBehalfOfContentOwner نشان می دهد که اعتبارنامه مجوز درخواست، کاربر YouTube CMS را شناسایی می کند که از طرف مالک محتوا مشخص شده در مقدار پارامتر عمل می کند. این پارامتر برای شرکای محتوای YouTube در نظر گرفته شده است که کانال‌های مختلف YouTube را مالک و مدیریت می‌کنند. این به صاحبان محتوا امکان می‌دهد یک بار احراز هویت کنند و به تمام داده‌های ویدیویی و کانال خود دسترسی داشته باشند، بدون اینکه نیازی به ارائه اعتبارنامه احراز هویت برای هر کانال جداگانه داشته باشند. حساب CMS که کاربر با آن احراز هویت می‌کند باید به مالک محتوای YouTube مشخص شده مرتبط باشد.
onBehalfOfContentOwnerChannel	string این پارامتر فقط در یک درخواست مجاز به درستی قابل استفاده است. توجه: این پارامتر منحصراً برای شرکای محتوای YouTube در نظر گرفته شده است. پارامتر onBehalfOfContentOwnerChannel شناسه کانال YouTube کانالی را که ویدیویی به آن اضافه می شود مشخص می کند. این پارامتر زمانی مورد نیاز است که یک درخواست مقداری را برای پارامتر onBehalfOfContentOwner مشخص می کند و فقط می تواند در ارتباط با آن پارامتر استفاده شود. علاوه بر این، درخواست باید با استفاده از یک حساب CMS که به مالک محتوایی که پارامتر onBehalfOfContentOwner مشخص می‌کند مرتبط است، مجاز باشد. در نهایت، کانالی که مقدار پارامتر onBehalfOfContentOwnerChannel مشخص می کند باید به مالک محتوایی که پارامتر onBehalfOfContentOwner مشخص می کند پیوند داده شود. این پارامتر برای شرکای محتوای YouTube در نظر گرفته شده است که کانال‌های مختلف YouTube را مالک و مدیریت می‌کنند. این به صاحبان محتوا اجازه می‌دهد تا یک بار احراز هویت کنند و اقداماتی را از طرف کانال مشخص‌شده در مقدار پارامتر انجام دهند، بدون اینکه نیازی به ارائه اعتبارنامه احراز هویت برای هر کانال جداگانه باشد.
order	string پارامتر order روشی را مشخص می کند که برای مرتب سازی منابع در پاسخ API استفاده می شود. مقدار پیش‌فرض SUBSCRIPTION_ORDER_RELEVANCE است. مقادیر قابل قبول عبارتند از: alphabetical - مرتب سازی بر اساس حروف الفبا. relevance - مرتب سازی بر اساس ارتباط. unread - مرتب سازی بر اساس ترتیب فعالیت.
pageToken	string پارامتر pageToken صفحه خاصی را در مجموعه نتایج مشخص می کند که باید برگردانده شود. در یک پاسخ API، ویژگی های nextPageToken و prevPageToken صفحات دیگری را شناسایی می کنند که می توانند بازیابی شوند.

درخواست بدن

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

واکنش

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

{
  "kind": "youtube#subscriptionListResponse",
  "etag": etag,
  "nextPageToken": string,
  "prevPageToken": string,
  "pageInfo": {
    "totalResults": integer,
    "resultsPerPage": integer
  },
  "items": [
    subscription Resource
  ]
}

خواص

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

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

خطاها

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

نوع خطا	جزئیات خطا	شرح
forbidden (403)	accountClosed	اشتراک‌ها بازیابی نشدند زیرا حساب مشترک بسته است.
forbidden (403)	accountSuspended	اشتراک ها قابل بازیابی نیستند زیرا حساب مشترک به حالت تعلیق درآمده است.
forbidden (403)	subscriptionForbidden	درخواست کننده اجازه دسترسی به اشتراک های درخواستی را ندارد.
notFound (404)	subscriberNotFound	مشترکی که با درخواست شناسایی شده است یافت نمی شود.

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

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