Notificações de callback de gravação em nuvem - ApsaraVideo Live: Central de Documentação do Alibaba Cloud

Os callbacks de gravação em nuvem usam requisições POST HTTP/HTTPS para notificar seu servidor sobre alterações no status das tarefas de gravação, incluindo eventos do ciclo de vida da tarefa e conclusões de upload de arquivos.

Mecanismo de nova tentativa de callback de gravação em nuvem

O sistema reenvia uma mensagem de callback se o código de erro da resposta for 500 ou superior, ou se a requisição atingir o tempo limite.

Formato da mensagem de callback de gravação em nuvem

As mensagens de callback são requisições POST enviadas via HTTP ou HTTPS para a URL configurada.
O corpo da requisição está no formato JSON.

Ao receber uma mensagem de callback, retorne a seguinte resposta:

Header

HttpStatus

Body

Content-Type: application/json

200

{

"Code": 0,

"Msg": "Success"

}

Parâmetros de callback de gravação em nuvem

Nota

Atualmente, as notificações de callback de gravação em nuvem suportam apenas eventos relacionados a alterações no status da tarefa.

Cabeçalho da mensagem de callback

Parâmetro	Valor
Content-Type	application/json
ALI-LIVE-TIMESTAMP	Transmitido apenas quando NotifyAuthKey é válido. Exemplo: 1748417138
ALI-LIVE-SIGNATURE	Transmitido apenas quando NotifyAuthKey é válido. Exemplo: abcdefgxxx

Instruções de autenticação: Se você fornecer um NotifyAuthKey válido ao criar uma tarefa de gravação em nuvem, o sistema incluirá os campos ALI-LIVE-TIMESTAMP e ALI-LIVE-SIGNATURE no cabeçalho da requisição HTTP de callback. Use esses campos para verificar a assinatura do callback e confirmar que a mensagem proviene de uma fonte confiável.

O campo ALI-LIVE-SIGNATURE é gerado da seguinte forma:

ALI-LIVE-SIGNATURE = MD5(MD5CONTENT)
MD5CONTENT = ALI-LIVE-TIMESTAMP + "|" + NotifyAuthKey

Após receber a requisição de callback, obtenha os valores de ALI-LIVE-TIMESTAMP e ALI-LIVE-SIGNATURE no cabeçalho da requisição.
Gere a string MD5CONTENT concatenando o NotifyAuthKey armazenado localmente com o valor de ALI-LIVE-TIMESTAMP do cabeçalho da requisição. Use o caractere pipe (|) como separador.
Calcule o hash MD5 da string MD5CONTENT para obter a assinatura.
Compare a assinatura calculada com o valor de ALI-LIVE-SIGNATURE presente no cabeçalho da requisição.

Se as assinaturas não coincidirem, rejeite a requisição, pois ela pode ter sido enviada por uma fonte não confiável.

Corpo da mensagem de callback

Parâmetro	Tipo	Descrição
appId	string	ID do aplicativo.
channelId	string	ID do canal.
taskId	string	ID da tarefa de gravação.
eventType	string	Tipo de evento. Para mais informações, consulte a tabela Tipos de evento.
callbackTs	integer	Momento em que o callback foi enviado, representado como timestamp UNIX em milissegundos. Exemplo: 1744774345595.
payload	json string	Informações adicionais. Para mais detalhes sobre os parâmetros, consulte a tabela Outras informações.

Tipos de evento (eventType)

Valor	Descrição
TaskCreated	Tarefa criada.
TaskStarting	Tarefa iniciando.
TaskRunning	Tarefa em execução.
TaskRecovering	Tarefa recuperando-se de uma exceção.
TaskStopping	Tarefa sendo interrompida.
TaskStopped	Tarefa interrompida.
TaskStartFailed	Falha ao iniciar a tarefa.
TaskUpdated	Tarefa atualizada com sucesso.
TaskUpdateFailed	Falha ao atualizar a tarefa.
RecordStart	Gravação iniciada.
RecordFailed	A gravação não conseguiu se recuperar de uma exceção e atingiu o tempo limite.
RecordFileUploaded	Arquivo de gravação carregado.

Outras informações (payload)

Parâmetro	Tipo	Descrição
eventTs	integer	Momento em que o evento ocorreu, representado como timestamp UNIX em milissegundos. Exemplo: 1744774345595.
taskStatus	string	Status da tarefa. Para mais informações, consulte a tabela Status da tarefa. Nota Este parâmetro não é retornado quando eventType é RecordFileUploaded.
errorCode	string	Código de erro. Para mais informações, consulte a tabela Erros.
errorMessage	string	Mensagem de erro. Para mais informações, consulte a tabela Erros.
recordFileList	FileList	Lista de arquivos de gravação. Para mais detalhes sobre os parâmetros, consulte a tabela FileList. Nota Este parâmetro é retornado apenas quando eventType é TaskRunning, TaskStopping ou TaskStopped.
recordFile	RecordFile	Detalhes do arquivo de gravação, retornados apenas quando eventType é RecordFileUploaded. Para mais informações, consulte a tabela RecordFile.
format	string	Formato do arquivo de gravação. Retornado apenas quando eventType é RecordFileUploaded. Valores válidos: SLICE (não suportado) HLS MP4 MP3
streamInfo	string	Retornado apenas quando eventType é RecordStart. Indica qual stream assinado iniciou a gravação. Para gravações com mixagem de streams, o valor é sempre Mix. Para gravações de stream único, o valor segue o padrão Single::{UserId}::{Suffix}. UserId corresponde ao ID do usuário associado ao stream. O Suffix varia conforme StreamType e SourceType definidos na assinatura: Se StreamType for 0: Suffix será AV::C caso SourceType seja 0, ou AV::S caso SourceType seja 1. Se StreamType for 1: Suffix será sempre A. Se StreamType for 2 (não suportado para gravação de stream único): Suffix será V::C caso SourceType seja 0, ou V::S caso SourceType seja 1.

Lista de arquivos de gravação (FileList)

Parâmetro	Tipo	Descrição
mp3FileList	array<string>	Array contendo os nomes dos arquivos de gravação MP3.
mp4FileList	array<string>	Array contendo os nomes dos arquivos de gravação MP4.
hlsFileList	array<string>	Array contendo os nomes dos arquivos de gravação HLS.
vodMediaList	array<VodFileInfo>	Array de recursos de mídia VOD, preenchido apenas durante gravações para VOD. Cada item corresponde a um stream assinado. Para mais informações, consulte a tabela VodFileInfo.

Informações do arquivo VOD (VodFileInfo)

Parâmetro	Tipo	Descrição
stream	string	Stream assinado. Para gravações com mixagem de streams, o valor é sempre Mix. Para gravações de stream único, o valor segue o padrão Single::{UserId}::{Suffix}. UserId corresponde ao ID do usuário associado ao stream. O Suffix varia conforme StreamType e SourceType definidos na assinatura. Se StreamType for 0: Suffix será AV::C caso SourceType seja 0, ou AV::S caso SourceType seja 1. Se StreamType for 1: Suffix será sempre A. Se StreamType for 2 (não suportado para gravação de stream único): Suffix será V::C caso SourceType seja 0, ou V::S caso SourceType seja 1.
mediaIds	array<string>	Array de IDs de recursos de mídia gerados durante a gravação.
mergedIds	array<string>	Array de IDs de recursos de mídia mesclados automaticamente após o término da gravação. Preenchido apenas ao gravar para VOD com a mesclagem automática ativada e quando houver mais de um recurso de mídia produzido.

Informações do arquivo de gravação (RecordFile)

Parâmetro	Tipo	Descrição
sliceFile	string	Retornado apenas se este formato for especificado no parâmetro NotifyFileUploadedFormat.
hlsFile	string	Retornado apenas se este formato for especificado no parâmetro NotifyFileUploadedFormat.
mp4File	string	Retornado apenas se este formato for especificado no parâmetro NotifyFileUploadedFormat.
mp3File	string	Retornado apenas se este formato for especificado no parâmetro NotifyFileUploadedFormat.

Status da tarefa (taskStatus)

Nota

O status da tarefa não é afetado por atualizações bem-sucedidas ou com falha. Portanto, o campo taskStatus não inclui esses estados.

Status	Descrição
CREATED	Retornado quando a tarefa é criada.
STARTING	Retornado quando a tarefa está iniciando.
RUNNING	Retornado quando a tarefa está em execução.
RECOVERING	Retornado quando a tarefa está se recuperando de uma exceção.
STOPPING	Retornado quando a tarefa está sendo interrompida.
STOPPED	Retornado após a interrupção da tarefa.
FAILED	Retornado após falha na inicialização da tarefa.

Erros

Nota

Esses parâmetros são preenchidos apenas quando eventType é TaskRecovering, TaskStartFailed ou TaskUpdateFailed. Para todos os outros tipos de evento, eles permanecem vazios.

Tipo de evento (eventType)	Código de erro (errorCode)	Mensagem de erro (errorMessage)	Descrição
Falha ao iniciar a tarefa (TaskStartFailed)	StartTaskError	Channel already closed	O canal está fechado.
Falha ao iniciar a tarefa (TaskStartFailed)	StartTaskError	Start task error	Outros motivos.
Recuperação de estado anormal (TaskRecovering)	RunTaskError	The rms task failed	O módulo de mixagem de streams está operando de forma anormal.
Recuperação de estado anormal (TaskRecovering)	RunTaskError	The record task failed	O módulo de gravação está operando de forma anormal.
Falha na atualização da tarefa (TaskUpdateFailed)	UpdateTaskError	Update task error	Falha ao atualizar a tarefa.
RecordFailed	RunTaskError	Recovering status timeout	A recuperação de uma exceção atingiu o tempo limite.

Exemplos de callback

Evento TaskStopped:

{
    "appId": "mytestappid",
    "callbackTs": 1755504873034,
    "channelId": "room1047",
    "eventType": "TaskStopped",
    "payload": "{\"eventTs\":1755504873014,\"taskStatus\":\"STOPPED\",\"errorCode\":\"\",\"errorMessage\":\"\",\"streamInfo\":\"\",\"recordFileList\":{\"mp3FileList\":[],\"mp4FileList\":[\"mp4/fe60a6e3-cecb-3fae-a8cf-3d2391f507a5/mytestappid_room1047_2025-08-18-15:59:16.mp4\",\"mp4/fe60a6e3-cecb-3fae-a8cf-3d2391f507a5/mytestappid_room1047_2025-08-18-16:02:16.mp4\"],\"hlsFileList\":[\"hls/fe60a6e3-cecb-3fae-a8cf-3d2391f507a5/mytestappid_room1047_2025-08-18-15:59:16.m3u8\",\"hls/fe60a6e3-cecb-3fae-a8cf-3d2391f507a5/mytestappid_room1047_2025-08-18-16:02:16.m3u8\"],\"vodMediaList\":[]}}",
    "taskId": "fe60a6e3-cecb-3fae-a8cf-3d2391f507a5"
}

Evento RecordFileUploaded:

{
    "appId":"mytestappid",
    "callbackTs":1764301584289,
    "channelId":"room1406",
    "eventType":"RecordFileUploaded",
    "payload":"{\"eventTs\":1764301584265,\"errorCode\":\"\",\"errorMessage\":\"\",\"streamInfo\":\"Single::userA::AV::C\",\"format\":\"MP4\",\"recordFile\":{\"sliceFile\":\"\",\"hlsFile\":\"\",\"mp3File\":\"\",\"mp4File\":\"mp4/07c2e845-630d-36a1-b2d1-3b546efdea90/mytestappid_room1406_userA_2025-11-28-11:46:03.mp4\"}}",
    "taskId":"07c2e845-630d-36a1-b2d1-3b546efdea90"}