Excluir dados em massa

O recurso de exclusão em massa no Microsoft Dataverse ajuda você a manter a qualidade dos dados e gerenciar o consumo do armazenamento do sistema excluindo dados de que você não precisa mais. Por exemplo, é possível excluir os seguintes dados em massa:

• Dados obsoletos
• Dados que não são mais relevantes para a empresa
• Dados de exemplo ou teste desnecessários
• Dados importados incorretamente de outros sistemas

Você pode executar as seguintes operações:

• Excluir dados em várias tabelas.
• Excluir registros em uma tabela específica.
• Receber notificações por email quando uma exclusão em massa for concluída.
• Excluir dados periodicamente.
• Agendar o horário de início de uma exclusão em massa recorrente.
• Recupere informações sobre falhas que ocorreram durante uma exclusão em massa.

Para excluir várias linhas em tabelas elásticas, você também pode usar a DeleteMultiple mensagem. DeleteMultiple exclui registros em um único elástico imediatamente, em vez de usar um trabalho de exclusão em massa.

Executar exclusão em massa

Para excluir dados em massa, use a mensagem BulkDelete para enviar uma tarefa de exclusão em massa. Usando o SDK, use a classe BulkDeleteRequest. Ao usar a Web API, use a ação BulkDelete. Especifique as expressões de consulta que descrevem os registros a serem excluídos na QuerySet propriedade de sua solicitação.

Um trabalho de exclusão em massa é representado por um registro na Bulk Delete Operation tabela (BulkDeleteOperation). Um registro de operação de exclusão em massa inclui as seguintes informações:

• O número de registros que a tarefa excluiu
• O número de registros que o trabalho não pôde excluir
• Se o trabalho foi definido como recorrente
• A hora de início do trabalho

O trabalho de exclusão em massa é executado de forma assíncrona sem bloquear outras atividades. Ele exclui apenas os registros que foram criados antes do trabalho começar a ser executado. O trabalho exclui os registros especificados com base em regras de cascata relativas ao comportamento em cascata da relação de tabela.

Se um trabalho de exclusão em massa falhar ou terminar prematuramente, a operação não reverterá nenhum registro excluído. Os dados de registro permanecem excluídos. Um registro de falhas é armazenado na Bulk Delete Failure tabela (BulkDeleteFailure). Você pode recuperar informações da tabela sobre o erro que causou a falha.

Para executar um trabalho de exclusão em massa, você deve ter BulkDelete e Delete privilégios nos tipos de tabela que está excluindo. Você também deve ter permissões de leitura nos registros de tabela especificados na QuerySet propriedade. Um administrador do sistema tem as permissões necessárias por padrão. Conceda-os a outros usuários.

Você pode executar uma exclusão em massa em todas as tabelas que dão suporte à Delete mensagem.

Se a ação de exclusão em um tipo de tabela específico disparar um plug-in ou um fluxo de trabalho (processo), o trabalho de exclusão em massa disparará o plug-in ou o fluxo de trabalho sempre que ele excluir um registro de tabela desse tipo.

Controlar o processamento de exclusão em massa

O Options parâmetro na BulkDelete ou solicitação de mensagem permite controlar como o trabalho de exclusão em massa processa linhas de tabela (registros). Você pode usar o parâmetro para:

• Desabilite a lixeira para registros excluídos em massa. Desabilitar a lixeira melhora o desempenho ignorando a sobrecarga de armazenar registros excluídos para recuperação.
• Habilite o modo de exclusão rápida da área restrita para ignorar o pipeline do SDK padrão (plug-ins, fluxos de trabalho, lixeira). A exclusão rápida alcança um maior desempenho na exclusão.

Warning

Não execute os exemplos mostrados neste artigo conforme escrito. Modifique o código de exemplo conforme apropriado para seu ambiente de desenvolvimento. Alguns desses exemplos excluem todas as contas, o que não é algo que talvez você queira fazer.

Usar o parâmetro Opções

O Options parâmetro aceita um BulkDeleteOptions objeto com as propriedades a seguir.

Property	Tipo	Default	Description
CanRecoverDeletedRecords	booleano	nulo (lixeira habilitada)	Quando definido como false, os registros excluídos pelo trabalho de exclusão em massa são permanentemente removidos e não podem ser recuperados da lixeira.
RunJobForSandbox	booleano	nulo (pipeline padrão)	Quando definido como true, o trabalho de exclusão em massa usa o modo de exclusão de área restrita de alto desempenho, ignorando plug-ins, fluxos de trabalho e a lixeira.

Importante

O pacote NuGet do SDK do Dataverse para .NET que contém a classe BulkDeleteRequest ainda não foi atualizado para incluir a nova propriedade Options. Até que esse pacote seja atualizado, você poderá acessar a nova propriedade usando uma classe OrganizationRequest genérica e especificando o nome da solicitação "bulkdelete" com um parâmetro de "opções".

Exemplo: Parâmetro Opções

Os exemplos a seguir demonstram como usar o Options parâmetro com a ação BulkDelete ou a solicitação de mensagem.

Web API

Use a propriedade Options no corpo da solicitação para a ação BulkDelete. O Options parâmetro é um tipo complexo BulkDeleteOptions.

Solicitação:

POST [Organization Uri]/api/data/v9.2/BulkDelete HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json

{
    "QuerySet": [
        {
            "@odata.type": "Microsoft.Dynamics.CRM.QueryExpression",
            "EntityName": "account",
            "ColumnSet": {
                "AllColumns": true
            },
            "Distinct": false
        }
    ],
    "JobName": "Delete all accounts",
    "SendEmailNotification": false,
    "ToRecipients": [],
    "CCRecipients": [],
    "RecurrencePattern": "",
    "StartDateTime": "2026-03-13T06:30:00Z",
    "Options": {
        "CanRecoverDeletedRecords": true,
        "RunJobForSandbox": false
    }
}

Resposta:

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.BulkDeleteResponse",
    "JobId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Valores dos parâmetros de opções

Cenário	PodeRecuperarRegistrosExcluídos	RunJobForSandbox	Efeito
Padrão (exclusão padrão)	verdadeiro ou omitido	falso ou ausente	Os registros passam pelo pipeline padrão. Registros excluídos são armazenados na lixeira do sistema se esta funcionalidade estiver habilitada.
Ignorar lixeira	falso	falso ou omitido	Os registros passam pelo fluxo de dados padrão. A lixeira é ignorada para este trabalho.
Exclusão rápida do sandbox	falso	verdadeiro	Omite o pipeline e a lixeira do SDK. Largura de banda máxima.

SDK para .NET

Use a BulkDeleteRequest class e defina o Options parâmetro na coleção de solicitações Parameters. O valor é um objeto BulkDeleteOptions do namespace Microsoft.Xrm.Sdk.

using Microsoft.Crm.Sdk.Messages;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Query;

static Guid BulkDeleteWithOptions(IOrganizationService service)
{
    var request = new BulkDeleteRequest
    {
        JobName = "Delete all accounts",
        QuerySet = new QueryExpression[]
        {
            new QueryExpression
            {
                EntityName = "account",
                ColumnSet = new ColumnSet(true)
            }
        },
        StartDateTime = DateTime.UtcNow,
        RecurrencePattern = string.Empty,
        SendEmailNotification = false,
        ToRecipients = Array.Empty<Guid>(),
        CCRecipients = Array.Empty<Guid>()
    };

    // Set bulk delete options
    request["Options"] = new BulkDeleteOptions
    {
        CanRecoverDeletedRecords = true,
        RunJobForSandbox = false
    };

    BulkDeleteResponse response =
        (BulkDeleteResponse)service.Execute(request);
    return response.JobId;
}

A classe BulkDeleteOptions está disponível no namespace Microsoft.Xrm.Sdk. Verifique se você está usando a versão recente dos assemblies do SDK.

Controlar o comportamento da lixeira

Por padrão, quando a lixeira está habilitada para seu ambiente, todos os registros excluídos por um trabalho de exclusão em massa são armazenados na lixeira antes da exclusão. A lixeira permite que os administradores recuperem registros excluídos acidentalmente, mas adiciona uma sobrecarga significativa de E/S para cada registro excluído. Para desabilitar a lixeira de um trabalho de exclusão em massa, defina CanRecoverDeletedRecords como false no parâmetro Options. Essa configuração pode dobrar aproximadamente a taxa de transferência de exclusão ao eliminar a sobrecarga de:

• Criando registros "DeletedItemReference"
• Copiando dados de registro para tabelas de armazenamento de lixeira
• Atualizando os blobs de restauração de dados para cada registro excluído

Warning

Quando CanRecoverDeletedRecords é definido como false, os registros excluídos são permanentemente removidos e não podem ser recuperados da lixeira. Essa ação é irreversível. Verifique se você verificou os critérios de consulta e tem backups apropriados antes de executar um trabalho de exclusão em massa com essa opção. Essa configuração afeta apenas o trabalho de exclusão em massa atual; ele não altera a configuração da lixeira no nível do ambiente.

Exemplo: Desabilitar a lixeira para exclusão mais rápida

Exclua permanentemente os registros sem armazená-los na lixeira.

Web API

POST [Organization Uri]/api/data/v9.2/BulkDelete HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json

{
    "QuerySet": [
        {
            "@odata.type": "Microsoft.Dynamics.CRM.QueryExpression",
            "EntityName": "account",
            "ColumnSet": {
                "AllColumns": true
            },
            "Distinct": false
        }
    ],
    "JobName": "Delete accounts - skip recycle bin",
    "SendEmailNotification": false,
    "ToRecipients": [],
    "CCRecipients": [],
    "RecurrencePattern": "",
    "StartDateTime": "2026-03-13T06:30:00Z",
    "Options": {
        "CanRecoverDeletedRecords": false
    }
}

SDK para .NET

static Guid BulkDeleteSkipRecycleBin(IOrganizationService service)
{
    var request = new BulkDeleteRequest
    {
        JobName = "Delete accounts - skip recycle bin",
        QuerySet = new QueryExpression[]
        {
            new QueryExpression
            {
                EntityName = "account",
                ColumnSet = new ColumnSet(true)
            }
        },
        StartDateTime = DateTime.UtcNow,
        RecurrencePattern = string.Empty,
        SendEmailNotification = false,
        ToRecipients = Array.Empty<Guid>(),
        CCRecipients = Array.Empty<Guid>()
    };

    // Disable recycle bin for this job
    request["Options"] = new BulkDeleteOptions
    {
        CanRecoverDeletedRecords = false
    };

    BulkDeleteResponse response =
        (BulkDeleteResponse)service.Execute(request);
    return response.JobId;
}

Exclusão rápida da área restrita

Para cenários que exigem taxa de transferência máxima de exclusão, você pode habilitar o modo de exclusão rápida do sandbox definindo RunJobForSandbox como true. Nesse modo, o trabalho de exclusão em massa ignora totalmente o pipeline do SDK padrão e usa a exclusão direta do mecanismo em cascata, alcançando uma taxa de transferência mais alta.

Quando a exclusão rápida do sandbox está ativada, o seguinte é ignorado:

• Execução de plug-ins pré-operação e pós-operação
• Gatilhos de fluxo de trabalho síncronos e assíncronos
• Armazenamento de lixeiras (os registros são excluídos permanentemente)
• Lógica de negócios personalizada registrada na mensagem de exclusão

Os seguintes são preservados ao executar a exclusão rápida:

• Regras de exclusão em cascata com base na configuração de relação de tabela
• Integridade referencial (relações de chave estrangeira)
• Verificações de privilégios de segurança
• Sincronizar o controle de alterações para replicação downstream

Importante

O modo de exclusão rápida de sandbox bypassa todo o pipeline de plug-in do SDK. Todos os plug-ins personalizados, fluxos de trabalho ou lógica de negócios registrados na mensagem Delete NÃO são executados para registros excluídos nesse modo. Incluídos estão plug-ins de auditoria, plug-ins de integração e qualquer lógica de validação personalizada. Além disso, os registros excluídos no modo de área restrita não podem ser recuperados da lixeira. Use essa opção somente quando tiver certeza de que nenhuma lógica comercial crítica depende da execução de plug-in durante a exclusão e que a exclusão permanente e irrecuperável é aceitável.

Exemplo: exclusão rápida do sandbox

Saiba como usar o modo de exclusão em sandbox de alto desempenho para a máxima taxa de transferência (throughput).

Web API

POST [Organization Uri]/api/data/v9.2/BulkDelete HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json

{
    "QuerySet": [
        {
            "@odata.type": "Microsoft.Dynamics.CRM.QueryExpression",
            "EntityName": "account",
            "ColumnSet": {
                "AllColumns": true
            },
            "Distinct": false
        }
    ],
    "JobName": "Delete accounts - sandbox fast delete",
    "SendEmailNotification": false,
    "ToRecipients": [],
    "CCRecipients": [],
    "RecurrencePattern": "",
    "StartDateTime": "2026-03-13T06:30:00Z",
    "Options": {
        "CanRecoverDeletedRecords": false,
        "RunJobForSandbox": true
    }
}

SDK para .NET

static Guid BulkDeleteSandboxFastDelete(IOrganizationService service)
{
    var request = new BulkDeleteRequest
    {
        JobName = "Delete accounts - sandbox fast delete",
        QuerySet = new QueryExpression[]
        {
            new QueryExpression
            {
                EntityName = "account",
                ColumnSet = new ColumnSet(true)
            }
        },
        StartDateTime = DateTime.UtcNow,
        RecurrencePattern = string.Empty,
        SendEmailNotification = false,
        ToRecipients = Array.Empty<Guid>(),
        CCRecipients = Array.Empty<Guid>()
    };

    // Enable sandbox fast delete (bypasses plug-ins & recycle bin)
    request["Options"] = new BulkDeleteOptions
    {
        CanRecoverDeletedRecords = false,
        RunJobForSandbox = true
    };

    BulkDeleteResponse response =
        (BulkDeleteResponse)service.Execute(request);
    return response.JobId;
}

Dados retidos a longo prazo

A exclusão em massa também está disponível para dados retidos de longo prazo. Execute uma exclusão em massa como faria normalmente, mas defina o campo da DataSource consulta como retido.

SDK para .NET

Usando o SDK, você pode usar ou QueryExpression ou a classe FetchXmlToQueryExpressionRequest com IOrganizationService.Execute para converter FetchXml em um QueryExpression.

QueryExpression

Use a propriedade QueryExpression.DataSource para indicar que a consulta se destina apenas a linhas retidas. Defina o valor como retained para apagar dados retidos em massa.

static Guid BulkDeleteRetainedAccountsExample(IOrganizationService service)
{
    var request = new BulkDeleteRequest
    {
        JobName = "Bulk Delete Retained Accounts"
    };

    // Create query and add additional filters as needed
    QueryExpression query = new QueryExpression
    {
        EntityName = "account",
        DataSource = "retained"
    };

    request.QuerySet = new QueryExpression[]{query};

    request.StartDateTime = DateTime.Now;
    request.RecurrencePattern = string.Empty;
    request.SendEmailNotification = false;
    request.ToRecipients = Array.Empty<Guid>();
    request.CCRecipients = Array.Empty<Guid>();

    BulkDeleteResponse response = (BulkDeleteResponse)service.Execute(request);
    return response.JobId;
}

FetchXML

Adicione o datasource='retained' atributo ao fetch elemento para indicar que a consulta é somente para linhas retidas.

static Guid BulkDeleteRetainedAccountsFetchXmlExample(IOrganizationService service) {
            
    var convertRequest = new FetchXmlToQueryExpressionRequest
    {
        FetchXml = @"
        <fetch datasource='retained'>
            <entity name='account'>
        </entity>
        </fetch>"
    };

    FetchXmlToQueryExpressionResponse convertResponse = (FetchXmlToQueryExpressionResponse)service.Execute(convertRequest);

    var request = new BulkDeleteRequest
    { JobName = "Bulk Delete Retained Accounts" };

    request.QuerySet = new QueryExpression[]{convertResponse.Query};

    request.StartDateTime = DateTime.Now;
    request.RecurrencePattern = string.Empty;
    request.SendEmailNotification = false;
    request.ToRecipients = Array.Empty<Guid>();
    request.CCRecipients = Array.Empty<Guid>();
           
    BulkDeleteResponse response = (BulkDeleteResponse)service.Execute(request);
    return response.JobId;
}

Web API

Defina a QueryExpressionDataSource propriedade como retained em uma ação BulkDelete da API Web para indicar que a consulta é somente para linhas retidas.

Solicitação:

POST [Organization Uri]/api/data/v9.2/BulkDelete HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json

{
    "QuerySet": 
    [
        {
            "EntityName": "contact",
            "DataSource": "retained",
            "Criteria":
            {
                "FilterOperator": "And",
                "Conditions": 
                [
                    {
                        "AttributeName": "firstname",
                        "Operator": "Equal",
                        "Values" : [{"Value":"Bob","Type":"System.String"}]
                    }
                ]
            }
        }
    ],
    "JobName": "Bulk Delete Retained Contacts",
    "SendEmailNotification": false,
    "RecurrencePattern": "",
    "StartDateTime": "2023-03-07T05:00:00Z",
    "ToRecipients": [],
    "CCRecipients": []
}

Resposta:

HTTP/1.1 200 OK
{
    "@odata.context": "[Organization Uri]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.BulkDeleteResponse",
    "JobId": "3093d67f-21f0-ed11-8b48-6045bdd92a32"
}

Saiba mais sobre ações de API Web.

Samples

Examine os seguintes exemplos do SDK para .NET para o recurso de exclusão em massa:

• Exemplo: excluir registros exportados em massa
• Exemplo: excluir em massa registros que correspondem a critérios comuns

Consulte também

• Retenção de dados de longo prazo
• Referência da Ação BulkDelete
• Excluir dados em massa
• Restaurar registros excluídos
• Use ações da API Web
• Referência da tabela BulkDeleteOperation