LiveChatMessages: streamList

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

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

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

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

הדגמה (דמו)

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

גוף הבקשה

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

תשובה

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

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

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

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

סוג שגיאה פרטי השגיאה תיאור
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, מה שגורם לבזבוז מיותר של רוחב פס.