API di Collaborazione B2B di Microsoft Entra e personalizzazione

  • Articolo

Si applica a: Cerchio verde con un segno di spunta bianco. Tenant delle risorse Cerchio bianco con il simbolo X grigio. Tenant esterni (altre informazioni)

L'API REST di Microsoft Graph permette di personalizzare il processo di invito in modo ottimale per l'organizzazione.

Funzionalità dell'API di invito

L'API offre le funzionalità seguenti:

  1. Invitare un utente esterno con qualsiasi indirizzo di posta elettronica.

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

  2. Personalizzare la pagina di destinazione visualizzata dagli utenti dopo avere accettato l'invito.

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

  3. Scegliere di inviare il messaggio di invito standard tramite Microsoft.

    "sendInvitationMessage": true

    con un messaggio personalizzabile per il destinatario.

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

  4. Scegliere di mettere in copia conoscenza le persone che si vuole mantenere nel ciclo relativo all'invito di questo collaboratore.

  5. Oppure, personalizzare completamente l'invito e il flusso di lavoro di onboarding scegliendo di non inviare notifiche tramite Microsoft Entra ID.

    "sendInvitationMessage": false

    In questo caso, si ottiene un URL di riscatto dall'API, che è possibile incorporare in un modello di messaggio di posta elettronica, in un messaggio istantaneo o in un altro metodo di distribuzione.

  6. Gli amministratori infine possono scegliere di invitare l'utente come membro.

    "invitedUserType": "Member"

Determinare se un utente è già stato invitato nella propria directory

È possibile usare l'API di invito per determinare se un utente è già presente nel tenant delle risorse. Ciò può essere utile quando si sviluppa un'app che usa l'API di invito per invitare un utente. Se l'utente esiste già nella directory delle risorse, non riceverà un invito. Pertanto, è possibile eseguire prima una query per determinare se il messaggio di posta elettronica esiste già come UPN o un'altra proprietà di accesso.

  1. Assicurarsi che il dominio della posta elettronica dell'utente non faccia parte del dominio verificato del tenant delle risorse.

  2. Nel tenant delle risorse usare la query get user seguente, in cui {0} è l'indirizzo di posta elettronica a cui si sta inviando l’invito:

    “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}')"

Modello di autorizzazione

L'API può essere eseguita nelle modalità di autorizzazione seguenti:

Modalità app + utente

In questa modalità, chiunque usi l'API deve disporre delle autorizzazioni per creare gli inviti B2B.

Modalità solo app

In un contesto di solo app l'invito viene inviato solo se nell'app è presente l'ambito User.Invite.All.

Per altre informazioni, vedere: https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShell

È possibile usare PowerShell per aggiungere e invitare facilmente utenti esterni a un'organizzazione. Creare un invito tramite il cmdlet:

New-MgInvitation

È possibile usare le opzioni seguenti:

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

Stato invito

Dopo aver inviato un invito a un utente esterno, è possibile usare il cmdlet Get-MgBetaUser per vedere se ha accettato. Le proprietà seguenti di Get-MgBetaUser vengono popolate quando viene inviato un invito a un utente esterno:

  • externalUserState indica se lo stato dell’invito è PendingAcceptance o Accettato.
  • externalUserStateChangeDateTime mostra il timestamp delle modifiche più recenti apportate alla proprietà externalUserState.

È possibile usare l'opzione Filtro per filtrare i risultati in base a externalUserState. L'esempio seguente mostra come filtrare i risultati per mostrare solo gli utenti in attesa di invito. L'esempio mostra anche l'opzione Format-List che consente di specificare le proprietà da visualizzare.

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

Nota

Assicurarsi di avere la versione più recente del modulo PowerShell di Microsoft Graph

Vedi anche

Eseguire il check-out del riferimento all'API di invito in https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation.

Passaggi successivi