Como gerenciar contas de usuário com a API de administração do Exchange Online

By Mirko Peters · 2026-03-09 · Updated 2026-03-24

Conheça a API de administração do Exchange Online, uma alternativa baseada em REST ao Exchange Web Services (EWS). Gerencie contas de usuário do Exchange Online com eficiência.

Automatically translated with AI from the original post. Read the English original

Gerenciar contas de usuário é fundamental para qualquer organização. Isso garante que os funcionários tenham o acesso certo aos recursos e mantém as informações sensíveis protegidas. A API de administração do Exchange torna esse processo mais simples e eficiente. Com seus recursos poderosos, você pode criar, atualizar ou excluir contas de usuário com rapidez. Além disso, ela permite gerenciar caixas de correio de forma eficaz. Essa API otimiza o seu fluxo de trabalho e economiza tempo, para que você possa se concentrar no que realmente importa: a sua equipe.

Principais conclusões

• A API de administração do Exchange simplifica o gerenciamento de contas de usuário, permitindo criar, atualizar e excluir contas com eficiência.

• Use o OAuth 2.0 para autenticação segura na API. Ele protege as credenciais do usuário ao usar tokens de acesso em vez de senhas.

• Sempre proteja seus tokens de acesso para evitar acesso não autorizado e possíveis vazamentos de dados.

• Implemente estratégias de tratamento de erros para lidar de forma eficaz com problemas comuns, como acesso não autorizado ou solicitações inválidas.

• Fique atento aos limites de taxa ao usar a API. Monitore o seu uso e considere agrupar solicitações para permanecer dentro dos limites.

7 fatos surpreendentes sobre a API de administração do Exchange

Se você gerencia o Exchange Online, a API de administração do Exchange pode mudar a forma como você automatiza, protege e monitora o seu ambiente. Aqui estão sete fatos surpreendentes sobre a API de administração do Exchange.

1. Ela expõe o gerenciamento de caixas de correio além do Graph API. Embora o Microsoft Graph cubra muitos cenários de usuários e caixas de correio, a API de administração do Exchange oferece endpoints especializados para configurações e gerenciamento específicos do Exchange que não estão disponíveis no Graph, tornando-a a escolha ideal para automação profunda do Exchange Online.
2. RBAC granular e consentimento de administrador são obrigatórios. A API aplica controles de acesso baseados em funções voltados ao Exchange e frequentemente exige consentimento explícito do administrador para operações sensíveis; por isso, o escopo de privilégio mínimo e as entidades de serviço dedicadas são essenciais para uma automação segura.
3. Oferece suporte a operações em lote e em massa para escalar. A API de administração do Exchange permite padrões de gerenciamento em lote e em massa (por exemplo, atualizar políticas em muitas caixas de correio), o que reduz significativamente o número de chamadas e simplifica o gerenciamento de locatários em grande escala.
4. Tem limitação de taxa e limites no nível do locatário diferentes do Graph. As regras de limitação e os limites de solicitações são distintos do Microsoft Graph; por isso, você precisa projetar lógica de nova tentativa e recuo especificamente para o comportamento da API de administração do Exchange, a fim de evitar falhas inesperadas sob carga.
5. Habilita controles avançados de conformidade e auditoria. A API expõe recursos de conformidade específicos do Exchange, como regras de fluxo de email, atribuições de política de retenção e configurações de auditoria, permitindo a aplicação programática de políticas organizacionais em escala.
6. Integra-se com ambientes Exchange híbridos. Para organizações no modo híbrido, a API de administração do Exchange pode ser usada junto com as ferramentas de gerenciamento locais para coordenar configurações e políticas, facilitando cenários de migração e coexistência.
7. Pode ser estendida com PowerShell e fluxos de autenticação modernos. Você pode combinar os módulos do PowerShell para Exchange Online com a API de administração do Exchange usando OAuth 2.0 com autenticação somente de aplicativo ou fluxos delegados, possibilitando uma automação moderna e segura e preservando os recursos legados do PowerShell quando necessário.

Use a API de administração do Exchange para complementar o Microsoft Graph e o PowerShell, em prol de um gerenciamento do Exchange Online robusto, escalável e seguro.

Métodos de autenticação

Visão geral do OAuth 2.0

Ao trabalhar com a Exchange Admin API, entender o OAuth 2.0 é essencial. Esse framework aumenta a segurança ao permitir que aplicativos acessem recursos sem expor as credenciais do usuário. Em vez de compartilhar senhas, você usa tokens de acesso, o que reduz significativamente o risco de acesso não autorizado. Veja a seguir alguns recursos principais do OAuth 2.0 que o tornam uma escolha robusta para autenticação em APIs:

Obtendo tokens de acesso

Para interagir com a Exchange Admin API, você precisa obter tokens de acesso. Aqui está um guia simples, passo a passo, para ajudá-lo nesse processo:

1. Registre um aplicativo no Microsoft Entra ID.

2. Atribua as permissões de API necessárias.

3. Atribua as permissões RBAC necessárias.

4. Obtenha um token de acesso.

Proteger seus tokens de acesso é fundamental. Se os tokens não estiverem protegidos, eles podem levar a sérios riscos de segurança. Veja a seguir alguns possíveis perigos de tokens de acesso não protegidos:

• APIs podem expor dados sensíveis se não forem protegidas adequadamente.

• Tokens de acesso não protegidos podem levar a acesso não autorizado e à manipulação de dados.

• O aumento dos ataques a APIs evidencia a necessidade de medidas de segurança robustas.

Além disso, se alguém se fizer passar por um Administrador Global, poderá obter controle total sobre o seu locatário, incluindo acesso a serviços como SharePoint Online e Exchange Online. Isso pode resultar em violações de dados significativas.

Para atribuir funções RBAC do Exchange Online a aplicativos para acesso a APIs, siga estes passos:

1. Em cenários delegados, certifique-se de que o usuário tenha as funções RBAC necessárias atribuídas no Exchange Online, como Gerenciamento de Destinatários ou Gerenciamento da Organização.

2. Em cenários somente de aplicativo, atribua funções do Microsoft Entra ou grupos de funções RBAC personalizados do Exchange à entidade de serviço que representa o seu aplicativo.

3. Use o fluxo de token de acesso OAuth 2.0 apropriado para o tipo do seu aplicativo, seja delegado ou somente de aplicativo.

4. Instale o Exchange Online PowerShell e conecte-se a ele.

5. Crie uma nova entidade de serviço e atribua as funções necessárias.

6. Verifique a atribuição de funções e teste o RBAC para aplicativos.

Seguindo essas diretrizes, você pode gerenciar contas de usuário com eficácia, mantendo suas interações com a API seguras.

Gerenciando contas de usuário com a Exchange Admin API

Criando contas de usuário

Criar contas de usuário com a Exchange Admin API é simples. Você precisa informar campos específicos para configurar um novo usuário. Aqui está uma lista rápida dos parâmetros obrigatórios:

• Alias: é o nome de usuário da conta.

• Name: o nome completo do usuário.

• FirstName: o primeiro nome do usuário.

• LastName: o sobrenome do usuário.

• DisplayName: como o nome do usuário aparece no diretório.

• MicrosoftOnlineServicesID: o endereço de e-mail associado à conta.

• Password: você precisará solicitar essa informação ao usuário.

• ResetPasswordOnNextLogon: é opcional, mas pode ser definido como true caso você queira que o usuário altere a senha no primeiro login.

Veja a seguir um exemplo simples de como você pode criar uma conta de usuário usando PowerShell:

New-MgUser -AccountEnabled $true -DisplayName "Holly Holt" -MailNickname "hollyh" -UserPrincipalName "hollyh@corp.contoso.com" -PasswordProfile @{ForceChangePasswordNextSignIn=$true; Password="YourSecurePassword"}

Atualizando informações do usuário

Atualizar informações do usuário é igualmente simples. Você pode modificar diversos atributos de uma conta de usuário por meio da Exchange Admin API. Veja a seguir alguns atributos comuns que você pode querer atualizar:

Para atualizar um usuário, você pode usar um comando como este:

Update-MgUser -UserId "<userId>" -DisplayName "Holly Holt Updated"

Este comando atualiza o nome de exibição do usuário com o ID de usuário especificado.

Excluindo contas de usuário

Ao excluir contas de usuário, você precisa seguir alguns passos para garantir que tudo corra bem. Aqui está um guia rápido:

1. Conecte-se ao seu locatário do Microsoft 365 usando o PowerShell com as permissões necessárias.

2. Use o comando Connect-MgGraph -Scopes User.Read.All, User.ReadWrite.All para estabelecer a conexão.

3. Recupere o ID do usuário filtrando pelo nome de exibição usando Get-MgUser -Filter "displayName eq '<display name>'".

4. Remova a conta de usuário com o comando Remove-MgUser -UserId <userId> -Confirm:$false.

Esse processo garante que você consiga gerenciar contas de usuário com eficiência, mantendo sua organização segura e organizada.

Consultando caixas de correio para uma gestão eficaz

Consultar caixas de correio é essencial para uma gestão eficaz de contas de usuário. Aqui estão algumas boas práticas a considerar:

• Sempre use POST para todas as operações, incluindo os cmdlets Get-*.

• Inclua apenas os parâmetros compatíveis com o cmdlet no endpoint.

• Use X-AnchorMailbox em todas as operações para garantir que as solicitações sejam roteadas corretamente.

• Utilize $select para reduzir o tamanho da resposta, especialmente ao trabalhar com grandes volumes de dados.

• Combine $select com paginação para gerenciar grandes volumes de dados com eficiência.

Seguindo essas diretrizes, você pode simplificar a gestão das suas caixas de correio e manter suas contas de usuário sempre atualizadas.

Melhores práticas para a Exchange Admin API

Tratamento de erros

Ao trabalhar com a Exchange Admin API, você pode encontrar erros. Saber como tratá-los com eficiência pode economizar tempo e evitar frustrações. Aqui está uma tabela prática com códigos de erro comuns, suas causas e as correções sugeridas:

Seguindo essas estratégias, você pode minimizar interrupções e manter suas operações funcionando sem problemas.

Considerações sobre limitação de taxa

A limitação de taxa (rate limiting) é outro aspecto importante a considerar ao usar a Exchange Admin API. Ela ajuda a manter o desempenho da API e garante uso justo entre todos os usuários. Aqui estão algumas dicas:

• Conheça os limites: familiarize-se com os limites de taxa impostos pela API. Esse conhecimento ajuda você a planejar suas solicitações de acordo.

• Implemente estratégias de backoff: se você atingir um limite de taxa, implemente uma estratégia de backoff. Isso significa aguardar um pouco antes de tentar a solicitação novamente. Assim você evita ser bloqueado.

• Monitore o seu uso: fique de olho no uso da sua API. Ferramentas de monitoramento podem ajudar você a acompanhar quantas requisições faz e quando se aproxima dos limites.

• Agrupe as requisições em lote: se possível, agrupe suas requisições. Essa abordagem pode reduzir o número de chamadas que você faz e ajudar a permanecer dentro dos limites.

Ao considerar os limites de taxa, você garante que suas interações com a Exchange Admin API continuem eficientes e eficazes.

Em resumo, a Exchange Admin API é uma ferramenta poderosa para gerenciar contas de usuário com eficiência. Você pode criar, atualizar e excluir contas com facilidade, garantindo que a sua organização funcione sem problemas. Lembre-se de que proteger seus tokens de acesso e entender o tratamento de erros são fundamentais para uma experiência tranquila.

Para se aprofundar na Exchange Admin API, considere estes recursos:

• Este artigo orienta você a fazer sua primeira chamada bem-sucedida à Exchange Online Admin API e explica comportamentos e padrões importantes aplicáveis a todos os endpoints.

Então, não hesite! Explore a API e veja como ela pode aprimorar seus processos de gerenciamento de usuários. Feliz programação! 🚀

Perguntas frequentes

O que é a Exchange Admin API?

A Exchange Admin API permite gerenciar contas de usuário e caixas de correio no Microsoft Exchange Online. Ela simplifica tarefas como criar, atualizar e excluir contas de usuário, tornando a administração mais eficiente.

Como faço a autenticação com a Exchange Admin API?

Você faz a autenticação usando OAuth 2.0. Registre seu aplicativo no Microsoft Entra ID, atribua permissões e obtenha um token de acesso para interagir com a API de forma segura.

Posso automatizar o gerenciamento de contas de usuário?

Sim! Você pode automatizar o gerenciamento de contas de usuário usando scripts com PowerShell ou outras linguagens de programação. Isso economiza tempo e reduz erros manuais na administração de usuários.

O que devo fazer se encontrar um erro?

Verifique o código de erro e consulte a documentação para ver as etapas de solução de problemas. Problemas comuns incluem tokens inválidos ou permissões ausentes. Ajuste suas requisições de acordo.

Como posso monitorar o uso da API?

Você pode monitorar o uso da API implementando registro de logs no seu aplicativo. Acompanhe o número de requisições feitas e fique atento a avisos de limite de taxa para evitar interrupções.

O que é a Exchange Admin API e qual é a sua relação com o Exchange Online?

A Exchange Admin API é uma nova API administrativa baseada em REST, lançada pela Microsoft para permitir tarefas administrativas do Exchange no Exchange Online e no Exchange Online do Office 365. Ela é uma abordagem baseada em REST, criada para ajudar as organizações a modernizar a automação, oferecendo endpoints da API que executam um conjunto específico de cmdlets e parâmetros do Exchange para cenários comuns de gerenciamento que antes eram tratados com EWS ou com o PowerShell do Exchange Online.

A Exchange Admin API substitui o Exchange Web Services (EWS)?

A nova API não é uma substituição direta, de um para um, para todos os cenários do EWS, mas foi projetada para ajudar as organizações a migrar do EWS ao longo do tempo. A Microsoft anunciou cronogramas de descontinuação e orientações, como a descontinuação em outubro de 2026 para determinados cenários do EWS. A versão prévia pública da Admin API oferece alternativas de API REST para muitos cenários administrativos do Exchange e moderniza a automação.

Quais tarefas administrativas são compatíveis com os endpoints da Admin API?

A API oferece suporte a um conjunto limitado de tarefas administrativas do Exchange Online, com foco em tarefas de gerenciamento como gerenciar domínios aceitos, configurações de permissões de pasta de caixa de correio e atribuições de delegação e permissões, além de outras tarefas administrativas do Exchange. A Admin API é uma superfície administrativa baseada em REST, projetada para viabilizar cenários comuns de administração do Exchange e permitir a automação via REST junto com os cmdlets do PowerShell e scripts do PowerShell.

Como isso impacta administradores do Office 365 e do Exchange Online no Office 365?

Para administradores do Office 365 e do Exchange Online no Office 365, a versão prévia do Exchange oferece um caminho para modernizar com uma API REST e reduzir a dependência de código EWS e de cmdlets do Exchange. Os administradores podem usar os endpoints da Admin API ou continuar usando o PowerShell do Exchange Online enquanto a Microsoft amplia os recursos disponíveis na versão prévia pública da Admin API. Isso ajuda as organizações a migrar do EWS e adotar uma automação moderna que se integra aos fluxos de trabalho de gerenciamento do Microsoft 365.

E o Exchange Online PowerShell e os cmdlets existentes do PowerShell, serão removidos?

O Exchange Online PowerShell e os cmdlets do PowerShell continuam sendo uma opção com suporte para muitas tarefas. A API de administração foi criada para complementar os cmdlets e parâmetros do Exchange, oferecendo uma alternativa baseada em REST para cenários específicos de administração do Exchange. A Microsoft disponibilizou uma prévia da API de administração do Exchange e orientações para usar tanto scripts do PowerShell quanto a API de administração; alguns cenários continuarão exigindo o Exchange Online PowerShell até que os endpoints da API de administração cubram um conjunto mais amplo de funcionalidades do Exchange.

Quando o EWS será desativado e o que as organizações devem fazer antes de outubro de 2026?

A Microsoft sinalizou a descontinuação, em outubro de 2026, de determinados usos do EWS e recomendou que as organizações planejem a migração para longe do EWS em cenários específicos de administração do Exchange. Os administradores devem fazer um inventário do código EWS, dos usos do EWS para cenários específicos de administração do Exchange e de quaisquer outros cenários de EWS no ambiente. Em seguida, devem avaliar a versão pública prévia da API de administração, as alternativas de API REST e o Exchange Online PowerShell para modernizar a automação antes da descontinuação, em outubro de 2026.

A API de administração consegue gerenciar permissões de caixa de correio, como mailboxfolderpermission e delegados?

Sim, a API de administração oferece suporte ao gerenciamento de mailboxfolderpermission e de atribuições de delegados em muitos cenários, com endpoints que permitem aos administradores definir ou modificar configurações de delegados e permissões. Embora a API de administração possa inicialmente oferecer um conjunto limitado, ela foi projetada para ajudar as organizações a automatizar essas tarefas administrativas específicas do Exchange sem depender exclusivamente de código EWS ou de cmdlets do Exchange.

Como acesso a API de administração em prévia pública e qual autenticação é necessária?

A API de administração está disponível em prévia pública e exige autenticação moderna por meio da plataforma de identidade da Microsoft (Azure AD/Entra). Os administradores registram um aplicativo, concedem os escopos apropriados para acesso à API do Exchange Online e chamam os endpoints REST da API de administração para executar tarefas de gerenciamento do Exchange. Essa abordagem permite a integração com automações, scripts e estruturas de gerenciamento do Microsoft 365 já existentes.

Há alguma limitação na API de administração durante a prévia pública?

Durante a prévia pública da API de administração, a API pode oferecer um conjunto de recursos mais limitado em comparação com o conjunto completo de cmdlets do Exchange ou do EWS. A prévia concentra-se em tarefas administrativas apropriadas do Exchange e em um subconjunto de funções do Exchange. As organizações devem validar os cenários administrativos e modernizar a automação combinando os endpoints da API de administração com o Exchange Online PowerShell quando necessário, até que a API ofereça suporte a tarefas de gerenciamento do Exchange mais abrangentes.

Como as organizações devem planejar a estratégia de migração do EWS para a nova API de administração baseada em REST?

As organizações devem fazer um levantamento das cargas de trabalho do Exchange que dependem do EWS, identificar cenários administrativos específicos do Exchange e cenários de EWS para essas necessidades, e priorizar a migração da automação de maior impacto para a API de administração ou para o Exchange Online PowerShell. Use a prévia pública da API de administração para testar cenários administrativos e modernizar a automação, atualize os scripts do PowerShell e o código EWS quando apropriado, e acompanhe as orientações da Microsoft sobre a descontinuação e a disponibilidade futura até outubro de 2026 e além.