LiveChatMessages: streamList

Questo metodo stabilisce una connessione di streaming del server che ti consente di ricevere messaggi della chat live per una chat specifica con una latenza ridotta. Questo è il modo più efficiente per utilizzare i messaggi della live chat, in quanto invia i nuovi messaggi al client non appena sono disponibili, anziché richiedere di eseguire il polling per gli aggiornamenti.

Quando ti connetti per la prima volta, l'API invia una serie di messaggi contenenti la cronologia chat recente. Man mano che vengono pubblicati nuovi messaggi, il server continuerà a inviarli tramite la connessione aperta.

I messaggi in ogni risposta del server sono ordinati dal meno recente al più recente. Ogni risposta include anche un nextPageToken. Se il client si disconnette, puoi utilizzare questo token per riprendere lo stream. A questo scopo, fornisci l'ultimo nextPageToken che hai ricevuto come valore del parametro pageToken nella nuova richiesta di connessione. L'API riprenderà quindi a inviare messaggi dal punto in cui avevi interrotto.

Demo

Per una demo in Python di questo endpoint, consulta la guida Streaming Live Chat.

Richiesta

Parametri

La tabella seguente elenca i parametri supportati da questa query. Tutti i parametri elencati sono parametri di query.

Parametri
Parametri obbligatori
liveChatId string
Il parametro liveChatId specifica l'ID della chat di cui verranno restituiti i messaggi. L'ID della chat live associato a una trasmissione viene restituito nella proprietà snippet.liveChatId della risorsa liveBroadcast.
part string
Il parametro part specifica le parti della risorsa liveChatMessage che verranno incluse nella risposta dell'API. I valori supportati sono id, snippet e authorDetails.
Parametri facoltativi
hl string
Il parametro hl indica all'API di recuperare una stringa di visualizzazione della valuta localizzata per una specifica lingua dell'applicazione supportata dal sito web di YouTube. Ad esempio, in inglese la valuta viene visualizzata come $1.50, mentre in francese come 1,50$.

Il valore del parametro deve essere un codice lingua incluso nell'elenco restituito dal metodo i18nLanguages.list.
maxResults unsigned integer
Il parametro maxResults specifica il numero massimo di messaggi che devono essere restituiti nel set di risultati. I valori accettabili sono compresi tra 200 e 2000 inclusi. Il valore predefinito è 500.
pageToken string
Il parametro pageToken identifica una pagina specifica nel set di risultati che deve essere restituita. In una risposta API, la proprietà nextPageToken identifica altre pagine che potrebbero essere recuperate.
profileImageSize unsigned integer
Il parametro profileImageSize specifica le dimensioni delle immagini del profilo utente che devono essere restituite nel set di risultati. Le immagini sono quadrate. Il valore predefinito è 88, il che significa che le immagini avranno dimensioni 88 x 88 px. I valori accettabili sono compresi tra 16 e 720 inclusi.

Corpo della richiesta

Non fornire un corpo della richiesta quando chiami questo metodo.

Risposta

In caso di esito positivo, questo metodo restituisce un corpo della risposta con la seguente struttura:

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

Proprietà

La tabella seguente definisce le proprietà visualizzate in questa risorsa:

Proprietà
kind string
Identifica il tipo di risorsa API. Il valore sarà youtube#liveChatMessageListResponse.
etag etag
L'ETag di questa risorsa.
nextPageToken string
Il token che può essere utilizzato come valore del parametro pageToken per recuperare la pagina successiva nel set di risultati.
offlineAt datetime
La data e l'ora in cui il live streaming sottostante è andato offline. Questa proprietà è presente solo se lo stream è già offline. Il valore è specificato nel formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
pageInfo object
L'oggetto pageInfo contiene le informazioni di paginazione per il set di risultati.
pageInfo.totalResults integer
Il numero totale di risultati nel set di risultati.
pageInfo.resultsPerPage integer
Il numero di risultati inclusi nella risposta dell'API.
items[] list
Un elenco di messaggi. Ogni elemento dell'elenco è una risorsa liveChatMessage.
activePollItem object
I dati del sondaggio nel messaggio. Ogni sondaggio è una risorsa liveChatMessage di tipo pollEvent, che rappresenta un sondaggio attivo. Può esserci un solo sondaggio per chat.

Errori

La seguente tabella identifica i messaggi di errore che l'API potrebbe restituire in risposta a una chiamata a questo metodo. Per maggiori dettagli, consulta la documentazione relativa al messaggio di errore.

Quando utilizzi gRPC per connetterti:

Codice di errore gRPC Dettaglio errore Descrizione
PERMISSION_DENIED (7) The caller does not have permission Non disponi delle autorizzazioni necessarie per recuperare i messaggi per la chat live specificata.
INVALID_ARGUMENT (3) Request contains an invalid argument Impossibile analizzare i parametri forniti. Assicurati che liveChatId e gli altri parametri siano nel formato corretto.
FAILED_PRECONDITION (9)* Precondition check failed LIVE_CHAT_DISABLED. La chat live specificata è disattivata.
FAILED_PRECONDITION (9)* Precondition check failed LIVE_CHAT_ENDED. Non puoi recuperare i messaggi della chat live terminata.
NOT_FOUND (5) Requested entity was not found Impossibile trovare la chat live che stai tentando di recuperare. Controlla il valore del parametro liveChatId della richiesta per assicurarti che sia corretto.
RESOURCE_EXHAUSTED (8) Resource has been exhausted (e.g. check quota) La richiesta è stata inviata troppo rapidamente dopo la precedente. Questo errore si verifica quando le richieste API per recuperare i messaggi vengono inviate con una frequenza superiore alle frequenze di aggiornamento di YouTube, il che spreca inutilmente la larghezza di banda.

* A causa di una limitazione di gRPC, non è possibile distinguere in base al codice di errore tra un caso LIVE_CHAT_DISABLED e un caso LIVE_CHAT_ENDED. YouTube sta lavorando attivamente a una soluzione per risolvere il problema.

Quando utilizzi il traffico web per connetterti:

Tipo di errore Dettaglio errore Descrizione
HttpStatus.FORBIDDEN (403) forbidden Non disponi delle autorizzazioni necessarie per recuperare i messaggi per la chat live specificata.
HttpStatus.BAD_REQUEST (400) Reason for invalid request, e.g. pageTokenInvalid Impossibile analizzare i parametri forniti. Assicurati che liveChatId e gli altri parametri siano nel formato corretto.
HttpStatus.FORBIDDEN (403) liveChatDisabled LIVE_CHAT_DISABLED. La chat live specificata è disattivata.
HttpStatus.FORBIDDEN (403) liveChatEnded LIVE_CHAT_ENDED. Non puoi recuperare i messaggi della chat live terminata.
HttpStatus.NOT_FOUND (404) liveChatNotFound Impossibile trovare la chat live che stai tentando di recuperare. Controlla il valore del parametro liveChatId della richiesta per assicurarti che sia corretto.
HttpStatus.FORBIDDEN (403) rateLimitExceeded La richiesta è stata inviata troppo rapidamente dopo la precedente. Questo errore si verifica quando le richieste API per recuperare i messaggi vengono inviate con una frequenza superiore alle frequenze di aggiornamento di YouTube, il che spreca inutilmente la larghezza di banda.