LiveChatMessages: list

מציג את ההודעות בצ'אט בשידור חי של צ'אט ספציפי.

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

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

בקשה

בקשת HTTP

GET https://www.googleapis.com/youtube/v3/liveChat/messages

פרמטרים

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

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

סוג השגיאה פרטי השגיאה תיאור
forbidden (403) forbidden אין לך את ההרשאות הנדרשות כדי לאחזר הודעות בצ'אט החי שצוין.
forbidden (403) liveChatDisabled הצ'אט בשידור חי לא מופעל בשידור שצוין.
forbidden (403) liveChatEnded הצ'אט בשידור חי שצוין כבר לא פעיל.
notFound (404) liveChatNotFound לא ניתן לאחזר את הצ'אט בשידור חי שניסית לאחזר. צריך לבדוק את הערך של הפרמטר liveChatId בבקשה ולוודא שהוא נכון.
rateLimitExceeded rateLimitExceeded הבקשה נשלחה מהר מדי אחרי הבקשה הקודמת. השגיאה הזו מתרחשת כשבקשות API לאחזור הודעות נשלחות בתדירות גבוהה יותר מקצב הרענון של YouTube, מה שגורם לבזבוז מיותר של רוחב פס.

נסה בעצמך!

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