Subscriptions: list

הפונקציה מחזירה משאבי מינוי שתואמים לקריטריונים של בקשת ה-API.

השפעה על המכסה: קריאה ל-method הזה מנצלת יחידה אחת מהמכסה.

תרחישים נפוצים לדוגמה

בקשה

בקשת 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 שונים. היא מאפשרת לבעלי תוכן לבצע אימות פעם אחת ולקבל גישה לכל נתוני הסרטונים והערוצים שלהם, בלי לספק פרטי כניסה לאימות לכל ערוץ בנפרד. החשבון במערכת ניהול התוכן שהמשתמש מאמת צריך להיות מקושר לבעל התוכן ב-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 מזהים דפים אחרים שאפשר לאחזר.

גוף הבקשה

כשמפעילים את ה-method הזו, לא צריך לספק גוף בקשה.

תשובה

אם הפעולה בוצעה ללא שגיאות, ה-method מחזירה גוף תגובה במבנה הבא:

{
  "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 יכול להחזיר בתגובה לקריאה ל-method הזה. פרטים נוספים מופיעים במסמכי התיעוד בנושא הודעות שגיאה.

סוג השגיאה פרטי השגיאה תיאור
forbidden (403) accountClosed לא ניתן לאחזר את המינויים כי החשבון של המנוי סגור.
forbidden (403) accountSuspended לא ניתן לאחזר את המינויים כי החשבון של המנוי מושעה.
forbidden (403) subscriptionForbidden לשולח הבקשה אין הרשאה לגשת למינויים המבוקשים.
notFound (404) subscriberNotFound לא נמצא מנוי שמזוהה עם הבקשה.

רוצה לנסות?

משתמשים ב-APIs Explorer כדי להפעיל את ה-API הזה ולראות את בקשת ה-API והתגובה.