LiveChatMessages: streamList

Mit dieser Methode wird eine Server-Streaming-Verbindung hergestellt, über die du Live-Chatnachrichten für einen bestimmten Chat mit geringer Latenz empfangen kannst. Das ist die effizienteste Methode, um Live-Chatnachrichten aufzunehmen, da neue Nachrichten an deinen Client gesendet werden, sobald sie verfügbar sind. Du musst also nicht nach Updates suchen.

Wenn du dich zum ersten Mal verbindest, sendet die API eine Reihe von Nachrichten mit dem aktuellen Chatverlauf. Wenn neue Nachrichten gepostet werden, sendet der Server sie weiterhin über die offene Verbindung.

Die Nachrichten in jeder Serverantwort sind vom ältesten zum neuesten sortiert. Jede Antwort enthält auch ein nextPageToken. Wenn die Verbindung zu deinem Client getrennt wird, kannst du dieses Token verwenden, um den Stream fortzusetzen. Gib dazu das letzte nextPageToken, das du erhalten hast, als Wert für den Parameter pageToken in deiner neuen Verbindungsanfrage an. Die API sendet dann Nachrichten ab dem Punkt, an dem du aufgehört hast.

Auswirkungen auf das Kontingent: Ein Aufruf dieser Methode hat einen Kontingentaufwand von 5 Einheiten.

Demo

Eine Python-Demo dieses Endpunkts findest du im Leitfaden zum Streaming von Live-Chats.

Anfrage

Parameter

In der folgenden Tabelle sind die Parameter aufgeführt, die von dieser Abfrage unterstützt werden. Alle aufgeführten Parameter sind Abfrageparameter.

Parameter
Erforderliche Parameter
liveChatId	string Der liveChatId Parameter gibt die ID des Chats an, dessen Nachrichten zurückgegeben werden. Die Live-Chat-ID, die mit einer Übertragung verknüpft ist, wird in der Eigenschaft snippet.liveChatId der Ressource liveBroadcast zurückgegeben.
part	string Der Parameter part gibt die Teile der Ressource liveChatMessage an, die in der API-Antwort enthalten sein sollen. Unterstützte Werte sind id, snippet und authorDetails.
Optionale Parameter
hl	string Mit dem Parameter hl wird die API angewiesen, einen lokalisierten Währungsanzeige-String für eine bestimmte Anwendungssprache abzurufen, die von der YouTube-Website unterstützt wird. Auf Englisch wird die Währung beispielsweise als $1.50 angezeigt, auf Französisch als 1,50$. Der Parameterwert muss ein Sprachcode sein, der in der Liste enthalten ist, die von der Methode i18nLanguages.list zurückgegeben wird.
maxResults	unsigned integer Der maxResults Parameter gibt die maximale Anzahl der Nachrichten an, die im Ergebnissatz zurückgegeben werden sollen. Zulässige Werte sind 200 bis 2000 (einschließlich). Der Standardwert ist 500. Die erste Anfrage ohne Fortsetzungstoken enthält nur die letzten Ereignisse. Dieser Wert kann kleiner als maxResults sein, falls angegeben. Die API ruft keine Ereignisse ab, die älter sind als die, die von der ersten Anfrage ohne Fortsetzungstoken zurückgegeben wurden.
pageToken	string Der pageToken Parameter gibt eine bestimmte Seite im Ergebnissatz an, die zurückgegeben werden soll. In einer API-Antwort werden mit der Eigenschaft nextPageToken andere Seiten angegeben, die abgerufen werden können.
profileImageSize	unsigned integer Der Parameter profileImageSize gibt die Größe der Nutzerprofilbilder an, die im Ergebnissatz zurückgegeben werden sollen. Die Bilder sind quadratisch. Der Standardwert ist 88. Die Bilder sind also 88 × 88 Pixel groß. Zulässige Werte liegen im Bereich von 16 bis 720 (einschließlich).

Anfragetext

Gib beim Aufrufen dieser Methode keinen Anfragetext an.

Antwort

Bei Erfolg gibt diese Methode einen Antworttext mit der folgenden Struktur zurück:

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

Attribute

In der folgenden Tabelle sind die Attribute definiert, die in dieser Ressource enthalten sind:

Attribute
kind	string Gibt den Typ der API-Ressource an. Der Wert ist youtube#liveChatMessageListResponse.
etag	etag Das ETag dieser Ressource.
nextPageToken	string Das Token, das als Wert des Parameters pageToken verwendet werden kann, um die nächste Seite im Ergebnissatz abzurufen.
offlineAt	datetime Datum und Uhrzeit, zu der der zugrunde liegende Livestream offline gegangen ist. Diese Eigenschaft ist nur vorhanden, wenn der Stream bereits offline ist. Der Wert wird im ISO 8601-Format (YYYY-MM-DDThh:mm:ss.sZ) angegeben.
pageInfo	object Das Objekt pageInfo enthält Paging-Informationen für den Ergebnissatz.
pageInfo.totalResults	integer Die Gesamtzahl der Ergebnisse im Ergebnissatz.
pageInfo.resultsPerPage	integer Die Anzahl der Ergebnisse in der API-Antwort.
items[]	list Eine Liste von Nachrichten. Jedes Element in der Liste ist eine Ressource vom Typ liveChatMessage.
activePollItem	object Die Umfragedaten in der Nachricht. Jede Umfrage ist eine Ressource vom Typ liveChatMessage mit dem Typ pollEvent, die eine aktive Umfrage darstellt. Pro Chat kann nur eine Umfrage vorhanden sein.

Fehler

In der folgenden Tabelle sind die Fehlermeldungen aufgeführt, die die API als Antwort auf einen Aufruf dieser Methode zurückgeben kann. Weitere Informationen findest du in der Dokumentation zu Fehlermeldungen.

Bei Verwendung von gRPC für die Verbindung:

gRPC-Fehlercode	Fehlerdetails	Beschreibung
PERMISSION_DENIED (7)	The caller does not have permission	Du hast nicht die erforderlichen Berechtigungen, um Nachrichten für den angegebenen Live-Chat abzurufen.
INVALID_ARGUMENT (3)	Request contains an invalid argument	Die angegebenen Parameter konnten nicht geparst werden. Achte darauf, dass die Parameter `liveChatId` und andere Parameter das richtige Format haben.
FAILED_PRECONDITION (9)^*	Precondition check failed	LIVE_CHAT_DISABLED. Der angegebene Live-Chat ist deaktiviert.
FAILED_PRECONDITION (9)^*	Precondition check failed	LIVE_CHAT_ENDED. Du kannst keine Nachrichten für den beendeten Live-Chat abrufen.
NOT_FOUND (5)	Requested entity was not found	Der Live-Chat, den du abrufen möchtest, wurde nicht gefunden. Prüfe den Wert des Parameters liveChatId der Anfrage, um sicherzustellen, dass er korrekt ist.
RESOURCE_EXHAUSTED (8)	Resource has been exhausted (e.g. check quota)	Die Anfrage wurde zu schnell nach der vorherigen Anfrage gesendet. Dieser Fehler tritt auf, wenn API-Anfragen zum Abrufen von Nachrichten häufiger gesendet werden als die Aktualisierungsraten von YouTube. Dadurch wird unnötig Bandbreite verbraucht.

* Aufgrund einer gRPC-Einschränkung ist es nicht möglich, anhand des Fehlercodes zwischen einem Fall von LIVE_CHAT_DISABLED und einem Fall von LIVE_CHAT_ENDED zu unterscheiden. YouTube arbeitet aktiv an einer Lösung für dieses Problem.

Bei Verwendung von Web-Traffic für die Verbindung:

Fehlertyp	Fehlerdetails	Beschreibung
HttpStatus.FORBIDDEN (403)	forbidden	Du hast nicht die erforderlichen Berechtigungen, um Nachrichten für den angegebenen Live-Chat abzurufen.
HttpStatus.BAD_REQUEST (400)	Reason for invalid request, e.g. pageTokenInvalid	Die angegebenen Parameter konnten nicht geparst werden. Achte darauf, dass die Parameter `liveChatId` und andere Parameter das richtige Format haben.
HttpStatus.FORBIDDEN (403)	liveChatDisabled	LIVE_CHAT_DISABLED. Der angegebene Live-Chat ist deaktiviert.
HttpStatus.FORBIDDEN (403)	liveChatEnded	LIVE_CHAT_ENDED. Du kannst keine Nachrichten für den beendeten Live-Chat abrufen.
HttpStatus.NOT_FOUND (404)	liveChatNotFound	Der Live-Chat, den du abrufen möchtest, wurde nicht gefunden. Prüfe den Wert des Parameters liveChatId der Anfrage, um sicherzustellen, dass er korrekt ist.
HttpStatus.FORBIDDEN (403)	rateLimitExceeded	Die Anfrage wurde zu schnell nach der vorherigen Anfrage gesendet. Dieser Fehler tritt auf, wenn API-Anfragen zum Abrufen von Nachrichten häufiger gesendet werden als die Aktualisierungsraten von YouTube. Dadurch wird unnötig Bandbreite verbraucht.