Extrações de dados

Uma extração de dados (data harvest) é um arquivo ZIP contendo os dados da conta atual. O Decoding Chat a compila em segundo plano, relata o progresso durante a execução e emite uma URL de download temporária assim que o arquivo é gravado.

Todas as rotas, exceto Download data harvest archive, são exclusivas para usuários. O Decoding Chat rejeita um bot ou credencial de portador (bearer) OAuth2 com 403 ACCESS_DENIED, e uma conta que possui sinalizadores de atividade suspeita com 403 ACCOUNT_SUSPICIOUS_ACTIVITY. Nenhuma rota aqui requer o modo sudo. A rota Delete current user’s messages aceita o mesmo formato de filtro, destrói as mensagens e o exige.

Um arquivo concluído tem um prazo de download de sete dias

Uma extração concluída registra um prazo de exatamente sete dias após a gravação do arquivo. Após isso, Get data harvest download URL retorna 400 HARVEST_EXPIRED e Download data harvest archive retorna 404, enquanto o registro continua relatando completed. Nada estende ou restaura esse prazo.

Valores de status de extração

Use status para acompanhar a preparação do arquivo.

Valor	Descrição
pending	Nenhuma tentativa de processamento foi iniciada
processing	Uma tentativa começou e não foi concluída nem falhou
completed	O arquivo foi gravado e está pronto para download
failed	A tentativa mais recente registrou uma falha

O Decoding Chat tenta novamente a tarefa subjacente. Uma nova tentativa limpa failed_at e error_message, define started_at novamente, zera o progresso relatado para 0 e relata processing enquanto está em execução. Em caso de sucesso, registra completed_at, file_size e um prazo de download, e relata completed.

Objeto de criação de extração

A confirmação retornada por ambas as operações de criação.

Estrutura

Campo	Tipo	Descrição
harvest_id	snowflake	O ID da extração criada
status1	string	O status da extração na criação
created_at2	timestamp ISO8601	Quando a extração foi solicitada

¹ Sempre pending

² Registrado no mesmo momento em que o snowflake é gerado, portanto, ordenar as extrações por ID é o mesmo que ordená-las por created_at

Objeto de status de extração

O estado completo de uma extração. Ele estende o objeto de criação da extração com campos de progresso e conclusão.

Estrutura

Campo	Tipo	Descrição
harvest_id	snowflake	O ID da extração
status	string	O status da extração derivado
created_at	timestamp ISO8601	Quando a extração foi solicitada
started_at1	?timestamp ISO8601	Quando a tentativa de processamento atual começou, ou null enquanto a extração estiver pendente
completed_at	?timestamp ISO8601	Quando o arquivo foi gravado, ou null quando não foi
failed_at2	?timestamp ISO8601	Quando a tentativa mais recente registrou falha, ou null quando não houve falha
file_size3	?string	O tamanho do arquivo em bytes como uma string decimal, ou null antes do arquivo ser gravado
progress_percent4	number	Progresso de 0 a 100
progress_step5	?string	O etapa de progresso da extração para o estágio atual
error_message6	?string	A descrição da falha da tentativa mais recente, ou null quando não tiver falhado
download_url_expires_at7	?timestamp ISO8601	Quando o prazo de download do arquivo expira, ou null antes da conclusão
expires_at8	?timestamp ISO8601	Quando o prazo de download do arquivo expira, ou null antes da conclusão

¹ Uma nova tentativa de processamento substitui este timestamp, redefine progress_percent para 0 e define progress_step como Starting harvest

² Limpo quando uma nova tentativa começa, de modo que é não-nulo apenas quando a tentativa mais recente falhou

³ Uma string decimal porque o valor é de 64 bits

⁴ Cada valor registrado é um número inteiro. Ele nunca diminui dentro de uma mesma tentativa, e a conclusão o define para exatamente 100

⁵ Todo registro é criado com a etapa Queued, então este membro nunca é nulo

⁶ A forma em string da falha subjacente. É para diagnóstico e não é estável para correspondência programática

⁷ Registrado quando o arquivo é gravado, exatamente sete dias após esse momento. Depois disso, o Decoding Chat não emite uma nova URL de download

⁸ Um segundo nome para download_url_expires_at. O valor armazenado é o mesmo

Etapas de progresso de extração

Um rótulo curto em inglês que descreve o estágio atual. Todos os valores são fixos, exceto o rótulo de mensagens extraídas, que inclui a contagem de mensagens.

Valor	Descrição
Queued	Registrado quando o registro da extração é criado, com progresso 0
Starting harvest	Registrado quando uma tentativa de processamento começa, com o progresso redefinido para 0
Harvesting messages	A coleta de mensagens foi iniciada, com progresso 5
Harvested N messages1	A coleta de mensagens foi concluída, onde N é a contagem decimal exata coletada
Collecting user metadata	Os dados da conta estão sendo coletados, com progresso 60
Downloading attachments and creating archive	O arquivo ZIP está sendo gravado, com progresso 65
Completed	O arquivo está pronto, com progresso 100

¹ Ignorado quando nenhuma mensagem é coletada

Objeto de download de extração

Uma URL de download emitida e sua expiração declarada.

Estrutura

Campo	Tipo	Descrição
download_url1	string	A URL temporária de download do arquivo (1-2048 caracteres)
expires_at2	timestamp ISO8601	Sete dias após esta resposta ter sido gerada

¹ Resolve para um único objeto ZIP servido como application/zip

² Exatamente sete dias após a emissão, mesmo quando o prazo do próprio arquivo termina antes

Uma URL apontando para Download data harvest archive ainda para de resolver no prazo do próprio arquivo, então a expiração declarada nela pode durar mais do que o ponto em que ela para de funcionar.

Uma URL emitida possui sua própria validade de sete dias

Uma URL pré-assinada (presigned) de armazenamento de objetos, a forma padrão, nunca é verificada novamente em relação ao registro da extração; assim, uma URL emitida pouco antes do prazo continua funcionando após ele. A forma de token assinado verifica o prazo novamente.

Objeto de filtro de mensagens de extração

O filtro escolhe quais mensagens uma extração coleta. Todas as seções não relacionadas a mensagens do arquivo são incluídas independentemente do que o filtro determinar.

Estrutura

Campo	Tipo	Descrição
scope?1	string	Qual conjunto de contextos a extração segmenta, seja selected ou inaccessible_only (padrão selected)
include_dms?	boolean	Se deve incluir mensagens diretas um-para-um que o autor da chamada ainda tem abertas (padrão true)
include_dms_closed?2	boolean	Se deve incluir mensagens diretas um-para-um que o autor da chamada fechou (padrão true)
include_group_dms?	boolean	Se deve incluir DMs em grupo das quais o autor da chamada ainda é membro (padrão true)
include_guilds?	boolean	Se deve incluir canais de texto em servidores (guilds) dos quais o autor da chamada é membro (padrão true)
guild_filter_mode?3	string	Como a lista de servidores é lida, seja exclude ou include_only (padrão exclude)
excluded_guild_ids?	array[snowflake]	Os servidores para omitir no modo exclude (máx. 500, padrão vazio)
included_guild_ids?	array[snowflake]	Os únicos servidores a incluir no modo include_only (máx. 500, padrão vazio)
start_date?4	?timestamp ISO8601	Limite inferior inclusivo nos timestamps de mensagens, ou null para sem limite inferior
end_date?4	?timestamp ISO8601	Limite superior exclusivo nos timestamps de mensagens, ou null para sem limite superior

¹ O escopo selected requer que pelo menos um dos campos de inclusão seja verdadeiro (true), e um corpo que os desabilite todos é rejeitado no caminho include_dms

² Independente de include_dms, portanto, definir include_dms como falso e include_dms_closed como verdadeiro direciona apenas para conversas fechadas

³ As listas de servidores são lidas apenas quando include_guilds for verdadeiro e o escopo for selected, e a lista que não corresponde ao modo é ignorada

⁴ Comparado com o tempo de criação embutido no snowflake da mensagem, então a edição de uma mensagem antiga não a move para uma janela posterior

No escopo selected, cada contexto tem sua própria condição:

• Uma mensagem direta um-para-um é coletada quando a conversa ainda está aberta e include_dms é verdadeiro, ou quando foi fechada e include_dms_closed é verdadeiro.
• Um DM em grupo é coletado apenas enquanto o autor da chamada ainda for um destinatário e include_group_dms é verdadeiro.
• Um canal de servidor é coletado apenas enquanto o autor da chamada ainda for um membro, include_guilds é verdadeiro e o servidor for admitido pelo modo de lista configurado.

O escopo inaccessible_only seleciona mensagens em servidores dos quais o autor da chamada saiu ou foi removido e em DMs em grupo que o autor da chamada abandonou. Ele nunca seleciona mensagens diretas um-para-um e ignora as opções, o modo de filtro de servidor e as duas listas de servidores.

Ambos os escopos excluem o canal de anotações pessoais do autor da chamada, e ambos excluem uma mensagem cujo canal não é mais resolvido ou não é nem uma mensagem direta, um DM em grupo nem um canal de servidor.

Fornecer ambos os limites de data exige que start_date seja estritamente anterior a end_date. Um par igual ou invertido é rejeitado no caminho end_date.

Um arquivo filtrado ainda tem todas as seções sem mensagens

O arquivo ainda contém o documento da conta, o documento do histórico de pagamentos, o documento do aplicativo próprio, o documento de segurança e o avatar e banner da conta. Nenhuma resposta de leitura retorna o filtro aplicado, então quem fez a chamada mantém seu próprio registro do que enviou.

Solicitar extração de dados

POST/v1/users/@me/harvest

Cria uma extração não filtrada da conta. Retorna um objeto de criação de extração em caso de sucesso.

A operação não recebe corpo na solicitação e sempre retorna antes que o arquivo exista, de modo que o autor da chamada deve consultar Get data harvest status ou Get latest data harvest usando o ID retornado.

Resposta

Status	Corpo	Condição
200	objeto de criação de extração	A solicitação de extração foi aceita
404	resposta de erro	A conta autenticada não é mais resolvida e a requisição retorna UNKNOWN_USER
500	resposta de erro	O registro da extração não pôde ser gravado ou o trabalho não pôde ser enfileirado

Efeitos colaterais

Um registro de extração é criado com um novo snowflake, o horário da solicitação como created_at, progresso 0, a etapa Queued, e todos os outros timestamps nulos. Criar uma extração não remove nenhum registro anterior e não impõe limite de quantas uma conta pode reter, então o bucket de rotas é o único limite.

O Decoding Chat prepara o arquivo em segundo plano. Ele contém:

• user.json, o documento da conta, incluindo conexões com seus identificadores, configurações de visibilidade e datas de verificação, mas nenhuma credencial
• um arquivo channels/{channel_id}/messages.json para cada canal que contribuiu com uma mensagem, com suas mensagens ordenadas da mais antiga para a mais nova
• payments/payment_history.json
• integrations/oauth.json, as aplicações de propriedade da conta, sem entrada para uma aplicação que ela apenas autorizou
• account/security.json
• o avatar e o banner da conta em assets/user/, quando presentes

Metadados de anexo aparecem com sua mensagem e têm o ID do anexo, nome do arquivo, tamanho, tipo de conteúdo, URL do CDN e dimensões em pixels. A URL do CDN é uma URL de anexo de pacote de dados, portanto não expira e ainda lê seu anexo depois que o próprio prazo de sete dias do arquivo expira. Remover o segredo que o assinou é a única coisa que o encerra. Os próprios arquivos de anexo nunca são incluídos.

Cada mensagem de autoria é coletada, sem limite na contagem. Mensagens que não existem mais são omitidas. Outras falhas de leitura falham a tentativa. Após a conclusão, o Decoding Chat tenta enviar uma URL de download por e-mail se a conta tiver um endereço de e-mail e a instância tiver a entrega de e-mail ativada. Essa URL expira sete dias após sua emissão. A falha no e-mail não impede o download de um arquivo concluído.

Limite de taxa

5 requisições por 30 minutos para cada usuário autenticado, no bucket user:data:harvest compartilhado com Request filtered data harvest.

Solicitar extração de dados filtrada

POST/v1/users/@me/harvest/filtered

Cria uma extração cuja coleta de mensagens é restrita por um filtro. Retorna um objeto de criação de extração em caso de sucesso.

Corpo JSON

O corpo é um objeto de filtro de mensagens de extração. Todo campo é opcional, então um objeto vazio é aceito e todo valor padrão admite seu contexto. Um corpo de solicitação vazio é lido como um objeto vazio.

Um arquivo filtrado testa a elegibilidade do canal para cada mensagem

Mesmo com todos os padrões, um arquivo filtrado descarta mensagens no canal de anotações pessoais do autor da chamada, em DMs de grupo e servidores dos quais o autor saiu, e em um canal que não resolve mais. Request data harvest coleta essas mensagens.

Resposta

Status	Corpo	Condição
200	objeto de criação de extração	A solicitação da extração filtrada foi aceita
400	resposta de erro	Um campo de filtro falhou na validação, o escopo selected não ativou nenhum contexto, uma lista de servidores excedeu 500 entradas ou os limites de data não eram estritamente crescentes
404	resposta de erro	A conta autenticada não é mais resolvida e a requisição retorna UNKNOWN_USER
500	resposta de erro	O registro da extração não pôde ser gravado ou o trabalho não pôde ser enfileirado

Efeitos colaterais

Os efeitos colaterais correspondem a Request data harvest, exceto que apenas as mensagens selecionadas pelo filtro são coletadas.

Limite de taxa

5 requisições por 30 minutos para cada usuário autenticado, no bucket user:data:harvest compartilhado com Request data harvest.

Obter a extração de dados mais recente

GET/v1/users/@me/harvest/latest

Retorna o objeto de status de extração criado mais recentemente para a conta.

Retorna a extração mais recente, independentemente do status, incluindo uma extração que falhou e que é mais recente que uma concluída.

Uma conta sem extração recebe 200 e null

O corpo é o valor JSON literal null, então decodifique-o antes de tratar a resposta como um objeto.

Resposta

Status	Corpo	Condição
200	objeto de status de extração | null	O estado mais recente da extração foi retornado, ou null quando não houver nenhuma

Limite de taxa

40 requisições a cada 10 segundos para cada usuário autenticado, no bucket user:harvest:latest.

Obter o status da extração de dados

GET/v1/users/@me/harvest/{harvestId}

Retorna um objeto de status de extração pertencente à conta atual.

Uma extração pertencente a outra conta retorna 404 UNKNOWN_HARVEST.

O Decoding Chat não remove nenhum registro de extração, portanto, um ID que foi resolvido uma vez continua a ser resolvido. Um 404 significa que o ID nunca foi emitido para esta conta, e a extração de outra conta nunca é distinguível de uma que nunca existiu.

Parâmetros de caminho

Campo	Tipo	Descrição
harvestId	snowflake	O ID da extração

Resposta

Status	Corpo	Condição
200	objeto de status de extração	O estado da extração foi retornado
404	resposta de erro	A extração é desconhecida ou pertence a outra conta, retornando UNKNOWN_HARVEST

Limite de taxa

40 requisições a cada 10 segundos para cada usuário autenticado, no bucket user:harvest:status.

Obter a URL de download da extração de dados

GET/v1/users/@me/harvest/{harvestId}/download

Emite uma URL temporária de download para uma extração concluída. Retorna um objeto de download de extração em caso de sucesso.

O Decoding Chat avalia os casos de rejeição em uma ordem fixa, cada um com seu próprio código. Uma extração desconhecida ou de terceiros resulta em 404 UNKNOWN_HARVEST. Uma extração cuja tentativa mais recente falhou é 400 HARVEST_FAILED. Uma extração sem conclusão registrada ou nenhum arquivo armazenado é 400 HARVEST_NOT_READY. Uma extração além do prazo de download é 400 HARVEST_EXPIRED.

Cada requisição emite uma nova URL bearer

Uma URL é criada para cada chamada, seu prazo declarado é de sete dias depois, e uma chamada posterior não revoga nada. Trate cada URL emitida como um segredo.

A URL assume uma das formas abaixo. Quando a instância tem downloads de extração pré-assinados (presigned) habilitados, que é o padrão, é uma URL pré-assinada de armazenamento de objetos. Caso contrário, ela aponta para Download data harvest archive nesta API com um parâmetro de consulta token assinado.

Parâmetros de caminho

Campo	Tipo	Descrição
harvestId	snowflake	O ID da extração

Resposta

Status	Corpo	Condição
200	objeto de download de extração	Uma URL de download foi emitida
400	resposta de erro	A extração retorna HARVEST_NOT_READY, HARVEST_FAILED, ou HARVEST_EXPIRED
404	resposta de erro	A extração é desconhecida ou pertence a outra conta, retornando UNKNOWN_HARVEST
500	resposta de erro	A URL de download não pôde ser emitida

Limite de taxa

10 requisições por minuto para cada usuário autenticado, no bucket user:harvest:download.

Fazer download do arquivo de extração de dados

GET/v1/harvest-downloads/{harvestId}Unauthenticated

Transmite o arquivo de uma extração concluída.

O parâmetro de consulta token emitido por Get data harvest download URL autoriza o download sem uma sessão. Use a URL completa emitida e a mantenha em segredo.

A operação está ativa apenas enquanto a instância tem downloads de extração pré-assinados desabilitados. Essa configuração é habilitada por padrão, portanto, uma implantação padrão responde a todas as solicitações aqui como 404 sem inspecionar o token.

Cada rejeição parece idêntica

Um token ausente, malformado, forjado ou expirado, e um token para outra extração retornam todos 404 com o corpo em texto simples Not Found. O mesmo vale para uma extração que nunca foi concluída, que registrou uma falha, que passou de seu prazo ou para uma chave de objeto obsoleta.

Parâmetros de caminho

Campo	Tipo	Descrição
harvestId	snowflake	O ID da extração

Parâmetros de consulta

Campo	Tipo	Descrição
token	string	Token de download assinado emitido com a URL de download

Cabeçalhos de requisição

Campo	Tipo	Descrição
Range?	string	Intervalo de bytes padrão, respondido com 206 e um cabeçalho Content-Range

Resposta

Status	Corpo	Condição
200	bytes do arquivo	O arquivo completo foi transmitido
206	bytes do arquivo	O intervalo de bytes solicitado foi transmitido
404	Not Found	O token está ausente, inválido ou expirado, a extração não permite download ou a instância emite URLs pré-assinadas no lugar
500	resposta de erro	O armazenamento de objetos não pôde ser lido

Cabeçalhos de resposta

O 200 possui Content-Type: application/zip, Content-Disposition¹, Content-Length, Accept-Ranges: bytes e Cache-Control: private, no-store. O 206 possui os cabeçalhos do 200 mais Content-Range. O 404 possui Content-Type: text/plain.

¹ Content-Disposition é sempre attachment e nomeia o arquivo fluxer-data-{harvestId}.zip

Efeitos colaterais

O arquivo é lido e transmitido. A extração fica inalterada e o token não é consumido, de forma que permanece utilizável até a sua própria validade.

Limite de taxa

60 requisições por minuto para cada endereço IP do cliente, ou para a conta autenticada quando a solicitação tiver uma credencial resolúvel, no bucket user:harvest:download_file.