LiveChatMessages: streamList

השיטה הזו יוצרת חיבור להזרמת נתונים מהשרת, שמאפשר לקבל הודעות בצ'אט בשידור חי בצ'אט ספציפי עם השהיה נמוכה. זו הדרך היעילה ביותר לצרוך הודעות בצ'אט בשידור חי, כי ההודעות החדשות נשלחות ללקוח ברגע שהן זמינות, ולא צריך לבצע סקר כדי לקבל עדכונים.

בחיבור הראשון, ה-API שולח סדרה של הודעות שמכילות את היסטוריית הצ'אט האחרונה. כשהודעות חדשות מתפרסמות, השרת ימשיך לשלוח אותן דרך החיבור הפתוח.

ההודעות בכל תגובה של השרת מסודרות מהישנה ביותר לחדשה ביותר. כל תשובה כוללת גם nextPageToken. אם הלקוח מתנתק, אפשר להשתמש באסימון הזה כדי להמשיך את השידור. כדי לעשות זאת, צריך לציין את הערך של nextPageToken האחרון שקיבלתם כערך של הפרמטר pageToken בבקשת החיבור החדשה. ה-API ימשיך לשלוח הודעות מהנקודה שבה הפסקתם.

הדגמה (דמו)

הדגמה של נקודת הקצה הזו ב-Python מופיעה במדריך שידור חי של הצ'אט.

בקשה

פרמטרים

בטבלה הבאה מפורטים הפרמטרים שהשאילתה הזו תומכת בהם. כל הפרמטרים שמופיעים ברשימה הם פרמטרים של שאילתות.

פרמטרים
פרמטרים נדרשים
liveChatId string
הפרמטר liveChatId מציין את המזהה של הצ'אט שההודעות שלו יוחזרו. מזהה הצ'אט בשידור חי שמשויך לשידור מוחזר במאפיין snippet.liveChatId של משאב liveBroadcast.
part ‫string
הפרמטר part מציין את חלקי המשאב liveChatMessage שייכללו בתגובת ה-API. הערכים הנתמכים הם id,‏ snippet ו-authorDetails.
פרמטרים אופציונליים
hl string
הפרמטר hl מורה ל-API לאחזר מחרוזת של מטבע מקומי לתצוגה בשפה ספציפית של האפליקציה שאתר YouTube תומך בה. לדוגמה, באנגלית, המטבע יוצג כ-$1.50, אבל בצרפתית הוא יוצג כ-1,50$.

ערך הפרמטר חייב להיות קוד שפה שמופיע ברשימה שמוחזרת על ידי השיטה i18nLanguages.list.
maxResults unsigned integer

הפרמטר maxResults מציין את המספר המקסימלי של הודעות שיוחזרו בקבוצת התוצאות. הערכים הקבילים הם 200 עד 2000, כולל. ערך ברירת המחדל הוא 500.

הבקשה הראשונית שמוגשת ללא טוקן המשך תכיל רק את האירועים האחרונים. יכול להיות שהערך יהיה קטן מ-maxResults, אם הוא יסופק.

ה-API לא מאחזר אירועים שקודמים לאירועים שמוחזרים על ידי הבקשה הראשונית שבוצעה ללא טוקן המשך.
pageToken string
הפרמטר pageToken מזהה דף ספציפי בערכת התוצאות שצריך להחזיר. בתשובה של API, המאפיין nextPageToken מזהה דפים אחרים שאפשר לאחזר.
profileImageSize unsigned integer
הפרמטר profileImageSize מציין את הגודל של תמונות הפרופיל של המשתמשים שיוחזרו בקבוצת התוצאות. התמונות ריבועיות. ערך ברירת המחדל הוא 88, כלומר התמונות יהיו בגודל 88x88 פיקסלים. הערכים הקבילים הם בטווח 16 עד 720, כולל.

גוף הבקשה

כשקוראים לשיטה הזו, לא צריך לספק גוף בקשה.

תשובה

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

{
  "kind": "youtube#liveChatMessageListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pollingIntervalMillis": unsigne{d integer,
  "offlineAt": datetime,
  "pageInfo}": 
    "totalResults": integer,
    "resultsPerPage": integer
  ,
  }"items": [
    liveChatMessage Resource
  ],
  "activePollItem": liveChatMessage Resource

מאפיינים

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

מאפיינים
kind ‫string
מזהה את סוג משאב ה-API. הערך יהיה youtube#liveChatMessageListResponse.
etag etag
ה-Etag של מקור המידע הזה.
nextPageToken ‫string
הטוקן שאפשר להשתמש בו כערך של הפרמטר pageToken כדי לאחזר את הדף הבא בקבוצת התוצאות.
offlineAt datetime
התאריך והשעה שבהם השידור החי הבסיסי עבר למצב אופליין. המאפיין הזה מופיע רק אם הסטרימינג כבר במצב אופליין. הערך מצוין בפורמט ISO 8601‏ (YYYY-MM-DDThh:mm:ss.sZ).
pageInfo ‫object
האובייקט pageInfo כולל מידע על חלוקת התוצאות לדפים.
pageInfo.totalResults integer
המספר הכולל של התוצאות בקבוצת התוצאות.
pageInfo.resultsPerPage integer
מספר התוצאות שנכללות בתגובת ה-API.
items[] list
רשימת הודעות. כל פריט ברשימה הוא משאב liveChatMessage.
activePollItem object
נתוני הסקר בהודעה. כל סקר הוא משאב liveChatMessage עם הסוג pollEvent, שמייצג סקר פעיל. בכל צ'אט יכול להיות רק סקר אחד.

שגיאות

בטבלה הבאה מפורטות הודעות השגיאה שה-API יכול להחזיר בתגובה לקריאה של השיטה הזו. פרטים נוספים זמינים במאמר בנושא הודעת השגיאה.

כשמשתמשים ב-gRPC כדי להתחבר:

קוד שגיאה של gRPC פרטי השגיאה תיאור
PERMISSION_DENIED (7) The caller does not have permission אין לך את ההרשאות שנדרשות כדי לאחזר הודעות בצ'אט בשידור חי שצוין.
INVALID_ARGUMENT (3) Request contains an invalid argument ניתוח הפרמטרים שסופקו נכשל. מוודאים שהפרמטר liveChatId ופרמטרים אחרים הם בפורמט הנכון.
FAILED_PRECONDITION (9)* Precondition check failed LIVE_CHAT_DISABLED. הצ'אט בשידור חי שצוין מושבת.
FAILED_PRECONDITION (9)* Precondition check failed LIVE_CHAT_ENDED. אי אפשר לאחזר הודעות מצ'אט בשידור חי שהסתיים.
NOT_FOUND (5) Requested entity was not found לא נמצא צ'אט בשידור חי שניסית לאחזר. צריך לבדוק את הערך של הפרמטר liveChatId בבקשה ולוודא שהוא נכון.
RESOURCE_EXHAUSTED (8) Resource has been exhausted (e.g. check quota) הבקשה נשלחה מהר מדי אחרי הבקשה הקודמת. השגיאה הזו מתרחשת כשבקשות API לאחזור הודעות נשלחות בתדירות גבוהה יותר מקצב הרענון של YouTube, מה שגורם לבזבוז מיותר של רוחב פס.

* בגלל מגבלה ב-gRPC, אי אפשר להבחין בין מקרה LIVE_CHAT_DISABLED למקרה LIVE_CHAT_ENDED על סמך קוד השגיאה. צוות YouTube עובד על פתרון לבעיה הזו.

כשמשתמשים בתעבורת אינטרנט כדי להתחבר:

סוג שגיאה פרטי השגיאה תיאור
HttpStatus.FORBIDDEN (403) forbidden אין לך את ההרשאות שנדרשות כדי לאחזר הודעות בצ'אט בשידור חי שצוין.
HttpStatus.BAD_REQUEST (400) Reason for invalid request, e.g. pageTokenInvalid ניתוח הפרמטרים שסופקו נכשל. מוודאים שהפרמטר liveChatId ופרמטרים אחרים הם בפורמט הנכון.
HttpStatus.FORBIDDEN (403) liveChatDisabled LIVE_CHAT_DISABLED. הצ'אט בשידור חי שצוין מושבת.
HttpStatus.FORBIDDEN (403) liveChatEnded LIVE_CHAT_ENDED. אי אפשר לאחזר הודעות מצ'אט בשידור חי שהסתיים.
HttpStatus.NOT_FOUND (404) liveChatNotFound לא נמצא צ'אט בשידור חי שניסית לאחזר. צריך לבדוק את הערך של הפרמטר liveChatId בבקשה ולוודא שהוא נכון.
HttpStatus.FORBIDDEN (403) rateLimitExceeded הבקשה נשלחה מהר מדי אחרי הבקשה הקודמת. השגיאה הזו מתרחשת כשבקשות API לאחזור הודעות נשלחות בתדירות גבוהה יותר מקצב הרענון של YouTube, מה שגורם לבזבוז מיותר של רוחב פס.