Upload de anexos

Envie anexos como partes files[n] em uma mensagem multipart, ou faça o upload antes de criar a mensagem. O pré-upload tem quatro etapas:

1. Solicite um plano de upload.
2. Envie os bytes para as URLs de upload do plano.
3. Conclua o upload, se for multipart.
4. Inclua o upload_filename ao criar ou editar a mensagem.

O pré-upload pode estar desligado

Quando os recursos da instância informarem presigned_attachment_uploads como falso, use uploads multipart embutidos. Requisições de plano e de conclusão retornam 403 FEATURE_TEMPORARILY_DISABLED.

Solicitando um plano de upload

Solicitar URLs de upload de anexo aceita até 10 arquivos. Declare o ID, o nome, a contagem exata de bytes e o tipo de conteúdo de cada arquivo. A referência do endpoint define os campos, as permissões e os limites de tamanho.

Guarde o plano devolvido, incluindo o upload_filename. Use o content_type devolvido, que o Decoding Chat deriva do nome do arquivo e que pode, portanto, diferir do valor declarado. O upload_mode determina os próximos passos.

Modos de upload

Valor	Selecionado para	Campos adicionados
singlepart1	Um file_size declarado de no máximo 10485760 bytes	upload_url
multipart2	Um file_size declarado acima de 10485760 bytes	upload_id, part_size e parts

¹ Armazenado assim que o PUT é bem-sucedido, então nunca é enviado para Concluir upload de anexo

² Cada entrada de parts tem um part_number começando em um e sua própria upload_url, e o array vem ordenado por número de parte crescente

Geometria das partes

Use o part_size e o parts devolvidos no plano de upload. Toda parte precisa conter exatamente part_size bytes, exceto a última, que contém o restante. Não calcule um layout de partes diferente.

Transferindo os bytes

Envie requisições PUT para os valores de upload_url devolvidos, sem cabeçalho Authorization. As URLs podem apontar para o armazenamento ou para o repasse de upload. Não reescreva os caminhos nem as query strings.

Envie exatamente a contagem de bytes declarada. O repasse retorna 413 para corpo grande demais e 401 para capacidade ausente, inválida ou expirada. Também retorna 413 para corpo acima do próprio limite, que por padrão é 500 MiB.

Uma transferência singlepart envia o arquivo inteiro com o content_type da entrada como cabeçalho Content-Type. Uma transferência multipart envia cada parte separadamente.

Tempo de vida das capacidades

Capacidade	Tempo de vida
URL de upload singlepart direto	5 minutos
URL de parte multipart direto	1 hora
URL de repasse de qualquer tipo1	O tempo de vida do token de repasse que a implantação configura, 900 segundos por padrão

¹ A expiração do repasse é exclusiva, então a capacidade já é recusada no segundo da expiração

A URL completa é a credencial

Uma URL de upload emitida autoriza a escrita de um objeto ou de uma parte. O cliente trata a URL inteira, query string incluída, como segredo até ela expirar, e a mantém fora de logs, referenciadores e destinos de redirecionamento.

Concluindo um upload multipart

Concluir upload de anexo finaliza de 1 a 10 uploads multipart. Envie o upload_filename e o upload_id de cada plano depois que todas as partes forem bem-sucedidas. Não envie lista de partes nem entity tags.

A conclusão verifica de novo as permissões e os limites de tamanho. Veja a tabela de respostas do endpoint para os erros. Se a conclusão abortar o upload, solicite um novo plano e envie o arquivo outra vez.

Vinculando o upload

Inclua o upload_filename em um anexo pré-enviado ao chamar Criar mensagem ou Modificar mensagem. Só fazer o upload não cria mensagem nem emite evento no Gateway.

Um upload fica vinculado à identidade e ao canal que o planejaram, e cada chave serve uma única vez. Uma chave que a identidade autenticada não possui, uma chave planejada para outro canal e uma chave já consumida por um anexo retornam, cada uma, 400 INVALID_FORM_BODY com UPLOADED_ATTACHMENT_NOT_FOUND em attachments.{index}.upload_filename. Quando o objeto não está no armazenamento, que é o que um plano sem transferência deixa para trás, o vínculo retorna o mesmo status com FILE_NOT_FOUND no mesmo caminho.

Não existe operação de retomada

Uma vez expirada, a capacidade não pode ser renovada, e o plano não pode ser lido de novo. Um cliente que perde o plano, ou cujas capacidades de parte expiram no meio da transferência, solicita um novo plano para o arquivo e recomeça.

Prévias de transmissão

Uma prévia de transmissão é um JPEG anexado a uma conexão de voz. Ela usa a API de transmissões, exclusiva de usuários, e não o fluxo de anexos. Siga as regras de acesso dela para ler ou alterar uma prévia.

Trate uma prévia armazenada como afirmação de quem publica

Uma prévia não prova que a conexão dela esteja publicando uma transmissão no momento.

Use Enviar prévia de transmissão para mandar a imagem como base64 em JSON. O base64 canônico usa o alfabeto padrão, comprimento divisível por quatro e no máximo dois caracteres = no fim. Decodificar e recodificar precisa produzir a mesma string. Codificação inválida retorna 400 INVALID_STREAM_THUMBNAIL_PAYLOAD.

Como alternativa, solicite uma URL de upload e envie o JPEG com PUT. Use o content_type devolvido, envie no máximo max_bytes bytes e faça o upload antes de expires_at. A URL pode ser reutilizada até expirar.

Envie um JPEG válido de no máximo 1000000 bytes. Obter prévia de transmissão a lê, e Excluir prévia de transmissão a remove.

Uma prévia expira um dia depois do upload embutido ou da requisição que emitiu a URL de upload. Reutilizar a URL não estende o tempo de vida da prévia. Uma prévia expirada retorna 404 vazio.

Falhas

Requisições de API retornam a resposta de erro padrão. Requisições de repasse retornam erros de mídia em texto puro. Erros diretos do armazenamento usam o formato do provedor de armazenamento.

Cada endpoint da API documenta o próprio limite de taxa. O repasse não tem limite de taxa por contagem de requisições.