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

  • Artigo

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

Recursos da API de convite

A API oferece os seguintes recursos:

  1. Convidar um usuário com qualquer endereço de email.

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

  2. Personalizar onde você deseja que os usuários cheguem depois de aceitar o convite.

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

  3. Escolha enviar o email de convite padrão por nosso intermédio.

    "sendInvitationMessage": true

    com uma mensagem para o destinatário que você pode personalizar.

    "customizedMessageBody": "Hello Sam, let's collaborate!"

  4. E escolher copiar (cc:) as pessoas que você deseja manter no loop sobre o seu convite a esse colaborador.

  5. Ou personalizar completamente seu convite e o fluxo de integração ao optar por não enviar notificações por meio do Microsoft Entra ID.

    "sendInvitationMessage": false

    Nesse caso, você obtém novamente uma URL de resgate da API, que pode ser inserida em um modelo de email, mensagem instantânea ou outro método de distribuição de sua escolha.

  6. Por fim, se você for um administrador, você pode convidar o usuário como membro.

    "invitedUserType": "Member"

Determine se um usuário já foi convidado para o diretório

É possível usar a API de convite para determinar se um usuário já existe no locatário de recursos. Isso pode ser útil quando você estiver desenvolvendo um aplicativo que usa a API de convite para convidar um usuário. Se o usuário já existir no diretório de recursos, ele não recebe 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 de recursos.

  2. No locatário de recursos, use a seguinte consulta get user, em que {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:

Modo Aplicativo + Usuário

Nesse modo, a pessoa que está usando a API precisa ter as permissões para criar convites de B2B.

Modo Somente aplicativo

No contexto somente aplicativo, o aplicativo precisa do escopo User.Invite.All para que o convite tenha êxito.

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

PowerShell

You can use PowerShell to add and invite external users to an organization easily. Crie um convite usando o cmdlet:

New-MgInvitation

É possível usar as seguintes opções:

  • -InvitedUserDisplayName
  • -InvitedUserEmailAddress
  • -SendInvitationMessage
  • -InvitedUserMessageInfo

Status do convite

Ao enviar um convite a um usuário externo, você pode usar o cmdlet Get-MgBetaUser para ver se ele foi aceito. As seguintes propriedades de Get-MgBetaUser são preenchidas ao enviar um convite a um usuário externo:

  • externalUserState indica se o convite está PendingAcceptance ou Accepted.
  • externalUserStateChangeDateTime mostra o carimbo de data/hora da última alteração na propriedade externalUserState.

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

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

Observação

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

Confira também

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

Próximas etapas