API e personalização da colaboração B2B do Azure Active DirectoryAzure Active Directory B2B collaboration API and customization

Muitos clientes nos disseram que desejam personalizar o processo de convite de forma que funcione melhor para suas organizações.We've had many customers tell us that they want to customize the invitation process in a way that works best for their organizations. Com nossa API, você pode fazer exatamente isso.With our API, you can do just that. https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation

Recursos da API de conviteCapabilities of the invitation API

A API oferece os seguintes recursos:The API offers the following capabilities:

  1. Convidar um usuário com qualquer endereço de email.Invite an external user with any email address.

    "invitedUserDisplayName": "Sam"
    "invitedUserEmailAddress": "gsamoogle@gmail.com"
    
  2. Personalizar onde você deseja que os usuários cheguem depois de aceitar o convite.Customize where you want your users to land after they accept their invitation.

    "inviteRedirectUrl": "https://myapps.microsoft.com/"
    
  3. Optar por enviar o email de convite padrão por nosso intermédioChoose to send the standard invitation mail through us

    "sendInvitationMessage": true
    

    com uma mensagem para o destinatário que você pode personalizarwith a message to the recipient that you can customize

    "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.And choose to cc: people you want to keep in the loop about your inviting this collaborator.

  5. Ou personalizar completamente seu convite e o fluxo de integração ao optar por não enviar notificações por meio do Azure AD.Or completely customize your invitation and onboarding workflow by choosing not to send notifications through Azure AD.

    "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.In this case, you get back a redemption URL from the API that you can embed in an email template, IM, or other distribution method of your choice.

  6. Por fim, se você for administrador, poderá convidar o usuário como membro.Finally, if you are an admin, you can choose to invite the user as member.

    "invitedUserType": "Member"
    

Determinar se um usuário já foi convidado para seu diretórioDetermine if a user was already invited to your directory

Você pode usar a API de convite para determinar se um usuário já existe no seu locatário de recursos.You can use the invitation API to determine if a user already exists in your resource tenant. Isso pode ser útil quando você estiver desenvolvendo um aplicativo que usa a API de convite para convidar um usuário.This can be useful when you're developing an app that uses the invitation API to invite a user. Se o usuário já existir no diretório de recursos, ele não receberá um convite para que você possa executar uma consulta primeiro para determinar se o email já existe como um UPN ou outra propriedade de entrada.If the user already exists in your resource directory, they won't receive an invitation, so you can run a query first to determine whether the already email exists as a UPN or other sign-in property.

  1. Verifique se o domínio de email do usuário não faz parte do domínio verificado do seu locatário de recursos.Make sure the user's email domain isn't part of your resource tenant's verified domain.

  2. No locatário de recursos, use a seguinte consulta Get User, em que {0} é o endereço de email que você está convidando:In the resource tenant, use the following get user query where {0} is the email address you're inviting:

    “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çãoAuthorization model

A API pode ser executada nos seguintes modos de autorização:The API can be run in the following authorization modes:

Modo Aplicativo + UsuárioApp + User mode

Nesse modo, a pessoa que está usando a API precisa ter as permissões para criar convites de B2B.In this mode, whoever is using the API needs to have the permissions to be create B2B invitations.

Modo Somente aplicativoApp only mode

No contexto somente aplicativo, o aplicativo precisa do escopo User.Invite.All para que o convite tenha êxito.In app only context, the app needs the User.Invite.All scope for the invitation to succeed.

Para obter mais informações, consulte: https://developer.microsoft.com/graph/docs/authorization/permission_scopesFor more information, refer to: https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShellPowerShell

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

New-AzureADMSInvitation

É possível usar as seguintes opções:You can use the following options:

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

Status do conviteInvitation status

Depois que você envia um convite por um usuário externo, você pode usar o Get-AzureADUser cmdlet para ver se eles aceitou-lo.After you send an external user an invitation, you can use the Get-AzureADUser cmdlet to see if they've accepted it. As seguintes propriedades de Get-AzureADUser são preenchidas quando um usuário externo é enviado um convite:The following properties of Get-AzureADUser are populated when an external user is sent an invitation:

  • UserState indica se o convite é PendingAcceptance ou Aceito.UserState indicates whether the invitation is PendingAcceptance or Accepted.
  • UserStateChangedOn mostra o registro de data e hora da última alteração na propriedade UserState.UserStateChangedOn shows the timestamp for the latest change to the UserState property.

Você pode usar o filtro opção para filtrar os resultados por UserState.You can use the Filter option to filter the results by UserState. O exemplo a seguir mostra como filtrar resultados para mostrar apenas os usuários que têm um convite pendente.The example below shows how to filter results to show only users who have a pending invitation. O exemplo também mostra a Format-List opção, que permite que você especifique as propriedades a serem exibidas.The example also shows the Format-List option, which lets you specify the properties to display.

Get-AzureADUser -Filter "UserState eq 'PendingAcceptance'" | Format-List -Property DisplayName,UserPrincipalName,UserState,UserStateChangedOn

Observação

Verifique se você possui a versão mais recente do módulo do PowerShell do AzureAD ou do módulo PowerShell do AzureADPreview.Make sure you have the latest version of the AzureAD PowerShell module or AzureADPreview PowerShell module.

Veja tambémSee also

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

Próximas etapasNext steps