Pular para o conteúdo
Documentation

RTC: traga seu próprio armazenamento

O RTC pode copiar todas as gravações concluídas para um bucket de sua propriedade. CHAMPREP Ele mantém sua própria cópia também, de modo que a gravação permanece disponível para download no RTC, independentemente de a entrega ter sido bem-sucedida ou não.

A entrega para o seu próprio armazenamento está incluída no Crescimento e Negócios . A avaliação gratuita, o nível Starter e a cota incluída nos planos pagos CHAMPREP não o incluem. Sem ele, as rotas de armazenamento respondem 403 RTC_FEATURE_NOT_IN_PLAN com os níveis que o incluem em offers. Consulte planos e faturamento.

Se o seu plano deixar de incluí-lo, o RTC desativará seus destinos. Após fazer a atualização novamente, reative cada um deles; o RTC executa primeiro um novo teste de gravação.

TipoUtilize-o paraO que o RTC mantém
aws-role (preferencial)Um bucket do AWS S3Nada confidencial. O RTC assume uma função do IAM criada por você, com um ID externo.
s3-compatibleCloudflare R2, MinIO, Wasabi, Backblaze B2 ou AWS com chaves de acessoSeu ID de chave de acesso e sua chave secreta, criptografados

Um destino pertence à sua organização. Ele atende a um projeto ou a todos os projetos quando projectId é null. Uma organização pode ter até 5 destinos; mais uma resposta 409 DESTINATION_LIMIT.

Crie, altere, teste e remova destinos no console do RTC ou por meio da API com sua sessão de console com login. API As chaves não podem criar nem alterar destinos. Uma chave com recordings:read pode listá-los; uma chave de projeto visualiza os destinos do seu projeto e os de todos os projetos.

Método e caminhoCredencialResultado
GET /v1/storage/destinationsSessão do console ou uma chave com recordings:readOs destinos, do mais antigo para o mais recente
GET /v1/storage/destinations/{destinationId}Sessão do console ou uma chave com recordings:readUm destino
GET /v1/storage/aws-setupSessão do consoleSua ID externa e as políticas do IAM a serem coladas (Função da AWS)
POST /v1/storage/destinationsSessão do console201, o destino após sua gravação de teste
PATCH /v1/storage/destinations/{destinationId}Sessão do consoleAltere as configurações, faça a rotação de chaves ou ative ou desative a função
POST /v1/storage/destinations/{destinationId}/testSessão do consoleExecute a gravação de teste novamente
DELETE /v1/storage/destinations/{destinationId}Sessão do console{ "id": "…", "deleted": true }
GET /v1/recordings/{recordingId}/deliveriesrecordings:readAs entregas da gravação (Acompanhe as entregas)
POST /v1/recordings/{recordingId}/redeliverrecordings:write202, entrega a gravação novamente
DELETE /v1/recordings/{recordingId}recordings:writeEnvia a gravação para a Lixeira (excluir uma gravação)
GET /v1/recordings?trashed=truerecordings:readAs gravações na Lixeira
POST /v1/recordings/{recordingId}/restorerecordings:writeRetira a gravação da Lixeira
POST /v1/recordings/{recordingId}/purgerecordings:writeExclui a gravação permanentemente da Lixeira

As credenciais nunca são retornadas. As respostas são enviadas com Cache-Control: no-store.

CampoAmbos os tiposNotes
type✓aws-role ou s3-compatible
name✓Seu rótulo, com até 80 caracteres
projectId✓Um projeto, ou null para cada projeto
bucket, region✓O nome do bucket e sua região
pathTemplate✓Opcional; consulte modelos de caminho
keepCopyDays✓Opcional, de 0 a 3.650, padrão 7; consulte retenção
roleArn, kmsKeyIdaws-roleSua função e, opcionalmente, sua chave KMS para SSE-KMS
provider, endpoint, forcePathStyle, accessKeyId, secretAccessKeys3-compatibleforcePathStyle O padrão é true

Um destino também informa seu status (active, unverified ou disabled), lastCheck (a última gravação de teste) e lastDelivery.

A RTC nunca armazena suas chaves da AWS. Você cria uma função em sua conta que a função de entrega da RTC pode assumir, limitada por um ID externo exclusivo para sua organização.

  1. Chame GET /v1/storage/aws-setup?bucket=<your-bucket> (adicionar pathTemplate e kmsKeyArn (se você os utilizar), ou abra a mesma configuração no console.
  2. Crie uma função IAM. Cole o valor retornado trustPolicy: ele confia principalArn somente quando a solicitação contiver sua externalId.
  3. Anexe o retornado permissionsPolicy. Ele permite s3:PutObject e s3:AbortMultipartUpload no seu caminho, s3:DeleteObject apenas na pasta de validação, e kms:GenerateDataKey e kms:Encrypt na sua chave KMS quando você forneceu uma.
  4. Crie o destino com type: "aws-role" e a função roleArn:
{
"type": "aws-role",
"name": "Recordings archive",
"projectId": null,
"bucket": "acme-rtc-recordings",
"region": "us-east-1",
"roleArn": "<your-delivery-role-arn>"
}

O ID externo é criado uma única vez para a sua organização e não se altera. Quando available é false na resposta de configuração, os destinos de função da AWS ainda não estão disponíveis e a criação de um deles resulta em resposta 503 DELIVERY_NOT_CONFIGURED; utilize chaves de acesso enquanto isso.

Utilizar type: "s3-compatible" para Cloudflare R2, MinIO, Wasabi, Backblaze B2 ou AWS quando preferir chaves de acesso. Nomeie seu serviço no provider campo, com um destes valores: r2, minio, wasabi, backblaze, aws ou other.

  • endpoint deve ser uma origem HTTPS na porta 443, sem caminho, consulta ou nome de usuário, fora de domíniosCHAMPREP, e deve ser resolvida para endereços públicos. O RTC verifica o endereço novamente a cada conexão. Caso contrário, o RTC responde 400 ENDPOINT_NOT_ALLOWED.
  • Conceda às chaves acesso de gravação ao bucket. Exclua o acesso ao champrep-rtc-validation/ A pasta permite que o RTC remova seu objeto de teste.
  • As chaves são criptografadas em repouso e nunca são devolvidas. Um destino exibe apenas accessKeyIdHint, os últimos quatro caracteres do ID da chave.
  • Para alternar as chaves, PATCH accessKeyId e secretAccessKey em conjunto.
  • Quando o armazenamento de chaves não estiver disponível, o RTC responde 503 CREDENTIALS_UNAVAILABLE; utilize uma função da AWS enquanto isso.

O RTC testa um destino quando o senhor o cria, quando altera sua região, modelo de caminho, função, chave KMS, endpoint, estilo de caminho ou chaves, quando o reativa e quando o senhor chama POST /v1/storage/destinations/{destinationId}/test.

O teste grava um objeto de 64 bytes em <path prefix>/champrep-rtc-validation/<uuid>.txt e, em seguida, o remove. Uma remoção recusada é apenas um aviso: permita s3:DeleteObject nessa pasta, ou exclua o objeto você mesmo.

Quando o teste falha, o destino é salvo como unverified e não recebe nada. lastCheck contém um código e uma frase:

CódigoSignificado
ROLE_ASSUME_DENIEDO RTC não conseguiu assumir a função (política de confiança ou ID externo)
WRITE_DENIEDA gravação foi recusada
BUCKET_NOT_FOUNDO bucket não existe
WRONG_REGIONO bucket está em outra região
INVALID_ACCESS_KEY, INVALID_SECRET_KEYAs chaves foram recusadas
KMS_DENIEDA chave KMS recusou a criptografia
ENDPOINT_NOT_ALLOWED, ENDPOINT_NOT_FOUND, ENDPOINT_UNREACHABLEO endpoint foi recusado, é desconhecido ou não está respondendo
DELIVERY_NOT_CONFIGUREDOs destinos de função da AWS ainda não estão disponíveis
STORAGE_ERROROutro erro de armazenamento

Corrija a causa e, em seguida, teste novamente. Um destino torna-se active quando um teste é bem-sucedido. Um destino desativado pelo CHAMPREP suporte não pode ser reativado por você (DESTINATION_ADMIN_DISABLED).

O modelo define a chave do objeto de cada arquivo. O padrão é:

{project}/{yyyy}/{mm}/{dd}/{room}/{recording_id}/{file}
VariávelValor
{project}ID do projeto
{room}ID da sala
{recording_id}ID da gravação
{external_ref}A sala externalRef; none quando estiver ausente ou for incomum
{track_id}ID da faixa
{artifact}Qual arquivo da gravação
{file}<trackId>.mkv, recording.mp4, audio.m4a, ou para um transcrição transcript.json e transcript.vtt
{yyyy}, {mm}, {dd}Partes da data

Os aliases project_id, projectId, room_id, roomId, recordingId, externalRef e trackId também são aceitos.

Um modelo deve conter {recording_id} e termine com {file}. O texto literal pode conter letras, dígitos e ! _ . * ' ( ) / -. Não pode ser iniciado com / ou conter //, . ou .. pastas. Uma chave pode ter, no máximo, 900 bytes.

  • Quando uma gravação é ready, o RTC copia cada um de seus arquivos (todas as faixas e os arquivos compostos, quando houver) para cada destino ativo de seu projeto. Uma transcrição concluída transcrição é entregue da mesma forma, como transcript.json e transcript.vtt.
  • Apenas as gravações que terminam após um destino se tornar ativo são entregues automaticamente. Entregue as anteriores com redeliver.
  • Arquivos com mais de 16 MiB são enviados em partes. O RTC informa o SHA-256 dos bytes que enviou.
  • Uma tentativa malsucedida é repetida com intervalo de espera (1, 2, 4 … minutos, com no máximo uma hora de intervalo) por 72 horas. Após esse período, a entrega é considerada malsucedida e recording.delivery_failed é enviada.
  • Os bytes entregues contam para o limite de download do seu plano.
  • Desativar um destino cancela suas entregas em fila. Removê-lo tem o mesmo efeito e exclui suas credenciais.

Um processo interrompido no meio de um upload pode deixar partes incompletas em seu bucket. Adicione um AbortIncompleteMultipartUpload regra de ciclo de vida (1 dia) para o bucket.

Inscreva-se no seu pontos de extremidade do webhook a esses eventos. Cada arquivo enviado gera seu próprio evento.

Eventodata
recording.deliveredrecordingId, roomId, destinationId, artifact, trackId (para uma faixa), bucket, key, size, sha256, checksum, etag, deliveredAt
recording.delivery_failedrecordingId, roomId, destinationId, artifact, trackId (para uma faixa), bucket, key, attempts, error (code, message)

Uma gravação contém um resumo de entrega: delivery.state (pending, delivered, partial ou failed) e o pending, delivered e failed conta.

GET /v1/recordings/{recordingId}/deliveries retorna recordingId, que summary e deliveries: cada tarefa com seu bucket de destino e chave, seu resultado (tamanho, SHA-256 e ETag) e seu último erro.

POST /v1/recordings/{recordingId}/redeliver com um opcional { "destinationId": "…" } reinicia as tarefas com falha, canceladas e entregues com um novo prazo de 72 horas e cria as que estiverem faltando.

HTTPCódigoSignificado
409RECORDING_NOT_READYApenas um ready A gravação pode ser entregue
409NO_ACTIVE_DESTINATIONNenhum destino ativo se aplica a esta gravação
404NO_ACTIVE_DESTINATIONNenhum destino ativo possui isso destinationId

A exclusão de uma gravação a envia para a Lixeira. Ela é excluída automaticamente após 30 dias, e você pode restaurá-la até esse momento. Todas as chamadas a seguir requerem uma tecla com recordings:write ou sua sessão do console.

DELETE /v1/recordings/{recordingId} envia a gravação para a Lixeira:

{ "id": "…", "status": "trashed", "trashedAt": "2026-11-08T12:00:00.000Z", "reason": "customer", "purgeAt": "2026-12-08T12:00:00.000Z" }
  • A gravação sai da lista e GET /v1/recordings/{recordingId}. GET /v1/recordings?trashed=true lista as gravações na Lixeira.
  • Seus downloads deixam de funcionar, incluindo os links de download já gerados.
  • Suas entregas agendadas são canceladas.
  • Ainda ocupa espaço no armazenamento de gravações e é cobrada enquanto estiver na Lixeira.
  • purgeAt É quando ocorre a exclusão automática: 30 dias após ter sido enviada para a Lixeira. É fixado quando a gravação é enviada para a Lixeira: uma alteração posterior na janela da Lixeira se aplica apenas às gravações enviadas para a Lixeira após essa data. purgeAt é null enquanto a exclusão automática da Lixeira estiver desativada.
  • recording.deleted é enviado.
  • Uma gravação que ainda esteja em execução ou em processamento responde 409 RECORDING_ACTIVE; interrompa ou aguarde.

POST /v1/recordings/{recordingId}/restore retira a gravação da Lixeira. A resposta é a gravação, de volta às suas listas e downloads como antes de ter sido excluída. recording.restored é enviado. Você pode restaurar um registro até que ele seja excluído automaticamente ou de forma definitiva. Uma restauração que chegue tarde demais responde 409 RECORDING_PURGED.

As entregas para o seu próprio armazenamento que foram canceladas quando a gravação foi enviada para a Lixeira são reenviadas. Uma gravação restaurada é mantida até que o(a) senhor(a) a exclua novamente: a retenção não a reenvia para a Lixeira.

POST /v1/recordings/{recordingId}/purge exclui definitivamente uma gravação da Lixeira. O RTC aceita a solicitação imediatamente e responde 202; a exclusão será concluída em breve:

{ "id": "…", "status": "deleting", "purgeRequestedAt": "2026-11-08T12:05:00.000Z" }
  • Ele nunca pode ser restaurado, a partir do momento em que o RTC aceita a solicitação.
  • Quando a exclusão é concluída, seus arquivos são apagados, deixando de ser contabilizados no armazenamento de registros, e recording.purged é enviado.
  • Repetir a solicitação é seguro: ela responde 202 novamente enquanto a exclusão é executada, então 200 assim que estiver concluído: { "id": "…", "status": "purged", "purgedAt": "2026-11-08T12:05:30.000Z" }.
  • Apenas um registro na Lixeira pode ser excluído permanentemente. Qualquer outro registro responde 409 RECORDING_NOT_IN_TRASH: envie-o primeiro para a Lixeira.

Um registro é excluído permanentemente em seu purgeAt (30 dias na Lixeira), da mesma forma, e recording.purged é enviado com reason: "expired". O CHAMPREP suporte também pode excluir um registro da Lixeira antecipadamente, mediante sua solicitação.

As cópias já entregues no seu bucket são de sua propriedade. Enviar uma gravação para a Lixeira, excluí-la permanentemente ou ativar sua exclusão automática nunca as remove.

CHAMPREP mantém sua própria cópia de um registro de acordo com o prazo de retenção do seu plano: 7 dias na versão de teste, 30 dias no plano Starter, 90 dias no plano Growth e 365 dias no plano Business. Quando esse prazo expirar, o registro será enviado para a Lixeira da mesma forma que acima, com reason: "retention": é possível restaurá-lo por 30 dias, e ele é excluído automaticamente após esse período.

A retenção se aplica apenas às gravações feitas após o RTC ter começado a aplicá-la. Gravações feitas antes dessa data não são expiradas por ela. A retenção nunca afeta as cópias em seu próprio bucket.

keepCopyDays em um destino (0 a 3650, padrão 7) registra por quanto tempo você deseja CHAMPREPmanter sua cópia após uma entrega. A cópia CHAMPREPde hoje segue a retenção do seu plano; essa configuração não a remove antes do prazo.