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.