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

  • Artigo

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:

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

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

  2. Personalize onde você deseja que seus usuários cheguem depois que eles aceitarem o convite.

    "inviteRedirectUrl": "https://myapps.microsoft.com/"

  3. 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!"

  4. E escolha cc: pessoas que você quer manter informado sobre o seu convite a este colaborador.

  5. 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.

  6. 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.

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

  2. 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.

Próximos passos