Bagikan melalui

API dan kustomisasi kolaborasi Microsoft Entra B2B

  • Artikel

Berlaku untuk: Lingkaran hijau dengan simbol tanda centang putih. Penyewa Tenaga Kerja Penyewa Lingkaran putih dengan simbol X abu-abu. eksternal (pelajari lebih lanjut)

Dengan Microsoft Graph REST API, Anda dapat menyesuaikan proses undangan dengan cara yang paling sesuai untuk organisasi Anda.

Kapabilitas API undangan

API menawarkan kapabilitas berikut:

  1. Mengundang pengguna eksternal dengan alamat email apa pun.

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

  2. Menyesuaikan tempat bagi pengguna Anda untuk masuk setelah mereka menerima undangan.

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

  3. Pilih untuk mengirim email undangan standar melalui kami.

    "sendInvitationMessage": true

    dengan pesan ke penerima yang bisa Anda kustomisasi.

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

  4. Dan pilih untuk cc: orang-orang yang ingin Anda beri kabar tentang mengundang kolaborator ini.

  5. Atau sesuaikan sepenuhnya alur kerja undangan dan onboarding Anda dengan memilih untuk tidak mengirim pemberitahuan melalui ID Microsoft Entra.

    "sendInvitationMessage": false

    Dalam hal ini, Anda mendapatkan URL penukaran dari API yang dapat disematkan dalam templat email, IM, atau metode distribusi pilihan Anda lainnya.

  6. Terakhir, jika Anda adalah admin, Anda dapat memilih untuk mengundang pengguna sebagai anggota.

    "invitedUserType": "Member"

Menentukan apakah pengguna sudah diundang ke direktori Anda

Anda dapat menggunakan API undangan untuk menentukan apakah pengguna sudah ada dalam penyewa sumber daya Anda. Hal ini dapat berguna saat Anda mengembangkan aplikasi yang menggunakan API undangan untuk mengundang pengguna. Jika pengguna sudah ada di direktori sumber daya Anda, mereka tidak akan menerima undangan, sehingga Anda bisa menjalankan kueri terlebih dahulu untuk menentukan apakah email sudah ada sebagai UPN atau properti masuk lainnya.

  1. Pastikan domain email pengguna bukan bagian dari domain terverifikasi penyewa sumber daya Anda.

  2. Dalam penyewa sumber daya, gunakan kueri mendapatkan pengguna berikut di mana {0} adalah alamat email yang Anda undang:

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

Model otorisasi

API dapat dijalankan dalam mode otorisasi berikut:

Mode Aplikasi + Pengguna

Dalam mode ini, siapa pun yang menggunakan API harus memiliki izin untuk membuat undangan B2B.

Mode hanya aplikasi

Dalam konteks hanya aplikasi, dibutuhkan cakupan User.Invite.All agar undangan berhasil.

Untuk mengetahui informasi selengkapnya, silakan lihat: https://developer.microsoft.com/graph/docs/authorization/permission_scopes

PowerShell

Anda dapat menggunakan PowerShell untuk menambah dan mengundang pengguna eksternal ke organisasi dengan mudah. Membuat undangan menggunakan cmdlet:

New-MgInvitation

Anda dapat menggunakan opsi berikut:

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

Status undangan

Setelah mengirim undangan kepada pengguna eksternal, Anda dapat menggunakan cmdlet Get-MgBetaUser untuk melihat apakah mereka telah menerimanya. Properti Get-MgBetaUser berikut diisi saat pengguna eksternal dikirimi undangan:

  • externalUserState menunjukkan apakah undangan adalah PendingAcceptance atau Accepted.
  • externalUserStateChangeDateTime memperlihatkan tanda waktu untuk perubahan terbaru ke properti externalUserState .

Anda dapat menggunakan opsi Filter untuk memfilter hasil menurut externalUserState. Contoh di bawah ini menunjukkan cara menyaring hasil untuk hanya menampilkan pengguna yang memiliki undangan yang tertunda. Contoh tersebut juga menunjukkan opsi Format-List, yang memungkinkan Anda untuk menentukan properti yang ditampilkan.

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

Catatan

Pastikan Anda memiliki versi terbaru modul Microsoft Graph PowerShell

Lihat juga

Memeriksa referensi API undangan di https://developer.microsoft.com/graph/docs/api-reference/v1.0/resources/invitation.

Langkah berikutnya