Subscriptions: list

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

ההשפעה על המכסה: לשיחה בשיטה הזו מוגדרת עלות מכסה של יחידה אחת.

תרחישים נפוצים

שליחת בקשה

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

גוף הבקשה

אין להזין גוף בקשה בעת הפעלת שיטה זו.

תשובה

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

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

נכסים

הטבלה הבאה מגדירה את המאפיינים שמופיעים במשאב הזה:

נכסים
kind string
מזהה את סוג המשאב של ה-API. הערך יהיה youtube#subscriptionListResponse.
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 ואת התשובה.