Microsoft 365 / Microsoft Graph PowerShell: mengekspor pengguna ke CSV dan mengelola lisensi
Microsoft Graph PowerShell memungkinkan Anda untuk mengambil data pengguna Microsoft 365 dan mengotomatiskan administrasi akun dan lisensi. Mulailah dengan menginstal modul yang diperlukan → menghubungkan dengan izin baca → mengonfirmasi organisasi target → mengekspor pengguna ke file CSV (nilai dipisahkan koma). Latihan hanya-baca dan contoh perubahan akun atau lisensi di bawah ini membutuhkan izin yang berbeda dan memiliki efek yang berbeda, jadi jalankan secara terpisah.
Apa itu Microsoft Graph PowerShell?
Microsoft Graph adalah sebuah API (Antarmuka Pemrograman Aplikasi, sebuah antarmuka untuk komunikasi antar program) yang mengelola data dari Microsoft Entra ID, Teams, SharePoint, dan lainnya. Graph PowerShell SDK (Perangkat Pengembangan Perangkat Lunak) memungkinkan Anda menggunakan API ini melalui perintah PowerShell. Nama saat ini dari layanan direktori, yang sebelumnya disebut Azure Active Directory atau Azure AD dalam dokumen-dokumen lama, adalah Microsoft Entra ID.
Menginstal Graph tidak berarti Anda dapat menggunakan semua perintah manajemen Microsoft 365. Beberapa tugas, seperti perintah manajemen khusus Exchange Online, memerlukan modul dan koneksi terpisah. Artikel ini membahas autentikasi terdelegasi interaktif menggunakan modul Microsoft Graph v1.0. Otentikasi hanya aplikasi untuk tugas terjadwal tanpa pengawasan memerlukan pertimbangan desain terpisah seperti izin aplikasi dan sertifikat, dan berbeda dari menjalankan tugas terjadwal menggunakan contoh masuk pengguna yang sama.
Persyaratan dan Instalasi Modul
Microsoft menyarankan PowerShell 7 atau yang lebih baru. Lakukan latihan berikut dalam lingkungan PowerShell 7 yang didukung. Windows PowerShell 5.1 memerlukan .NET Framework, PowerShellGet, dan prasyarat lainnya secara terpisah, dan modul yang diinstal di satu versi tidak otomatis diinstal di versi lain. Pertama, periksa persyaratan instalasi SDK.
- Buka PowerShell di PC administrasi yang disetujui organisasi. Periksa versinya dengan
$PSVersionTable.PSVersion. - Di pusat admin Microsoft Entra, periksa ID tenant target di bawah Entra ID → Overview. Ini sangat penting jika akun Anda memiliki akses ke beberapa organisasi.
- Konfirmasikan persetujuan admin untuk izin Graph dan peran administrasi Anda sendiri. Gunakan akun perusahaan atau sekolah dari organisasi Anda, bukan akun Microsoft pribadi biasa.
- Buat folder terbatas untuk menyimpan file hasil. Karena daftar pengguna berisi nama dan alamat akun, jangan gunakan penyimpanan publik atau folder web publik.
Untuk menginstal hanya modul yang diperlukan untuk lingkup pengguna saat ini, jalankan seperti berikut. Jika pesan konfirmasi instalasi muncul, periksa repositori dan paket. Menginstal modul Microsoft.Graph secara penuh juga memungkinkan, tetapi untuk latihan ini, submodul di bawah ini sudah cukup.
Install-Module -Name Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions -Scope CurrentUser -Repository PSGallery
Setelah instalasi, periksa versi yang tersedia dan nama perintah menggunakan perintah berikut. Pada langkah ini, tidak terhubung ke data organisasi.
Get-Module -ListAvailable Microsoft.Graph.Authentication,Microsoft.Graph.Users,Microsoft.Graph.Identity.DirectoryManagement,Microsoft.Graph.Users.Actions | Select-Object Name,Version
Get-Command Connect-MgGraph,Get-MgUser,Get-MgSubscribedSku,Set-MgUserLicense
Jika modul atau skrip diblokir karena kebijakan eksekusi, periksa terlebih dahulu bagian kebijakan eksekusi. Jangan menganggap kesalahan kebijakan sebagai masalah seperti kesalahan izin 403.
Membedakan izin koneksi dan peran admin
Autentikasi terdelegasi adalah metode yang bekerja atas nama pengguna yang sedang masuk. -Scopes adalah ruang lingkup izin Graph yang diminta oleh aplikasi, dan juga harus memenuhi ruang lingkup peran/target dari admin yang masuk dan persetujuan admin. Menulis nama dalam -Scopes saja tidak secara otomatis menyetujui izin tersebut atau membuat peran admin.
| Tugas | Izin Graph yang diminta dalam contoh | Pemeriksaan tambahan |
|---|---|---|
| Lihat daftar pengguna dan atribut yang ditentukan | User.Read.All |
Persetujuan admin dan pembatasan atribut untuk dikueri |
| Kueri SKU langganan dan lisensi pengguna | LicenseAssignment.Read.All |
Peran yang didukung oleh API, seperti Pembaca Direktori |
| Membuat pengguna cloud | User.Create |
Persetujuan administrator serta izin dan target manajemen pengguna |
| Menetapkan dan mencabut lisensi | LicenseAssignment.ReadWrite.All |
Peran yang didukung, seperti Administrator Lisensi |
Untuk latihan membaca, tidak perlu meminta izin modifikasi grup atau izin tulis direktori penuh sekaligus. Izin yang didelegasikan versus izin aplikasi dan persyaratan persetujuan administrator dapat diperiksa di Referensi izin Microsoft Graph.
Untuk menguji perintah query individu, sambungkan seperti ditunjukkan di bawah ini. ID tenant yang Anda masukkan harus merupakan nilai aktual yang dikonfirmasi di organisasi Anda, dan setelah masuk, periksa Account·TenantId·Scopes. Metode login dapat menggunakan browser atau jendela autentikasi Windows tergantung pada versi dan lingkungan yang terpasang.
$tenantId = Read-Host 'ID tenant target'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,AuthType,Scopes
-ContextScope Process membatasi konteks autentikasi pada proses PowerShell saat ini. Ketika Connect-MgGraph dipanggil tanpa cakupan yang eksplisit, periksa konteks aktual alih-alih mengasumsikan izin selalu User.Read. Untuk mengganti akun atau cakupan, jalankan Disconnect-MgGraph dan sambungkan kembali dengan cakupan yang diperlukan. Lihat Panduan autentikasi PowerShell Graph.
Contoh lengkap pencarian pengguna dan penyimpanan CSV
Get-MgUser -All terus-menerus mengambil daftar pengguna yang dikembalikan dalam halaman. Namun, ini tidak berarti secara otomatis menerima semua properti. Select-Object * hanya memperluas properti dari objek yang sudah diterima, dan nilai yang tidak termasuk dalam pengembalian default harus diminta dari server dengan -Property. Perbedaan ini dijelaskan dalam Deskripsi Get-MgUser.
Simpan kode lengkap berikut sebagai UTF-8 dengan m365-users-report.ps1. Skrip ini membaca informasi pengguna, membuat CSV dengan stempel waktu di folder yang sama, dan memutuskan sesi. Ini tidak mengubah akun atau lisensi. Jika Anda telah melakukan latihan koneksi sebelumnya, pertama hentikan dengan Disconnect-MgGraph lalu jalankan ini.
param(
[Parameter(Mandatory)]
[Guid]$TenantId
)
$ErrorActionPreference = 'Stop'
$connected = $false
$file = Join-Path $PSScriptRoot ("m365-users-{0}.csv" -f (Get-Date -Format 'yyyyMMdd-HHmmss'))
try {
Connect-MgGraph -TenantId $TenantId.ToString() -Scopes 'User.Read.All' -ContextScope Process -NoWelcome
$connected = $true
$context = Get-MgContext
if ($context.TenantId -ne $TenantId.ToString()) {
throw 'Tenant yang terhubung tidak sesuai dengan tenant yang diminta.'
}
$properties = 'Id','DisplayName','UserPrincipalName','Mail','AccountEnabled','UsageLocation','AssignedLicenses'
$users = @(Get-MgUser -All -Property $properties)
if ($users.Count -eq 0) {
throw 'Tidak ada pengguna yang dikembalikan. Periksa koneksi dan izin.'
}
$report = @($users | Select-Object Id,DisplayName,UserPrincipalName,Mail,AccountEnabled,UsageLocation,
@{Name='AssignedSkuCount';Expression={ @($_.AssignedLicenses | Where-Object { $null -ne $_ }).Count }})
$report | Export-Csv -Path $file -NoTypeInformation -Encoding utf8BOM -NoClobber
Write-Host ("Disimpan: {0} / Jumlah pengguna: {1}" -f $file, $report.Count)
$report | Select-Object -First 5 | Format-Table DisplayName,UserPrincipalName,AssignedSkuCount -AutoSize
}
finally {
if ($connected) {
Disconnect-MgGraph -ErrorAction SilentlyContinue | Out-Null
}
}
Setelah pindah ke folder tempat file berada di PowerShell, jalankan sebagai berikut. Sesuaikan jalur file dengan lokasi penyimpanan yang sebenarnya, dan tempelkan ID penyewa organisasi Anda ke bidang input.
$targetTenant = Read-Host 'ID tenant target'
.\m365-users-report.ps1 -TenantId $targetTenant
Jika berhasil, jalur CSV dan jumlah pengguna akan ditampilkan, dan lima pengguna pertama akan ditunjukkan di layar. Bandingkan jumlah baris dalam file dengan jumlah pengguna di layar, dan periksa nama tampilan, alamat login, lokasi penggunaan, dan lisensi dari satu akun uji yang diketahui dengan pusat admin. AssignedSkuCount menunjukkan jumlah SKU produk yang ditugaskan, bukan jumlah layanan individu atau kuota lisensi yang dibeli.
Bahkan jika ada pengguna dengan Mail yang kosong, jangan langsung menganggap query gagal. Nama login, UserPrincipalName, dan alamat email adalah atribut yang berbeda. Bahkan jika AccountEnabled benar, login aktual atau penggunaan layanan mungkin dibatasi karena lisensi, kebijakan, atau penilaian risiko. Jangan menyimpulkan hanya dari laporan ini bahwa seorang pengguna baru saja login atau sedang melakukan pekerjaan secara normal.
Jika tidak ada hasil yang dikembalikan atau pembuatan CSV gagal, jangan tandai sebagai selesai. Periksa izin untuk jalur output, file dengan nama yang sama, kunci file, dan pesan kesalahan. Karena laporan mencerminkan hasil query pada saat eksekusi, jika akun telah berubah, jalankan lagi untuk perbandingan, dan kelola file sebelumnya sesuai dengan kebijakan retensi organisasi Anda.
Menanyakan produk lisensi dan penugasan pengguna
SKU (Stock Keeping Unit) adalah unit yang digunakan di sini untuk membedakan produk berlisensi. SkuPartNumber adalah string identifikasi produk, dan SkuId adalah pengenal unik global produk (GUID) yang digunakan dalam perintah Graph. Saat mengubah penugasan pengguna, bedakan agar Anda tidak memasukkan ID objek langganan atau ID rencana layanan sebagai gantinya SKU ID.
Seluruh skrip CSV terputus di akhir, jadi saat menjalankan perintah individual di bawah, sambungkan kembali setiap kali. Selain izin baca, peran yang didukung oleh operasi tersebut diperlukan untuk menanyakan SKU langganan. Periksa Peran dan Izin untuk API Permintaan SKU Langganan.
$tenantId = Read-Host 'ID tenant target'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Read.All','LicenseAssignment.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
Get-MgSubscribedSku -All | Select-Object SkuPartNumber,SkuId,CapabilityStatus,ConsumedUnits,@{Name='EnabledUnits';Expression={$_.PrepaidUnits.Enabled}}
$userId = Read-Host 'Nama utama pengguna (UPN) atau ID objek yang diperiksa'
Get-MgUserLicenseDetail -UserId $userId -All | Select-Object SkuPartNumber,SkuId,ServicePlans
ConsumedUnits adalah jumlah lisensi yang digunakan, dan PrepaidUnits.Enabled adalah unit yang tersedia. Karena mungkin ada status ditangguhkan, peringatan, dan kondisi produk, jangan langsung mengartikan selisih sederhana sebagai jumlah yang ditagih atau sisa kuota lisensi untuk semua produk. Detail pembelian dan tagihan yang sebenarnya harus dikonfirmasi secara terpisah melalui Prosedur Rekonsiliasi Langganan, Penagihan, dan Jumlah Lisensi.
Get-MgUserLicenseDetail mencakup lisensi yang ditugaskan langsung dan diturunkan dari grup. Anda tidak dapat membedakan penyebab penugasan hanya dari hasil ini. Untuk penugasan berbasis grup, periksa juga pusat admin atau informasi status penugasan. Dalam Detail Lisensi Pengguna API, Anda juga dapat memverifikasi izin yang didelegasikan dan peran yang didukung.
Jalankan operasi perubahan pengguna dan lisensi secara terpisah.
Contoh berikut menunjukkan operasi yang memodifikasi data organisasi. Jangan jalankan secara batch segera setelah laporan baca; sambungkan kembali dengan izin yang diperlukan setelah menyiapkan pengguna uji dan catatan yang disetujui sebelum perubahan. Opsi -WhatIf di bawah ini memungkinkan Anda untuk melihat pratinjau operasi yang ingin dijalankan dan bukan tes tiruan yang memverifikasi semua validasi server, izin, dan kondisi lisensi.
Buat pengguna uji cloud.
Gunakan metode ini hanya untuk pengguna yang dikelola cloud. Dalam organisasi yang disinkronkan, pertama tentukan apakah akun harus dibuat di direktori sumber. Pilih nama utama pengguna (UPN, nama untuk masuk) yang unik dalam domain yang telah diverifikasi di tenant, dan kata sandi sementara yang memenuhi kebijakan kata sandi tersebut. Membuat pengguna anggota berbeda dari mengundang tamu kolaborasi eksternal. Tinjau persyaratan dan izin API pembuatan pengguna, termasuk izin pembuatan dengan hak paling terbatas User.Create, dan konfirmasikan peran administratif serta ruang lingkup target.
Disconnect-MgGraph
$tenantId = Read-Host 'ID tenant target'
Connect-MgGraph -TenantId $tenantId -Scopes 'User.Create','User.Read.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
$upn = Read-Host 'UPN pengguna uji yang akan dibuat (domain terverifikasi)'
$nickname = Read-Host 'Alias email (misalnya graph-test01)'
$securePassword = Read-Host 'Kata sandi sementara yang memenuhi kebijakan' -AsSecureString
$params = @{
AccountEnabled = $true
DisplayName = 'Pengguna uji Graph'
UserPrincipalName = $upn
MailNickname = $nickname
PasswordProfile = @{
Password = [System.Net.NetworkCredential]::new('', $securePassword).Password
ForceChangePasswordNextSignIn = $true
}
}
try {
New-MgUser -BodyParameter $params -WhatIf
}
finally {
$params.PasswordProfile.Password = $null
Remove-Variable securePassword
}
Setelah memverifikasi input dan target, untuk benar-benar membuat pengguna, hapus -WhatIf dari kode dan jalankan lagi. Jangan menyimpan kata sandi secara hard-code di string baris perintah atau file skrip. Karena permintaan SDK memerlukan nilai kata sandi dalam teks biasa, jangan menggunakan output debug atau pencatatan tubuh permintaan untuk tugas ini, dan sampaikan kata sandi sementara melalui saluran yang disetujui organisasi.
Setelah pembuatan, verifikasi akun lagi menggunakan Get-MgUser -UserId $upn -Property Id,DisplayName,UserPrincipalName,AccountEnabled. Hanya membuat pengguna tidak secara otomatis menyelesaikan lisensi aplikasi, kotak surat, atau keanggotaan grup. Menghapus akun uji juga memerlukan tinjauan data serupa dengan menghapus akun bisnis. Periksa prosedur offboarding dan penyerahan data, lalu tinjau dan atur target serta ruang lingkup yang dapat dipulihkan di pusat admin.
Ambil kembali lisensi yang ditugaskan langsung
Sebelum mengambil kembali, periksa pengguna, produk, apakah itu ditugaskan secara langsung atau melalui grup, dan persyaratan retensi data. Dalam contoh ini, -RemoveLicenses menerima sebuah array string ID SKU, tetapi tidak menyertakan tabel hash dalam format @{SkuId=...}. Gunakan -AddLicenses @() bersama-sama ketika tidak ada produk tambahan yang akan ditambahkan. Periksa sintaks Set-MgUserLicense.
Disconnect-MgGraph
$tenantId = Read-Host 'ID tenant target'
Connect-MgGraph -TenantId $tenantId -Scopes 'LicenseAssignment.ReadWrite.All' -ContextScope Process
Get-MgContext | Select-Object Account,TenantId,Scopes
$userId = Read-Host 'UPN atau ID objek pengguna uji untuk pencabutan lisensi'
$skuId = [Guid](Read-Host 'SkuId terverifikasi dari lisensi yang dicabut')
Set-MgUserLicense -UserId $userId -AddLicenses @() -RemoveLicenses @($skuId.ToString()) -WhatIf
Jalankan perubahan hanya setelah persetujuan dan verifikasi target, dengan menghapus -WhatIf. Diperlukan persetujuan untuk LicenseAssignment.ReadWrite.All serta peran yang didukung, misalnya Administrator Lisensi. Untuk lisensi yang diwarisi dari grup, tinjau penugasan grup asal; penghapusan langsung dari pengguna tidak menggantikan pengelolaan penugasan grup. Lihat izin, peran, dan format permintaan API penugasan lisensi.
Setelah perubahan, sambungkan kembali dengan izin baca yang diperlukan dan bandingkan detail lisensi dengan pusat manajemen. Selama rollback, Anda perlu memverifikasi kuota lisensi yang tersedia, lokasi penggunaan, dan paket layanan yang sebelumnya dinonaktifkan untuk ditugaskan kembali ke konfigurasi asli. Jangan menganggap bahwa pemasangan ulang lisensi akan membatalkan semua penghapusan data yang sebelumnya dijalankan. Penting untuk memastikan retensi dan penyerahan data sebelum mengambil kembali.
Periksa kebijakan eksekusi Windows dan lakukan rollback
Kebijakan eksekusi adalah kondisi untuk menjalankan skrip dan modul. Jika terjadi kesalahan yang memblokir di Windows, periksa kebijakan yang berlaku dan nilai menurut ruang lingkup.
Get-ExecutionPolicy
Get-ExecutionPolicy -List
Hanya jika kebijakan organisasi mengizinkan dan lingkup pengguna saat ini perlu diubah, catat nilai sebelumnya dan tinjau RemoteSigned. Jika pengaturan sudah diizinkan, jangan ubah hanya untuk menyesuaikan format. Jika MachinePolicy dan UserPolicy dari kebijakan grup organisasi lebih diutamakan, periksa dengan orang yang bertanggung jawab dan jangan melewati.
$previousUserPolicy = Get-ExecutionPolicy -Scope CurrentUser
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
Get-ExecutionPolicy -List
Untuk mengembalikan nilai semula setelah selesai, jalankan perintah berikut dalam sesi yang sama. Jika memakai jendela baru, gunakan nilai sebenarnya yang telah dicatat. RemoteSigned tidak berarti semua kode dari internet dapat dipercaya. Lihat cakupan dan prioritas kebijakan eksekusi PowerShell.
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy $previousUserPolicy
Kesalahan umum dan penghentian tugas
| Gejala | Urutan Verifikasi |
|---|---|
| Perintah Tidak Dikenal | Periksa versi PowerShell yang sedang berjalan dan lokasi instalasi modul. Get-MgUser ada di Microsoft.Graph.Users. Gunakan Get-Command untuk menemukan perintah dan membedakan antara kesalahan instalasi dan impor. |
| 403 atau Hak Istimewa Tidak Cukup | Verifikasi akun yang terhubung, tenant, ruang lingkup, persetujuan admin, dan peran yang didukung untuk API. Jangan menambahkan izin tulis penuh secara default. |
| Tidak Dapat Menemukan Pengguna atau Objek | Periksa organisasi dan UPN/ID objek, serta status penghapusan/sinkronisasi. Pastikan nama akun tidak berasal dari tenant yang berbeda. |
| Properti Kosong | Bedakan apakah properti diminta dengan -Property, apakah akun benar-benar memiliki nilai, dan apakah properti memerlukan izin terpisah. |
| Login Diblokir | Catat kode kesalahan dan stempel waktu, serta periksa akses bersyarat, autentikasi multifaktor (MFA), metode autentikasi yang diizinkan, dan log login. Jangan menonaktifkan kebijakan keamanan untuk login yang berhasil. |
Merekam versi instalasi, kesalahan perintah secara rinci, ID permintaan, dan waktu terjadinya secara bersamaan dapat membantu dalam reproduksi dan permintaan dukungan. Bahkan saat menggunakan metode di diagnosis kesalahan Graph PowerShell, jangan membagikan log yang berisi token, kata sandi, atau informasi pribadi secara langsung.
Setelah menyelesaikan latihan perintah individual, putuskan sambungan dan periksa lokasi penyimpanan file hasil. Keluar dari sistem berbeda dengan membatalkan perubahan akun atau lisensi yang sudah dilakukan.
Disconnect-MgGraph




