Restaurar registros excluídos com código

[Este artigo é uma documentação de pré-lançamento e está sujeito a alterações.]

Às vezes, as pessoas excluem registros que não deveriam. Os administradores podem habilitar a manutenção de registros excluídos para que possam restaurar registros excluídos dentro de um período de tempo especificado. Saiba como os administradores podem restaurar registros excluídos.

Quando a manutenção de registros excluídos está habilitada, os desenvolvedores podem usar a mensagem Restore para restaurar o registro excluído antes do período de tempo especificado. O período pode ser de até 30 dias.

Recuperar registros excluídos que podem ser restaurados

Para recuperar registros excluídos que podem ser restaurados, defina a fonte de dados da consulta como 'bin'. Os exemplos a seguir retornam até três registros de conta excluídos.

SDK para .NET
Web API

Ao usar o SDK, você pode recuperar dados usando FetchXml ou QueryExpression.

Ao recuperar dados usando FetchXml, defina o atributo do elemento fetchdatasource como 'bin' ao recuperar registros.

static EntityCollection GetDeletedAccountRecordsFetchXml(IOrganizationService service) {

   string queryString = @"<fetch top='3' datasource='bin'>
                     <entity name='account'>
                        <attribute name='name' />
                     </entity>
                     </fetch>";
   
   FetchExpression query = new(queryString);

   return service.RetrieveMultiple(query);
}

Ao recuperar dados usando QueryExpression, defina a propriedade QueryExpression.DataSource como "bin" ao recuperar registros.

static EntityCollection GetDeletedAccountRecordsQueryExpression(IOrganizationService service) {

   QueryExpression query = new("account") { 
         ColumnSet = new ColumnSet("name"),
         DataSource = "bin",
         TopCount = 3
   };

   return service.RetrieveMultiple(query);
}

Usando a API Web, você pode recuperar registros com sintaxe FetchXml ou OData.

Note

Atualmente, usando a API Web, você só pode recuperar registros excluídos usando FetchXml.

Ao recuperar dados usando FetchXml, defina o atributo do elemento fetchdatasource como 'bin' ao recuperar registros.

Essa Get-DeletedAccountRecords função do PowerShell retorna até três registros de conta excluídos.

Este exemplo de API Web e outros neste artigo dependem das variáveis $environmentUrl e $baseHeaders conforme descrito em Quick Start Web API com o PowerShell e Visual Studio Code.

function Get-DeletedAccountRecords{

   $query = @()
   $query += "<fetch top='3' datasource='bin'>"
   $query += "<entity name='account'>"
   $query += "<attribute name='name' />"
   $query += "</entity>"
   $query += "</fetch>"

   $uri = $environmentUrl
   $uri += 'accounts'
   $uri += '?fetchXml=' + [uri]::EscapeUriString($query -join '')

   $RetrieveMultipleRequest = @{
      Uri     = $uri
      Method  = 'Get'
      Headers = $baseHeaders
   }
   Invoke-RestMethod @RetrieveMultipleRequest

}

Restaurar um registro excluído

Use a mensagem Restore para restaurar um registro excluído. O Target parâmetro não é uma referência a um registro excluído. É um registro completo para que você possa definir valores de coluna enquanto restaura o registro. Todos os valores de coluna originais são restaurados, a menos que você os substitua definindo valores durante a operação Restore.

Note

Neste momento, você só pode restaurar registros usando o valor da chave primária. Você não pode usar uma chave alternativa para restaurar um registro.

A forma como você restaura um registro excluído depende se você está usando o SDK para .NET ou API Web.

SDK para .NET
Web API

Como você restaura um registro usando o SDK para .NET depende de você estar gerando tipos de vinculação antecipada usando pac modelbuilder ou se está usando o estilo de vinculação tardia.

Saiba mais sobre programação com limite tardio e com limite inicial usando o SDK para .NET

Exemplo de associação antecipada

O método estático RestoreAccountRecordEarlyBound usa as classes RestoreRequest<T> e Account geradas usando o pac modelbuilder.

/// <summary>
/// Restores an account record
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance</param>
/// <param name="accountId">The ID of the deleted account record.</param>
/// <param name="originalName">The original name value for the account record.</param>
/// <returns>The ID of the restored account</returns>
static Guid RestoreAccountRecordEarlyBound(
    IOrganizationService service, 
    Guid accountId,
    string originalName)
{
    Account accountToRestore = new()
    {
        Id = accountId,
        // Appending '(Restored)' to the original name
        // to demonstrate overwriting a value.
        Name = originalName + " (Restored)"
    };

    RestoreRequest<Account> request = new()
    {
        Target = accountToRestore
    };

    var response = (RestoreResponse)service.Execute(request);
    return response.id;
}

Exemplo de vinculação tardia

O método estático RestoreAccountRecordLateBound usa a classe OrganizationRequest para invocar a Restore mensagem, definindo o Target parâmetro.

/// <summary>
/// Restores an account record
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance</param>
/// <param name="accountId">The ID of the deleted account record.</param>
/// <param name="originalName">The original name value for the account record.</param>
/// <returns>The ID of the restored account</returns>
static Guid RestoreAccountRecordLateBound(
   IOrganizationService service,
   Guid accountId,
   string originalName)
{
   Entity accountToRestore = new("account", accountId)
   {
         Attributes = {
            // Appending '(Restored)' to the original name
            // to demonstrate overwriting a value.
            {"name", originalName + " (Restored)"}
         }
   };

   OrganizationRequest request = new("Restore")
   {
         Parameters = {
            { "Target", accountToRestore }
         }
   };

   OrganizationResponse response = service.Execute(request);

   return (Guid)response.Results["id"];
}

Use mensagens com o SDK para .NET

Utilize a ação Restaurar para restaurar registros excluídos. Esta operação retorna um tipo complexo RestoreResponse que tem uma id propriedade definida como a ID do registro restaurado.

Recuperar qualquer tipo de registro sem sobrescrever os valores das colunas

A Restore-AnyRecord função do PowerShell mostra como restaurar qualquer tipo de registro fazendo referência a ele usando a URL completa para o registro e a @odata.id anotação. Passe uma URL relativa como contacts(0ad63f65-990d-ef11-9f89-6045bdece8bb) para o relativeUri parâmetro dessa função. No entanto, com essa abordagem, você não pode substituir nenhum valor do registro.

function Restore-AnyRecord{
   param(
      [Parameter(Mandatory)]
      [uri]$relativeUri
   )

   $uri = $environmentUrl + 'api/data/v9.2/'
   $uri += 'Restore'
   
   $body = @{
      'Target' = @{
         '@odata.id' = $environmentUrl + 'api/data/v9.2/' + $relativeUri
      }
   }

   $postHeaders = $baseHeaders.Clone()
   $postHeaders.Add('Content-Type', 'application/json')

   $RestoreRequest = @{
      Uri     = $uri
      Method  = 'Post'
      Headers = $postHeaders
      Body    = (ConvertTo-Json $body) 
   }
  
  $id = Invoke-RestMethod @RestoreRequest | Select-Object -ExpandProperty id

  return $id
}

Restaurar um registro e sobrescrever valores de coluna

A Restore-AccountRecord função do PowerShell mostra como restaurar um registro de conta e substituir um valor. Há três requisitos:

Especifique o parâmetro de tipo de tabela utilizando o nome totalmente qualificado do tipo de entidade com o @odata.type. Essa anotação informa ao OData que tipo de registro é.
Para especificar o registro, inclua o valor da chave primária, nesse caso accountid .
Especifique as propriedades que você deseja substituir, nesse caso, a name propriedade.

function Restore-AccountRecord {
   param(
      [Parameter(Mandatory)]
      [guid]$recordId,
      [Parameter(Mandatory)]
      [string]$originalName
   )
   
   $uri = $environmentUrl
   $uri += 'Restore'
   
   $body = @{
      'Target' = @{
         '@odata.type' = 'Microsoft.Dynamics.CRM.account'
         # Appending '(Restored)' to the original name
         # to demonstrate overwriting a value.
         'name'       = ($originalName + ' (Restored)')
         'accountid'  = $recordId.Guid
      }
   }

   $postHeaders = $baseHeaders.Clone()
   $postHeaders.Add('Content-Type', 'application/json')

   $RestoreRequest = @{
      Uri     = $uri
      Method  = 'Post'
      Headers = $postHeaders
      Body    = (ConvertTo-Json $body) 
   }
  
  $id = Invoke-RestMethod @RestoreRequest | Select-Object -ExpandProperty id

  return $id
}

Práticas recomendadas ao restaurar registros

Evite os seguintes problemas ao restaurar registros:

Restaurar registros relacionados antes de restaurar o registro primário
Não especifique valores de chave primária ao criar registros
Registros com valores de chave alternativos correspondentes bloqueiam a restauração
Os registros que usam opções de opção removidas não são restaurados
Violação de chave primária durante a exclusão

Se alguns registros relacionados fizerem referência aos registros que a relação em cascata removeu, a operação de restauração falhará. Para evitar esse problema, sempre restaure os registros relacionados que a exclusão de registro atual não removeu antes de tentar restaurar o registro primário.

Nome: RefCannotBeRestoredRecycleBinNotFound
Código: 0x80049959
Número: -2147182247
Mensagem: Entity with id '<Guid Value>' and logical name '<Entity.LogicalName>' does not exist. We cannot restore the reference '<Referred Primary Key Name>' that must be restored as part of this Restore call. ValueToBeRestored: <Guid Value>, ReferencedEntityName: <Referenced Entity Name>, AttributeName: <Referred Attribute Name>

Não especifique valores de chave primária ao criar registros

Sempre permita que o Dataverse defina a chave primária ao criar um registro. Se você criar um novo registro que tenha o mesmo valor de chave primária que um registro excluído, não será possível restaurar o registro excluído. Se você quiser restaurar o registro excluído, exclua o novo registro primeiro.

Nome: DuplicateExceptionRestoreRecycleBin
Código: 0x80044a02
Número: -2147182279
Mensagem: Please delete the existing conflicting record '<Entity Platform Name>' with primary key '<Primary Key Name>' and primary key value '<Primary Key Value>' before attempting restore.

Registros com valores de chave alternativos correspondentes bloqueiam a restauração

Se você criar um registro que tenha os mesmos valores de coluna de chave alternativos que um registro excluído, não será possível restaurar o registro excluído. Se você quiser restaurar o registro excluído, exclua o novo registro primeiro.

Nome: DuplicateExceptionEntityKeyRestoreRecycleBin
Código: 0x80049929
Número: -2147182295
Mensagem: Duplicate entity key preventing restore of record '<Entity Platform Name>' with primary key '<Primary Key Name>' and primary key value '<Primary Key Value>'. See inner exception for entity key details.

Os registros que usam opções de opção removidas não são restaurados

Se você excluir uma opção de conjunto de opções e essa opção tiver sido usada em um registro excluído, não será possível restaurar o registro porque a opção agora é inválida. Antes de excluir uma opção de conjunto de opções, verifique se nenhum registro usa essa opção, incluindo registros excluídos.

Nome: PicklistValueOutOfRangeRecycleBin
Código: 0x80049949
Número: -2147182263
Mensagem: Picklist value not valid, please add the invalid value back to the picklist before restoring record

Violação de chave primária durante exclusão

Se o registro com a mesma chave primária já existir, nada acontecerá. Para impor que todos os itens excluídos sejam registrados, defina a configuração DoNotEnforcePrimaryKeyOrgSettingRecycleBin usando a ferramenta OrgDBOrgSettings para Microsoft Dynamics CRM.

Depois de habilitar essa configuração, você poderá receber o seguinte erro:

Nome: DuplicateExceptionRestoreRecycleBin
Código: 0x80049939
Número: -2147182279
Mensagem: A record that has the attribute values Deleted Object already exists on Delete.

Detectar quais tabelas estão habilitadas para manutenção de registros excluídos

Antes de habilitar esse recurso, a tabela RecycleBinConfig (Configuração de Manutenção de Registros Excluída) não tem linhas.

Com o tempo, a maioria das tabelas dará suporte à gestão de registros excluídos. Não há suporte para componentes de solução, tabelas virtuais e tabelas elásticas para manutenção de registros excluídos. Algumas tabelas que não estão habilitadas no momento podem ser habilitadas posteriormente (por exemplo, tabelas com mais de 600 colunas). Para obter uma lista de tabelas que não dão suporte a esse recurso, consulte Tabelas sem suporte no momento.

Você também pode desabilitar a manutenção de registros excluídos para o ambiente. Se o registro de exclusões não estiver habilitado para uma tabela, você não encontrará nenhum registro qualificado para ser restaurado. Você pode consultar o Dataverse para descobrir se a manutenção de registros excluída está habilitada para uma tabela ou não.

Tabelas que são habilitadas para manutenção de registros excluídos têm uma linha na tabela RecycleBinConfig em que statecode está ativa e isreadyforrecyclebin é verdadeira. A RecycleBinConfig tabela não contém o nome da tabela, mas refere-se a uma linha na tabela Entidade em que a logicalname coluna contém o LogicalName da tabela.

Use a seguinte consulta FetchXml para detectar quais tabelas excluíram a manutenção de registros habilitada:

<fetch>
  <entity name='recyclebinconfig'>
    <filter type='and'>
      <condition attribute='statecode'
        operator='eq'
        value='0' />
      <condition attribute='isreadyforrecyclebin'
        operator='eq'
        value='1' />
    </filter>
    <link-entity name='entity'
      from='entityid'
      to='extensionofrecordid'
      link-type='inner'
      alias='entity'>
      <attribute name='logicalname' />
      <order attribute='logicalname' />
    </link-entity>
  </entity>
</fetch>

Saiba como consultar dados usando FetchXml

Detectar quais tabelas não estão habilitadas para manutenção de registros excluídos

Para saber quais tabelas não estão habilitadas para manutenção de registros excluídos, use a seguinte consulta FetchXml que é o inverso daquela encontrada em Detectar quais tabelas estão habilitadas.

<fetch>
  <entity name='entity'>
    <attribute name='logicalname' />
    <filter type='or'>
      <condition entityname='recyclebin'
        attribute='extensionofrecordid'
        operator='null' />
      <condition entityname='recyclebin'
        attribute='statecode'
        operator='ne'
        value='0' />
      <condition entityname='recyclebin'
        attribute='isreadyforrecyclebin'
        operator='ne'
        value='1' />
    </filter>
    <order attribute='logicalname' />
    <link-entity name='recyclebinconfig'
      from='extensionofrecordid'
      to='entityid'
      link-type='outer'
      alias='recyclebin' />
  </entity>
</fetch>

Saiba como consultar dados usando FetchXml

Os resultados dessa consulta a partir de maio de 2024, quando esse recurso começou, estão em Tabelas que atualmente não oferecem suporte para manutenção de registros deletados.

Recuperar e definir a configuração de período de limpeza automática para a manutenção de registros excluídos

Defina o valor que determina quanto tempo os registros excluídos estão disponíveis para serem restaurados na coluna RecycleBinConfig.CleanupIntervalInDays em que o valor da coluna Name está organization. Todas as outras linhas da tabela RecycleBinConfig têm um valor de coluna CleanupIntervalInDays de -1. Esse valor indica que ele usa os mesmos valores definidos para a organization tabela.

Para especificar um valor diferente para outra tabela, defina o valor da coluna CleanupIntervalInDays onde o Name corresponde ao nome lógico da tabela. Esta coluna aceita valores de até 30. Não defina esse valor, a menos que você queira usar um valor diferente do padrão da organização.

SDK para .NET
Web API

Use esse método estático SetCleanupIntervalInDays para definir o valor da CleanupIntervalInDays coluna para uma tabela específica.

/// <summary>
/// Updates the CleanupIntervalInDays value for a specified table
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance</param>
/// <param name="entityId">The entityId of the table</param>
/// <param name="cleanupIntervalInDays">The new CleanupIntervalInDays value</param>
static void SetCleanupIntervalInDays(
    IOrganizationService service,
    Guid entityId,
    int cleanupIntervalInDays)
{

    QueryExpression query = new("recyclebinconfig")
    {
        ColumnSet = new ColumnSet("recyclebinconfigid"),
        Criteria = new FilterExpression(LogicalOperator.And)
        {
            Conditions = {
              {
                  new ConditionExpression(
                      attributeName: "extensionofrecordid",
                      conditionOperator: ConditionOperator.Equal,
                      value: entityId)
              }
          }
        }
    };

    EntityCollection records = service.RetrieveMultiple(query);

    if (records.Entities.Count.Equals(1))
    {
        Guid id = records.Entities[0].Id;

        Entity record = new(entityName: "recyclebinconfig", id: id)
        {
            Attributes = {
                { "cleanupintervalindays", cleanupIntervalInDays }
            }
        };

        service.Update(record);

    }
    else
    {
        throw new Exception($"Deleted record keeping configuration for table '{tableLogicalName}' not found.");
    }
}

Usar o SDK para .NET

Essa função Set-CleanupIntervalInDays do PowerShell recupera a linha recyclebinconfig que tem a entityId que corresponde ao parâmetro $tableEntityId. Em seguida, atualiza a propriedade da coluna cleanupintervalindays do registro para o valor do parâmetro $cleanupIntervalInDays.

Essa função depende das funções Get-Records e Update-Record descritas em Create table operations functions.

function Set-CleanupIntervalInDays{
      param(
         [Parameter(Mandatory)]
         [guid]$tableEntityId,
         [Parameter(Mandatory)]
         [int]$cleanupIntervalInDays
      )
      $records = (Get-Records `
         -setName 'recyclebinconfigs' `
         -query "?`$filter=_extensionofrecordid_value eq $($tableEntityId)").value
   
      if ($records.Count -eq 1) {
         $recyclebinconfigId = $records[0].recyclebinconfigid
   
         Update-Record `
               -setName 'recyclebinconfigs' `
               -id $recyclebinconfigId `
               -body @{
               'cleanupintervalindays' = $cleanupIntervalInDays
         }
      }
      else {
         Write-Host "Deleted record keeping configuration for table $tableEntityId not found."
      }
}

Desabilitar a manutenção de registros excluídos para o ambiente

Note

A maneira preferida de desabilitar a manutenção de registros excluídos para um ambiente é desativá-la no Centro de administração do Power Platform. O método descrito aqui pode ser alterado antes que o recurso fique disponível em geral.

Exclua a linha na tabela RecycleBinConfig onde o valor name é organization. Essa ação exclui todos os registros na tabela e desabilita a RecycleBinConfig manutenção de registros excluídos para o ambiente.

Importante

Não tente excluir outros registros individuais. É importante que o Dataverse gerencie essa ação.

Gerenciar a restauração de registros excluídos pela lógica de negócios personalizada

O Dataverse fornece um mecanismo para gerenciar ações desejadas para registros relacionados quando uma linha é excluída. Esses dados de configuração fazem parte da definição da relação. Quando um registro relacionado é excluído, você pode configurar quatro comportamentos possíveis:

Excluir Comportamento	Description
Todos em Cascata	Exclui os registros relacionados.
Remover Link	Define as colunas de pesquisa do registro excluído como nulas.
Nenhum em Cascata	Não aplica nenhuma alteração aos registros relacionados. (Somente interno)
Restrict	Impede a exclusão do registro para manter a integridade dos dados. O registro não pode ser excluído, a menos que não haja registros relacionados a essa relação.

Saiba mais sobre comportamentos de relação.

Quando você configura a relação para Cascade All, Remove Link ou Restrict, o Dataverse gerencia esses comportamentos e não há nada extra a ser feito.

Se você configurar uma relação para usar o comportamento Remover Link , mas a relação deve excluir o registro relacionado, talvez seja necessário ter uma lógica personalizada que aplique algum comportamento personalizado. Por exemplo, talvez você queira responder a esse comportamento de forma diferente e implementar seu próprio comportamento 'Cascade some' com base nas regras definidas. Por exemplo, você pode excluir registros inativos ou registros que não foram atualizados em um determinado período de tempo. Essa lógica geralmente é implementada usando um plug-in, mas também pode ser feita usando Power Automate com o conector Microsoft Dataverse: quando uma linha é adicionada, modificada ou excluída.

Se você tiver esse tipo de lógica de negócios personalizada, o Dataverse não saberá disso e não poderá 'desfazer' automaticamente sua lógica. No entanto, você pode registrar outro plug-in na Restore mensagem e assim reverter qualquer lógica personalizada existente. Ou você pode usar o Power Automate e o conector do Microsoft Dataverse: acionador quando uma ação é realizada.

Importante

Tenha cuidado com o contexto ao registrar as etapas de plug-in para a mensagem Restore. O registro que você está restaurando não está disponível no PreOperation estágio. Se você precisar criar registros relacionados, use o PostOperation estágio. Saiba mais sobre estágios de plugin.

Os InputParameters e OutputParameters da Restore mensagem são semelhantes à Create mensagem, portanto, os plug-ins gravados para serem registrados para a Create mensagem podem ser reutilados para a Restore mensagem com menos alterações.

Atualmente, não há suporte para tabelas para manutenção de registros excluídos

A consulta descrita em Detectar quais tabelas não estão habilitadas foi usada para gerar essa lista em agosto de 2024.

Consulte também

Restaurar registros de tabela excluídos do Microsoft Dataverse

Comentários

Esta página foi útil?

Last updated on 2026-05-01

Restaurar registros excluídos com código

Recuperar registros excluídos que podem ser restaurados

Restaurar um registro excluído

Exemplo de associação antecipada

Exemplo de vinculação tardia

Práticas recomendadas ao restaurar registros

Restaurar registros relacionados antes de restaurar o registro primário

Não especifique valores de chave primária ao criar registros

Registros com valores de chave alternativos correspondentes bloqueiam a restauração

Os registros que usam opções de opção removidas não são restaurados

Violação de chave primária durante exclusão

Detectar quais tabelas estão habilitadas para manutenção de registros excluídos

Detectar quais tabelas não estão habilitadas para manutenção de registros excluídos

Recuperar e definir a configuração de período de limpeza automática para a manutenção de registros excluídos

Desabilitar a manutenção de registros excluídos para o ambiente

Gerenciar a restauração de registros excluídos pela lógica de negócios personalizada

Atualmente, não há suporte para tabelas para manutenção de registros excluídos

Consulte também

Comentários

Recursos adicionais