LiveChatMessages: list

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

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

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

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

בקשה

בקשת 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.

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

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

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

רוצה לנסות?

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