Subscriptions: list

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

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

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

درخواست

درخواست 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 روشی را مشخص می‌کند که برای مرتب‌سازی منابع در پاسخ میانای برنامه‌سازی کاربردی استفاده خواهد شد. مقدار پیش‌فرض SUBSCRIPTION_ORDER_RELEVANCE است.

مقادیر پذیرفتنی عبارت‌اند از:
  • alphabetical – مرتب کردن براساس حروف الفبا.
  • relevance – مرتب‌سازی براساس مربوط بودن.
  • unread – مرتب‌سازی براساس ترتیب فعالیت.
pageToken string
پارامتر pageToken صفحه خاصی را در مجموعه نتایج شناسایی می‌کند که باید برگردانده شود. در پاسخ میانای برنامه‌سازی کاربردی، ویژگی‌های nextPageToken و prevPageToken صفحه‌های دیگری را که می‌توان بازیابی کرد شناسایی می‌کنند.

متن درخواست

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

پاسخ

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

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

مشخصات

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

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

خطاها

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

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

امتحان کنید!

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