Visão geral das APIs de Backup e Recuperação do Microsoft Entra

Namespace: microsoft.graph.entraRecoveryServices

As APIs de Backup e recuperação do Microsoft Entra no Microsoft Graph permitem que você faça backup e restaure de forma programática objetos críticos de diretório para um bom estado conhecido anteriormente. Essas APIs ajudam os administradores de TI a se recuperarem de alterações acidentais ou comprometimentos de segurança, exibindo backups disponíveis, visualizando alterações de restauração, executando operações de recuperação e monitorando o progresso do trabalho.

Objetos de diretório com suporte

As APIs de backup e recuperação são compatíveis com os seguintes objetos de diretório do Microsoft Entra. Para cada tipo de objeto, apenas um subconjunto de propriedades e relações é rastreado e tem suporte no processo de backup e recuperação.

Também há suporte para identidades de agentes associadas a usuários, aplicativos ou entidades de serviço.

Para obter mais informações, consulte Objetos com suporte e propriedades recuperáveis no Microsoft Entra Backup e recuperação do Microsoft Entra.

Observação

Objetos excluídos irreversivelmente não podem ser recuperados. Somente os objetos que foram modificados, excluídos temporariamente ou criados recentemente desde o backup podem ser resolvidos por uma operação de recuperação. Objetos sincronizados do Active Directory local com a fonte de autoridade local não podem ser recuperados, mas as alterações são visíveis nos instantâneos.

Principais conceitos de API

Instantâneos

Um snapshot representa um backup pontual dos dados do diretório do locatário. Cada snapshot tem um identificador exclusivo (carimbo de data/hora codificado em base64) e rastreia a contagem total de objetos alterados. Use instantâneos como ponto de partida para operações de visualização e recuperação.

O Microsoft Entra cria automaticamente um backup de um snapshot por dia e retém até cinco dias de histórico de snapshots. Os instantâneos não são editáveis e não podem ser excluídos ou desabilitados por nenhum usuário ou aplicativo.

Empregos

O processo de backup e recuperação gira em torno de dois tipos de trabalhos: trabalhos de visualização e trabalhos de recuperação, representados pelos tipos de recursos recoveryPreviewJob e recoveryJob , respectivamente.

Você pode definir o escopo dos trabalhos de visualização e recuperação para subconjuntos de dados específicos usando critérios de filtragem:

  • Limite o escopo a tipos de entidade específicos (por exemplo, apenas usuários ou apenas usuários e grupos).
  • Limite o escopo a objetos específicos identificados por tipo de entidade e ID de objeto.

Os trabalhos são operações de execução prolongada. Quando você cria um trabalho, a resposta inclui um Location cabeçalho com a URL do recurso de trabalho criado. Sonde esse recurso para marcar o status do trabalho até que ele seja concluído.

  • Um trabalho de visualização bem-sucedido fornece uma lista abrangente de objetos que seriam afetados por uma operação de recuperação, juntamente com as alterações de propriedades específicas.
  • Um trabalho de recuperação bem-sucedido aplica as alterações necessárias para restaurar os objetos de diretório do locatário para o estado snapshot. Após a conclusão, você pode examinar todas as alterações com falha que não puderam ser aplicadas.

Somente um trabalho (versão prévia ou recuperação) pode ser executado por vez por locatário. Aguarde a conclusão de um trabalho em execução ou cancele-o antes de iniciar um novo.

Trabalhos de visualização de recuperação

Um recoveryPreviewJob é uma "simulação" que calcula as diferenças entre o estado atual do locatário e um snapshot selecionado. Os trabalhos de visualização não modificam nenhum dado.

Um trabalho de visualização pode ser concluído com êxito, com falha ou abandonado (cancelado).

  • Após a conclusão de um trabalho de visualização, chame a função getChanges para enumerar os objetos que seriam afetados, juntamente com as alterações de propriedade específicas.
  • Para cancelar um trabalho de visualização, chame a ação de cancelamento . Nenhum resultado está disponível para um trabalho abandonado.

Cada objeto alterado retornado por getChanges ou getFailedChanges inclui uma propriedade recoveryAction que indica o que a operação de recuperação faz com esse objeto:

Ação Descrição
update As propriedades do objeto são atualizadas para corresponder ao estado do snapshot.
softDelete O objeto é excluído temporariamente porque não existia no snapshot ou foi excluído no snapshot.
restore O objeto é restaurado de um estado de exclusão reversível porque ele existia no snapshot.

Trabalhos de recuperação

Ao contrário de um trabalho de visualização, um recoveryJob executa a restauração real de objetos de diretório para o estado de snapshot selecionado. Após a conclusão de um trabalho de recuperação, chame a função getFailedChanges para examinar todas as alterações que não puderam ser aplicadas.

Fluxo de trabalho típico

O diagrama a seguir ilustra o fluxo de trabalho típico de ponta a ponta para usar as APIs de backup e recuperação:

Etapa 1: listar instantâneos disponíveis Recupere os backups disponíveis para identificar o snapshot para o qual você deseja restaurar.

GET /directory/recovery/snapshots

Etapa 2: Criar um trabalho de visualização Crie um trabalho de visualização para calcular as diferenças entre o estado atual do locatário e o snapshot selecionado. Opcionalmente, inclua critérios de filtragem para limitar o escopo.

POST /directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs

Etapa 3: Sonde o status do trabalho de visualização O trabalho de visualização é uma operação de execução longa que retorna uma 202 Accepted resposta com um Location cabeçalho que aponta para o recurso de trabalho criado. Sonde seu status até que ele seja concluído. Quando o trabalho for concluído (successful, failedou abandoned status), recupere os resultados.

GET /directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs/{job-id}

Etapa 4: revise as alterações Depois que o trabalho de visualização for concluído com êxito, recupere a lista de objetos que seriam afetados.

GET /directory/recovery/snapshots/{snapshot-id}/recoveryPreviewJobs/{job-id}/microsoft.graph.entraRecoveryServices.getChanges

Etapa 5: criar um trabalho de recuperação Depois de revisar a versão prévia, crie um trabalho de recuperação para aplicar as alterações. Você pode usar os mesmos critérios de filtragem da visualização.

POST /directory/recovery/snapshots/{snapshot-id}/recoveryJobs

Etapa 6: Monitorar o trabalho de recuperação O trabalho de recuperação é uma operação de execução longa que retorna uma 202 Accepted resposta com um Location cabeçalho que aponta para o recurso de trabalho criado. Sonde seu status para acompanhar o progresso, incluindo o número de objetos e links modificados. Quando o trabalho for concluído (successful, failedou abandoned status), recupere os resultados.

GET /directory/recovery/snapshots/{snapshot-id}/recoveryJobs/{job-id}

Etapa 7: Examinar as alterações com falha (se houver) Se o trabalho de recuperação relatar alterações com falha, recupere os detalhes para entender o que não pôde ser aplicado e por quê.

GET /directory/recovery/snapshots/{snapshot-id}/recoveryJobs/{job-id}/microsoft.graph.entraRecoveryServices.getFailedChanges

Dica

Você pode cancelar um trabalho de visualização ou recuperação em execução a qualquer momento chamando a ação de cancelamento . O cancelamento de um trabalho atualiza seu status para abandoned.

Logs de auditoria

Todas as operações executadas por meio das APIs de backup e recuperação são registradas nos logs de auditoria do Microsoft Entra com a categoria "Backup e Recuperação". Você pode usar esses logs para rastrear quando os instantâneos foram criados, quando os trabalhos de visualização e recuperação foram iniciados e seus resultados.

Permissões e privilégios

As APIs de backup e recuperação dão suporte a permissões delegadas e de aplicativo. Para obter mais informações sobre as permissões necessárias para chamar essas APIs, consulte os tópicos de referência de API individuais para cada operação.

Além das permissões do Microsoft Graph, o usuário conectado deve receber uma das seguintes funções do Microsoft Entra:

  • Microsoft Entra Backup Reader — Para operações de leitura (listagem de instantâneos, visualização de trabalhos, recuperação de alterações).
  • Administrador do Backup do Microsoft Entra — Para operações de gravação (criação de trabalhos de visualização, criação de trabalhos de recuperação, cancelamento de trabalhos).

Limitações

  • Esse recurso não tem suporte para locatários Entra ID externa e Azure AD B2C.
  • Os instantâneos de backup são criados automaticamente uma vez por dia e mantidos por cinco dias. Você não pode criar, modificar, excluir ou exportar instantâneos.
  • Nem todos os atributos e atributos vinculados dos tipos de objeto suportados podem ser recuperados.
  • Objetos sincronizados com o Active Directory local não podem ser recuperados por meio dessas APIs, embora as alterações sejam visíveis nos instantâneos.
  • O tempo de conclusão do trabalho depende do volume de dados e da complexidade do processamento. Aguarde pelo menos uma hora para concluir.
  • Não há suporte para a recuperação para outro locatário.
  • As operações de recuperação não geram notificações de alteração por meio de assinaturas ou registros delta para controle de alterações. Os aplicativos que dependem desses mecanismos não são notificados sobre as alterações feitas pelos trabalhos de recuperação.

Limitação

As APIs de backup e recuperação seguem os limites de limitação específicos do serviço padrão do Microsoft Graph. Monitore 429 Too Many Requests as respostas e implemente a lógica de repetição usando o Retry-After cabeçalho.