API de colaboração e personalização do Microsoft Entra B2B

Artigo
05/24/2024

Aplica-se a: Círculo verde com um símbolo de marca de verificação branco. Locatários da força de Círculo branco com um símbolo X cinzento. trabalho Locatários externos (saiba mais)

Com a API REST do Microsoft Graph, você pode personalizar o processo de convite da maneira que funciona melhor para sua organização.

Recursos da API de convite

A API oferece os seguintes recursos:

Convide um usuário externo com qualquer endereço de e-mail.

"invitedUserDisplayName": "Taylor"
"invitedUserEmailAddress": "taylor@fabrikam.com"

Personalize onde você deseja que seus usuários cheguem depois que eles aceitarem o convite.
```
"inviteRedirectUrl": "https://myapps.microsoft.com/"
```
Opte por enviar o e-mail de convite padrão através de nós.
```
"sendInvitationMessage": true
```
com uma mensagem para o destinatário que você pode personalizar.
```
"customizedMessageBody": "Hello Sam, let's collaborate!"
```
E escolha cc: pessoas que você quer manter informado sobre o seu convite a este colaborador.
Ou personalize completamente seu fluxo de trabalho de convite e integração optando por não enviar notificações por meio do Microsoft Entra ID.
```
"sendInvitationMessage": false
```
Nesse caso, você recebe de volta uma URL de resgate da API que pode ser incorporada em um modelo de e-mail, mensagem instantânea ou outro método de distribuição de sua escolha.
Finalmente, se você for um administrador, poderá optar por convidar o usuário como membro.
```
"invitedUserType": "Member"
```

Determinar se um usuário já foi convidado para seu diretório

Você pode usar a API de convite para determinar se um usuário já existe em seu locatário de recurso. Isso pode ser útil quando você está desenvolvendo um aplicativo que usa a API de convite para convidar um usuário. Se o usuário já existir em seu diretório de recursos, ele não receberá um convite, portanto, você pode executar uma consulta primeiro para determinar se o email já existe como um UPN ou outra propriedade de entrada.

Verifique se o domínio de email do usuário não faz parte do domínio verificado do locatário do recurso.

No locatário do recurso, use a seguinte consulta get user onde {0} é o endereço de email que você está convidando:

“userPrincipalName eq '{0}' or mail eq '{0}' or proxyAddresses/any(x:x eq 'SMTP:{0}') or signInNames/any(x:x eq '{0}') or otherMails/any(x:x eq '{0}')"

Modelo de autorização

A API pode ser executada nos seguintes modos de autorização:

App + Modo de utilizador

Nesse modo, quem estiver usando a API precisa ter as permissões para criar convites B2B.

Modo apenas de aplicação

No contexto somente do aplicativo, o aplicativo precisa do escopo User.Invite.All para que o convite seja bem-sucedido.

Para mais informações, consulte: https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShell

Você pode usar o PowerShell para adicionar e convidar usuários externos para uma organização facilmente. Crie um convite usando o cmdlet:

New-MgInvitation

Você pode usar as seguintes opções:

-InvitedUserDisplayName
-InvitedUserEmailAddress
-SendInvitationMessage
-InvitedUserMessageInfo

Estado do convite

Depois de enviar um convite a um usuário externo, você pode usar o cmdlet Get-MgBetaUser para ver se ele o aceitou. As seguintes propriedades de Get-MgBetaUser são preenchidas quando um usuário externo recebe um convite:

externalUserState indica se o convite é PendingAcceptance ou Accepted.
externalUserStateChangeDateTime mostra o carimbo de data/hora da alteração mais recente na propriedade externalUserState .

Você pode usar a opção Filter para filtrar os resultados por externalUserState. O exemplo abaixo mostra como filtrar resultados para mostrar apenas os usuários que têm um convite pendente. O exemplo também mostra a opção Format-List , que permite especificar as propriedades a serem exibidas.

Get-MgBetaUser -Filter "externalUserState eq 'PendingAcceptance'" | Format-List -Property DisplayName,UserPrincipalName,externalUserState,externalUserStateChangeDateTime

Nota

Verifique se você tem a versão mais recente do módulo PowerShell do Microsoft Graph

Consulte também

Confira a referência da API de convite em https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation.

Partilhar via