Guia de migração: Exchange Web Services (EWS) para a API do Microsoft Graph

Migre integrações do Exchange do Exchange Web Services (EWS) para a API do Microsoft Graph antes do prazo de descontinuação de outubro de 2026.

Visão geral

A Microsoft está aposentando a API do Exchange Web Services (EWS) para o Exchange Online, com desabilitação completa em 1º de outubro de 2026. A descontinuação aplica-se apenas ao Exchange Online: o Exchange Server local não é afetado.

Você deve migrar todas as integrações do Exchange Online que atualmente usam o EWS para a API do Microsoft Graph para garantir que elas continuem a funcionar.

Melhores práticas

• Trate as integrações de produção com cuidado. A mudança de credenciais afeta diretamente uma integração ativa, e uma alteração de credencial não pode ser desfeita dentro da plataforma. Planeje cada transição de produção deliberadamente em vez de migrar tudo de uma vez.
• Teste com uma integração separada primeiro. Crie uma integração de teste dedicada com as novas credenciais da API do Graph antes de tocar em qualquer integração de produção (consulte Etapa 3: testar suas credenciais da API do Graph). Isso confirma que o registro do seu aplicativo, as permissões e o consentimento do administrador estão corretos sem arriscar uma caixa de correio de produção.
• Programe transições fora dos horários de pico. Planeje cada alternância de produção para um período em que um intervalo seja aceitável, para limitar o impacto do intervalo de ingestão temporário que ocorre após a troca de credenciais.

Pré-requisitos

Antes de iniciar a migração, certifique-se de atender aos seguintes requisitos:

• Acesso ao Portal do Azure: acesso administrativo ao portal do Azure de sua organização.
• Permissões: a capacidade de registrar aplicativos e conceder consentimento de administrador no Azure AD.
• Acesso à integração: acesso administrativo às suas integrações do Communications Mining.
• Informações da caixa de correio: lista de todas as caixas de correio conectadas atualmente por meio de integrações do EWS.

Processo de migração

Depois de alternar as credenciais de uma integração, a integração do Graph é retomada a partir do primeiro ponto em que qualquer pasta na caixa de correio atingiu o EWS e verifica novamente os emails a partir de lá, ignorando qualquer coisa já sincronizada. Nada é importado duas vezes como resultado.

AVISO:

Ao alternar as credenciais de uma integração de produção para o Graph, espere um intervalo temporário na ingestão de e-mail antes que a nova integração o atinja. Esse é um efeito lateral esperado das diferenças entre as integrações EWS e Graph, não um erro. Programe a transição para fora do horário de pico, quando um intervalo na ingestão for aceitável.

Etapa 1: identificar suas integrações atuais do EWS

1. Faça login no Communications Mining por meio do IXP no Automation Cloud.
2. Navegue até Configurações e, em seguida, até a aba Integrações .
3. Documente todas as integrações existentes do Exchange, incluindo:
   • Nomes da integração
   • Caixas de correio conectadas
   • Projetos associados

Etapa 2: Registrar um aplicativo do Azure

Se você ainda não tiver criado um aplicativo do Azure para o acesso à API do Graph, aplique as seguintes etapas:

2.1 Crie o registro de aplicativo

1. Faça login no seu portal do Azure.

2. Navegue até Registros de aplicativos e selecione Novo registro.

   

3. Configure o aplicativo da seguinte forma:

   • Nome: use um nome descritivo, como por exemplo, uipath-exchange-graph-integration.
   • Tipos de conta compatíveis: selecione Contas apenas neste diretório organizacional (Tenant único).

4. Selecione Registrar.

5. Anote os seguintes valores da página de visão geral do aplicativo:

   • ID do aplicativo (cliente)
   • ID do Diretório (tenant)

2.2 Criar um segredo do cliente

1. Em seu aplicativo, selecione Certificados e segredos no menu esquerdo.

2. Em Segredos do cliente, selecione Novo segredo do cliente.

   

3. Isso abre o painel lateral Adicionar um segredo do cliente . Configure o segredo:

   • Descrição: insira uma descrição significativa, como por exemplo, Exchange Graph Integration Secret.
   • Expira: selecione um período de expiração. A opção recomendada é de 12 ou 24 meses. Observe a data de expiração em algum lugar que você a veja: quando o segredo expira, a ingestão de e-mail é interrompida até que você o gire.

4. Selecione Adicionar.

5. Copie imediatamente o Valor secreto e armazene-o com segurança.

   

Observação:

O Azure exibe o valor do segredo apenas uma vez. Se você o perder, deverá criar um novo segredo.

2.3 Definir permissões de API para o Microsoft Graph

1. Selecione Permissões de API no menu à esquerda.

2. Selecione Adicionar uma permissão.

   

3. Selecione Microsoft Graph na guia APIs da Microsoft .

   

4. Selecione Permissões de aplicativos.

   

5. Expanda E-mail e selecione Mail.Read.

   

6. Selecione Adicionar permissões.

7. Selecione Adicionar uma permissão novamente e, em seguida, selecione Microsoft Graph → Permissões de aplicativos.

8. Pesquise e selecione MailboxFolder.Read.All.

   

9. Selecione Adicionar permissões.

10. Retornando ao menu de permissões de API , selecione Conceder consentimento de administrador para [Your Organization].

11. Selecione Sim na caixa de diálogo de confirmação.

    

Suas permissões configuradas devem mostrar:

• Mail.Read (Application) — marca de seleção verde em Status.
• MailboxFolder.Read.All (Application) — marca de seleção verde em Status.

2.4 Restringir o acesso da caixa de correio (recomendado)

Para segurança aprimorada, seu administrador do Exchange pode limitar o aplicativo para acessar apenas as caixas de correio necessárias criando uma política de acesso ao aplicativo. Certifique-se de seguir o guia da Microsoft: Limitação de permissões de aplicativos a caixas de correio específicas do Exchange Online.

Antes de migrar uma integração de produção, verifique se a política abrange todas as caixas de correio que você planeja sincronizar. Uma caixa de correio fora da política é desabilitada com um erro ErrorAccessDenied na primeira vez que a sincronização tenta lê-la. Para obter detalhes, consulte Solução de problemas de integrações do Exchange.

Etapa 3: testar suas credenciais da API do Graph

Antes de atualizar suas integrações de produção, teste primeiro as novas credenciais da API do Graph em uma integração de teste separada.

1. Vá para Communications Mining em IXP no Automation Cloud.
2. Navegue até Configurações → aba Integrações .
3. Selecione Nova integração.
4. Configure a integração de teste:
   • Selecione um projeto de teste.
   • Insira um nome de teste claro, por exemplo, Exchange Graph Test ou [Production Name] - Test.
5. Em Conectar com seu aplicativo, selecione API do Graph.
6. Selecione Com acesso ao aplicativo.
7. Preencha as credenciais da Etapa 2:
   • Autoridade OAuth: https://login.microsoftonline.com/{tenant_id}
   • ID do cliente do OAuth: ID do seu aplicativo (cliente).
   • Segredo do cliente: o valor do seu segredo do cliente.
8. Selecione Validar e salvar credenciais.
9. Adicione as caixas de correio usadas em sua integração de produção. Use um carimbo de data/hora de início recente para limitar a quantidade de dados sincronizados inicialmente.
10. Selecione Criar integração.
11. Aguarde a primeira sincronização ser concluída.

Verifique se os emails estão sincronizando com sucesso e se nenhuma mensagem de erro aparece na página de status da integração. A caixa de correio começa a ser sincronizada em minutos; a recuperação leva mais tempo quando uma grande quantidade de e-mails fica após o carimbo de data/hora inicial escolhido. Se nenhum e-mail chegar após uma hora, verifique Solução de problemas de integrações do Exchange.

Depois de confirmado, atualize suas integrações de produção.

Etapa 4: fazer backup da sua configuração atual do EWS

Antes de modificar sua integração de produção, registre seus detalhes de conexão atuais do EWS e confirme se você ainda possui uma cópia do segredo do cliente EWS, por exemplo, no armazenamento de segredos da sua organização. A plataforma não exibe as credenciais salvas de volta para você, portanto, você só pode reverter para o EWS se tiver mantido o segredo em outro lugar.

Etapa 5: atualizar sua integração de produção

Observação:

Se você precisar reverter, edite a integração e mude as credenciais de volta para seus detalhes EWS.

1. Vá para Communications Mining em IXP no Automation Cloud.

2. Navegue até Configurações e, em seguida, até a aba Integrações .

3. Localize a integração de produção que você deseja migrar e abra suas configurações.

4. Selecione a guia Credenciais e, em seguida, selecione Alterar credenciais.

5. Em Conectar com seu aplicativo, selecione API do Graph.

6. Selecione Com acesso ao aplicativo.

7. Atualize os seguintes campos:

   • Autoridade do OAuth: https://login.microsoftonline.com/{tenant_id} — substitua {tenant_id} por sua ID do Azure Directory (tenant).
   • ID do cliente do OAuth: ID do seu aplicativo (cliente).
   • Segredo do cliente: o valor do seu segredo do cliente.

8. Selecione Validar e salvar credenciais para verificar sua configuração.

   Observação:

   Se a validação falhar, verifique novamente seu ID de tenant, ID de cliente e segredo do cliente. Certifique-se de que o consentimento do administrador foi concedido para as permissões de API. Observe que a validação bem-sucedida confirma apenas a autenticação: ela não verifica o acesso a nenhuma caixa de correio.

9. Selecione Salvar ou Continuar para aplicar a configuração atualizada.

10. Monitore a integração por pelo menos uma hora para confirmar a operação estável e a sincronização de email bem-sucedida. Se a integração ou uma caixa de correio mostrar um erro, verifique Solução de problemas de integrações do Exchange.

Etapa 6: atualização das integrações restantes

Repita as etapas 3-5 para cada integração restante do EWS em sua organização.