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

גוף הבקשה

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

תשובה

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

{
  "kind": "youtube#liveChatMessageListResponse",
  "etag": etag,
  "nextPageToken": string,
  "pollingIntervalMillis": unsigned 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, מה שגורם לבזבוז מיותר של רוחב פס.