Trabalhos em lote

Um trabalho em lote aplica uma operação a um conjunto explícito de usuários ou guildas. O campo task seleciona o corpo da solicitação e a Admin ACL necessária.

Todo alvo é uma lista de IDs. Não há seletor de pesquisa, cargo, tag, e-mail ou IP, portanto, o chamador resolve seu próprio conjunto de alvos primeiro com Listar usuários ou Listar guildas.

Enfileirar trabalho em lote retorna um identificador de trabalho imediatamente e não aplica nada de forma síncrona. O chamador lê o progresso, o estado terminal e o texto de falha através de Obter trabalho. Cancelar trabalho interrompe uma execução.

Objeto de criação de trabalho em lote

Uma criação de trabalho em lote possui o identificador do trabalho enfileirado.

Estrutura

Campo	Tipo	Descrição
job_id¹	snowflake	O trabalho que aplica a operação solicitada, legível através de Obter trabalho

¹ O trabalho é legível assim que esta resposta chega

Exemplo

{
  "job_id": "1501314428688998182"
}

Tipos de tarefas em lote

Cada valor é o discriminador exato de task.

`update_user_flags`

ACL bulk:update:user_flags. Adiciona e remove sinalizadores de conta em cada usuário alvo. Executa como bulkUpdateUserFlags.

`update_suspicious_activity_flags`

ACL bulk:update:suspicious_activity. Adiciona e remove requisitos de verificação em cada usuário alvo. Executa como bulkUpdateSuspiciousActivityFlags.

`update_guild_features`

ACL bulk:update:guild_features. Adiciona e remove recursos em cada guilda alvo. Executa como bulkUpdateGuildFeatures.

`add_guild_members`

ACL bulk:add:guild_members. Adiciona cada usuário alvo a uma guilda. Executa como bulkAddGuildMembers.

`schedule_user_deletion`

ACL bulk:delete:users. Agenda a exclusão de conta para cada usuário alvo. Executa como bulkScheduleUserDeletion.

Cada tarefa de trabalho é registrada como task_type no trabalho e listada em tipos de tarefas de trabalho em segundo plano. Toda tarefa em lote é executada na faixa de processamento lifecycle.

Enfileirar trabalho em lote

POST/v1/admin/bulk-jobs

Audit reason

Enfileira uma operação em lote. Retorna um objeto de criação de trabalho em lote em caso de sucesso.

Limitações

O corpo corresponde exatamente a uma variante de task.
O chamador precisa de pelo menos uma das ACLs em lote e, em seguida, a ACL exata que a task seleciona.

Corpo JSON

O discriminador task seleciona uma dessas estruturas. Toda matriz de IDs tem um limite superior e nenhum limite inferior, portanto, uma matriz vazia enfileira um trabalho que não processa nada e termina com o status succeeded.

Estrutura de atualização de sinalizadores de usuário

Campo	Tipo	Descrição
task	string	O discriminador que seleciona esta variante, `update_user_flags`
user_ids	array[snowflake]	Os usuários a serem atualizados (máx. 1000 entradas)
add_flags?¹	array[string]	Valores de sinalizador de conta a serem adicionados (máx. 64, padrão vazio)
remove_flags?¹	array[string]	Valores de sinalizador de conta a serem removidos (máx. 64, padrão vazio)

¹ Cada entrada é um valor de sinalizador de 64 bits escrito como uma string decimal sem sinal, como 1024. A validação do corpo rejeita um nome simbólico. As adições são aplicadas antes das remoções, então um valor nomeado em ambas as matrizes acaba sendo limpo

Estrutura de atualização de sinalizadores de atividade suspeita

Campo	Tipo	Descrição
task	string	O discriminador que seleciona esta variante, `update_suspicious_activity_flags`
user_ids	array[snowflake]	Os usuários a serem atualizados (máx. 1000 entradas)
add_flags?¹ ²	array[string]	Nomes de sinalizador de atividade suspeita a serem adicionados (máx. 32, padrão vazio)
remove_flags?¹	array[string]	Nomes de sinalizador de atividade suspeita a serem removidos (máx. 32, padrão vazio)

¹ Cada entrada é o nome do sinalizador simbólico como REQUIRE_VERIFIED_PHONE. Uma entrada que não nomeia nenhum sinalizador conhecido é ignorada, e as adições são aplicadas antes das remoções

² Adicionar REQUIRE_VERIFIED_PHONE ou REQUIRE_REVERIFIED_PHONE também limpa o bit de telefone adiado 1 << 16, o que transforma um requisito de telefone adiado em um imediato

Estrutura de atualização de recursos de guilda

Campo	Tipo	Descrição
task	string	O discriminador que seleciona esta variante, `update_guild_features`
guild_ids	array[snowflake]	As guildas a serem atualizadas (máx. 1000 entradas)
add_features?¹	array[string]	Recursos de guilda a serem adicionados (máx. 100, padrão vazio)
remove_features?¹	array[string]	Recursos de guilda a serem removidos (máx. 100, padrão vazio)

¹ A validação do corpo aceita qualquer string, então um nome fora do registro é gravado no conjunto de recursos da guilda. As adições são aplicadas antes das remoções

Estrutura de adição de membros da guilda

Campo	Tipo	Descrição
task	string	O discriminador que seleciona esta variante, `add_guild_members`
guild_id	snowflake	A guilda que recebe os usuários
user_ids	array[snowflake]	Os usuários a serem adicionados como membros (máx. 1000 entradas)

Estrutura de agendamento de exclusão de usuário

Campo	Tipo	Descrição
task	string	O discriminador que seleciona esta variante, `schedule_user_deletion`
user_ids	array[snowflake]	Os usuários a serem agendados para exclusão (máx. 1000 entradas)
reason_code	integer	Motivo da exclusão registrado contra cada conta alvo
public_reason?	string	O motivo mostrado a cada titular da conta no aviso de exclusão (0-512 caracteres após a normalização)
days_until_deletion?¹	integer	O atraso antes da exclusão em dias inteiros (1-365, padrão 60)

¹ O Decoding Chat aumenta o valor para o mínimo específico do motivo, 14 dias para USER_REQUESTED e 60 dias para todos os outros códigos

Resposta

Status	Corpo	Condição
200	objeto criação de trabalho em lote	O trabalho em lote foi enfileirado
403	resposta de erro	`MISSING_ACL` sem a ACL selecionada pela `task`
500¹	resposta de erro	O trabalho não pôde ser enfileirado

¹ Uma fila cheia rejeita o trabalho e a solicitação retorna INTERNAL_SERVER_ERROR

Efeitos colaterais

O trabalho registra o Admin atuante e o motivo da auditoria. O enfileiramento registra uma entrada de auditoria de Admin com ação queue_bulk_job, tipo de alvo bulk_job, ID de alvo igual ao identificador do trabalho, e chaves de metadados task e entity_count. entity_count é o comprimento de guild_ids para update_guild_features e de user_ids para todas as outras tarefas. Uma entrada add_guild_members também possui guild_id. Falha ao criar o trabalho retorna 500 INTERNAL_SERVER_ERROR sem iniciar a operação ou registrar uma entrada.

As entidades são processadas na ordem enviada. Cancelar trabalho interrompe a execução entre entidades e define seu status como cancelled. As alterações concluídas permanecem em vigor. Uma entidade com falha ou desconhecida conta como falha sem interromper o restante do trabalho.

Toda tarefa atualiza seu progresso antes do início do trabalho e na conclusão. Toda tarefa, exceto schedule_user_deletion, também atualiza seu progresso após cada 25 entidades, e schedule_user_deletion atualiza seu progresso após cada 10 contas. A progress_message final tem as contagens bem-sucedidas e com falha.

Toda tarefa grava uma entrada de resumo da auditoria do Admin quando termina, com a ação bulk_update_user_flags, bulk_update_suspicious_activity_flags, bulk_update_guild_features, bulk_add_guild_members, bulk_schedule_deletion, bulk_ban_file_shas, ou bulk_delete_user_messages. O resumo tem o motivo da auditoria, a contagem de entidades, os parâmetros específicos da operação, o identificador do trabalho e as contagens processadas, bem-sucedidas e com falha. Seu target_type é bulk_job e seu target_id é o identificador do trabalho, exceto para add_guild_members, que tem como alvo a guilda. Um trabalho com falha não grava nenhuma entrada de resumo. Um trabalho cancelado grava uma, marcada como cancelled, cobrindo as entidades processadas antes de parar.

update_user_flags grava uma entrada update_flags para cada conta e despacha User Update para as sessões da conta. Uma alteração em um sinalizador visível publicamente também despacha Guild Member Update para todas as guildas em que a conta está.

update_suspicious_activity_flags reescreve os requisitos de verificação de cada conta e despacha User Update. Nenhum Guild Member Update é seguido. A tarefa grava uma entrada update_suspicious_activity_flags para cada conta, com o motivo da auditoria, e registra um resultado de risco quando os requisitos se tornam não vazios. Um nome de sinalizador desconhecido falha o trabalho antes que qualquer conta seja alterada.

update_guild_features grava uma entrada update_features para cada guilda, despacha Guild Update e reindexa a guilda para pesquisa. O Decoding Chat reconcilia uma guilda que já possui um registro de aplicativo de descoberta com o novo conjunto de recursos, de modo que o ganho de DISCOVERABLE aprova o registro e a perda dele marca o registro como removido. Uma guilda sem registro de descoberta é deixada em paz.

add_guild_members contorna a verificação de banimento e a verificação de telefone adiada que uma entrada normal executa para uma conta sem telefone verificado. A tarefa suprime a mensagem do sistema de entrada, registra a fonte de entrada como uma adição forçada do Admin e despacha Guild Member Add para a guilda e Guild Create para as sessões da conta adicionada. A tarefa ainda impõe o limite de guildas por conta e o limite de membros da guilda, de modo que uma conta em qualquer teto seja contada como falha. Uma conta que já é um membro é deixada inalterada e contada como bem-sucedida, sem segunda associação e sem Dispatch. Adicionar uma conta de bot também registra uma entrada de log de auditoria de guilda BOT_ADD atribuída ao Admin atuante.

delete_user_messages exclui todas as mensagens que cada conta escreveu, em todos os canais. Ele grava uma entrada delete_all_user_messages para cada conta, com o motivo da auditoria, a conta e a contagem de mensagens excluídas, e relata o progresso após cada conta.

schedule_user_deletion marca cada conta como excluída. A tarefa executa as mesmas etapas que Agendar exclusão de usuário para uma conta. Ele armazena o código do motivo, o motivo público e o motivo da auditoria na conta, reprograma sua exclusão pendente, encerra suas sessões, cancela e reembolsa sua assinatura do Stripe quando houver uma em arquivo, despacha User Update, grava uma entrada schedule_deletion para cada conta com o motivo da auditoria e o código do motivo e envia um e-mail ao titular da conta quando um endereço estiver arquivado. Um e-mail com falha é registrado e não falha a entidade. Quando o motivo não for USER_REQUESTED, a tarefa também banirá os identificadores da conta e resolverá as denúncias pendentes contra ela.

Limite de taxa

20 solicitações por minuto para cada usuário autenticado, no bucket admin:bulk:operation.