LiveChatMessages: streamList

Mit dieser Methode wird eine Server-Streaming-Verbindung hergestellt, über die du Livechat-Nachrichten für einen bestimmten Chat mit geringer Latenz empfangen kannst. Das ist die effizienteste Methode, um Live-Chat-Nachrichten zu empfangen, da neue Nachrichten an Ihren Client gesendet werden, sobald sie verfügbar sind. Sie müssen also nicht regelmäßig nach Updates suchen.

Wenn Sie sich zum ersten Mal verbinden, 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.

Nachrichten in jeder Serverantwort sind von der ältesten zur neuesten sortiert. Jede Antwort enthält auch ein nextPageToken. Wenn die Verbindung Ihres Clients getrennt wird, können Sie den Stream mit diesem Token fortsetzen. Geben Sie dazu die letzte nextPageToken, die Sie erhalten haben, als Wert für den Parameter pageToken in Ihrer neuen Verbindungsanfrage an. Die API setzt dann das Senden von Nachrichten an der Stelle fort, an der Sie aufgehört haben.

Demo

Eine Python-Demo dieses Endpunkts finden Sie im Leitfaden Streaming Live Chat.

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 Parameter liveChatId gibt die ID des Chats an, dessen Nachrichten zurückgegeben werden. Die mit einer Übertragung verknüpfte Livechat-ID wird in der snippet.liveChatId-Eigenschaft der liveBroadcast-Ressource zurückgegeben.
part string
Mit dem Parameter part werden die liveChatMessage-Ressourcenteile angegeben, 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ährungsanzeigestring für eine bestimmte Anwendungssprache abzurufen, die von der YouTube-Website unterstützt wird. Auf Deutsch 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 Parameter maxResults gibt die maximale Anzahl von Nachrichten an, die im Ergebnissatz zurückgegeben werden sollen. Zulässige Werte sind 200 bis einschließlich 2000. Der Standardwert ist 500.
pageToken string
Der Parameter pageToken gibt eine bestimmte Seite im Ergebnissatz an, die zurückgegeben werden soll. In einer API-Antwort gibt die Eigenschaft nextPageToken andere Seiten an, die abgerufen werden könnten.
profileImageSize unsigned integer
Der Parameter profileImageSize gibt die Größe der Profilbilder der Nutzer an, die im Ergebnissatz zurückgegeben werden sollen. Die Bilder sind quadratisch. Der Standardwert ist 88, d. h. Bilder sind 88 × 88 Pixel groß. Zulässige Werte liegen im Bereich von 16 bis einschließlich 720.

Anfragetext

Geben Sie 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 werden 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 in der Ergebnismenge abzurufen.
offlineAt datetime
Datum und Uhrzeit, zu der der zugrunde liegende Livestream offline gegangen ist. Diese Property 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 pageInfo-Objekt enthält Paging-Informationen für das Ergebnis-Set.
pageInfo.totalResults integer
Die Gesamtzahl der Ergebnisse im Ergebnissatz.
pageInfo.resultsPerPage integer
Die Anzahl der in der API-Antwort enthaltenen Ergebnisse.
items[] list
Eine Liste von Nachrichten. Jedes Element in der Liste ist eine liveChatMessage-Ressource.
activePollItem object
Die Umfragedaten in der Nachricht. Jede Umfrage ist eine liveChatMessage-Ressource vom Typ pollEvent, die eine aktive Umfrage darstellt. Pro Chat kann es nur eine Umfrage geben.

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 finden Sie in der Dokumentation zur Fehlermeldung.

Wenn Sie gRPC für die Verbindung verwenden:

gRPC-Fehlercode Fehlerdetails Beschreibung
PERMISSION_DENIED (7) The caller does not have permission Sie haben nicht die erforderlichen Berechtigungen, um Nachrichten für den angegebenen Livechat abzurufen.
INVALID_ARGUMENT (3) Request contains an invalid argument Die angegebenen Parameter konnten nicht geparst werden. Achte darauf, dass die liveChatId und andere Parameter das richtige Format haben.
FAILED_PRECONDITION (9)* Precondition check failed LIVE_CHAT_DISABLED. Der angegebene Livechat ist deaktiviert.
FAILED_PRECONDITION (9)* Precondition check failed LIVE_CHAT_ENDED. Nachrichten aus dem beendeten Livechat können nicht abgerufen werden.
NOT_FOUND (5) Requested entity was not found Der Livechat, den Sie abrufen möchten, wurde nicht gefunden. Prüfen Sie 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 verschwendet.

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

Wenn Sie Web-Traffic für die Verbindung verwenden:

Fehlertyp Fehlerdetails Beschreibung
HttpStatus.FORBIDDEN (403) forbidden Sie haben nicht die erforderlichen Berechtigungen, um Nachrichten für den angegebenen Livechat abzurufen.
HttpStatus.BAD_REQUEST (400) Reason for invalid request, e.g. pageTokenInvalid Die angegebenen Parameter konnten nicht geparst werden. Achte darauf, dass die liveChatId und andere Parameter das richtige Format haben.
HttpStatus.FORBIDDEN (403) liveChatDisabled LIVE_CHAT_DISABLED. Der angegebene Livechat ist deaktiviert.
HttpStatus.FORBIDDEN (403) liveChatEnded LIVE_CHAT_ENDED. Nachrichten aus dem beendeten Livechat können nicht abgerufen werden.
HttpStatus.NOT_FOUND (404) liveChatNotFound Der Livechat, den Sie abrufen möchten, wurde nicht gefunden. Prüfen Sie 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 verschwendet.