Atualização em lote
A atualização em lote aplica os mesmos valores a todos os registros da lista:Modelos aceitos
Omodel_name do caminho aceita dois valores:
Qualquer outro valor devolve HTTP 422, com
message: "validation_errors" e o motivo em validation.model:
- Modelo ainda não suportado (por exemplo,
contact):messages.model_not_supported_yet. - Modelo que não existe:
Model was not found.
project ou answer_pool no caminho. Para alterar vários registros de outro tipo, faça uma requisição por registro.
Corpo da requisição
O corpo é um objeto com a lista deids e, no mesmo nível, os campos a aplicar em todos eles. Este exemplo marca três projetos como em andamento, com impacto 8, e troca uma etiqueta por outra:
Lista dos identificadores a atualizar. Não pode estar vazia e não aceita valores repetidos. Não há teto de quantidade.
Campos de project
Os campos simples são aplicados diretamente no projeto:
As relações abaixo usam o formato
{ "to_add": [...], "to_rem": [...] }. Envie as duas chaves, mesmo que uma delas vá vazia:
As demais relações têm formato próprio:
Campos de answer_pool
Com answer_pool, o lote grava as mesmas respostas de formulário em todos os registros da lista. Este exemplo responde o campo 30 do formulário do objeto projeto em dois projetos:
As respostas a gravar, no mesmo formato usado na gravação individual: cada item tem o
id do campo e a answer.Endereço do formulário, o pivot. Exige
pivot_class, form_id e father_class. A API usa cada item de ids como o registro alvo, então você não envia father_id.ids continuam sendo ids de projeto, e o target leva o id da etapa ou do funil:
Resposta
A resposta tem HTTP 200 mesmo quando alguns itens falham. O resultado do lote está emresult:
Um objeto por falha, com
id e error. Quando a falha é de permissão, o objeto também traz permission, com a permissão que faltou.ids que não aparecem em fails.
Falha no meio de um item
A API processa item a item, mas não desfaz as alterações de um item que falhou. Se um projeto falhar depois de receber parte das alterações, a parte já aplicada permanece. Por exemplo, o campo simples é gravado e a relação seguinte falha.Concorrência
A API processa um lote por usuário de cada vez. Se outro lote do mesmo usuário estiver em andamento, a requisição responde com HTTP 409:Movimentação em lote entre etapas
A movimentação em lote move vários projetos para a mesma etapa de funil:Corpo da requisição
Este exemplo move dois projetos para a etapa 42 e os desvincula das outras etapas do mesmo funil:Tudo ou nada
Este endpoint para no primeiro erro, e nenhuma movimentação do lote é confirmada, nem a dos projetos processados antes da falha. A resposta de erro segue o formato padrão e informa o motivo, com o detalhe da restrição ou do requisito que barrou a movimentação. As regras por trás desses erros estão em Restrições de etapa e Requisitos de etapa.
O erro descreve o motivo, mas não diz qual projeto falhou. Para descobrir qual projeto barrou o lote, mova um projeto de cada vez com
POST /api/management/funnel-steps/{funnel_step_id}/projects. O projeto que reproduzir o erro é o responsável.
Concorrência na movimentação
A movimentação em lote usa a mesma trava da atualização em lote: um lote por usuário de cada vez, com HTTP 409 ebulk_operation_in_progress quando já existe outro em andamento. Um lote de atualização em curso também bloqueia um lote de movimentação do mesmo usuário, e vice-versa.
Boas práticas
Estes cuidados evitam as falhas mais comuns nos lotes:- Escolha o endpoint pelo comportamento de erro. Se o lote inteiro precisa dar certo ou falhar junto, use a movimentação entre etapas. Se você quer aplicar o que for possível e tratar o resto depois, use a atualização em lote.
- Confira o nome dos campos. Na atualização em lote, um campo escrito errado é ignorado sem aviso. Valide o corpo antes de rodar sobre muitos registros.
- Leia sempre o
result. UmsuccessCountigual ao total garante só que nenhum item deu erro, e não que os campos certos foram aplicados. - Envie um lote de cada vez. Com o mesmo usuário, o segundo lote recebe 409. Organize uma fila do seu lado.