Microsoft Graph PowerShell untuk admin SharePoint: perintah pertama
By Mirko Peters · · Updated
Microsoft Graph PowerShell untuk SharePoint: instal SDK, masuk dengan scope yang tepat, daftar situs dengan Get-MgSite, dan atasi error 403 yang paling sering dialami admin.
Automatically translated with AI from the original post. Read the English original
Microsoft Graph PowerShell untuk SharePoint berarti menggunakan SDK Graph untuk membaca dan mengelola situs dari baris perintah. Anda menginstal satu modul, masuk dengan Connect-MgGraph dan sebuah scope izin, lalu menjalankan cmdlet seperti Get-MgSite. Panduan ini ditujukan bagi admin SharePoint yang sudah memahami pusat admin SharePoint dan ingin memulai скрипт dengan aman. Anda akan menginstal SDK, masuk dengan scope terkecil yang dapat berfungsi, mendaftar situs, dan memahami cara membaca error yang pertama kali muncul.
Poin Penting
- Microsoft Graph PowerShell adalah SDK yang membungkus API Graph, sehingga setiap perintah memerlukan masuk dengan Connect-MgGraph terlebih dahulu beserta scope izin yang tepat.
- Get-MgSite mendaftar situs SharePoint dan memerlukan izin Sites.Read.All sebagai minimum, yaitu opsi dengan hak akses terendah yang didokumentasikan Microsoft untuk perintah tersebut.
- Get-MgContext menampilkan scope yang dimiliki sesi Anda saat ini, yang merupakan cara tercepat untuk menjelaskan error 403 Forbidden.
- Find-MgGraphCommand dan Find-MgGraphPermission memberi tahu Anda izin yang dibutuhkan suatu perintah, sehingga Anda tidak perlu menebak nama scope.
- Masuk delegasi cocok untuk seseorang yang duduk di depan keyboard, sedangkan masuk khusus aplikasi dengan sertifikat atau managed identity cocok untuk pekerjaan tanpa pengawasan.
Apa itu Microsoft Graph PowerShell dan mengapa admin menggunakannya
Microsoft Graph adalah API tunggal untuk data Microsoft 365: pengguna, grup, file, surat, Teams, dan situs SharePoint. SDK PowerShell Microsoft Graph membungkus API Graph dalam cmdlet. Anda tidak perlu menulis permintaan web ke setiap endpoint. Anda cukup menjalankan Get-MgSite dan menerima objek situs kembali.
Bagi admin SharePoint, ada tiga manfaat praktis.
- Satu alat untuk berbagai layanan. Masuk yang sama berlaku untuk situs, pengguna, dan grup. Sebuah skrip dapat mendaftar situs, lalu mencari pemiliknya.
- Model izin yang dapat Anda baca. Setiap panggilan memerlukan izin bernama, yang disebut scope. Anda dapat melihat scope apa saja yang dimiliki sebuah sesi dan alasan panggilan ditolak.
- Jalan keluar dari modul lama. Catatan entitas untuk Microsoft Graph PowerShell menyebutnya sebagai pengganti modul Azure AD PowerShell dan MSOnline yang sudah dihentikan.
Modul komunitas PnP PowerShell adalah pilihan umum lainnya untuk skrip SharePoint, dan dokumentasinya mencatat bahwa beberapa cmdlet juga berkomunikasi dengan Graph. Graph PowerShell tidak menggantikan setiap alat admin SharePoint. Modul ini mencakup apa yang diekspos oleh API Graph. Beberapa pengaturan penyewa masih berada di pusat admin SharePoint atau di modul lain. Anggap Graph sebagai salah satu alat dalam kumpulan Anda, bukan satu-satunya.
Langkah 1: instal SDK dan masuk
Panduan instalasi merekomendasikan PowerShell 7 atau yang lebih baru di semua platform. Windows PowerShell memerlukan versi 5.1 atau yang lebih baru, .NET Framework 4.7.2 atau yang lebih baru, dan execution policy RemoteSigned atau yang lebih longgar.
Ikuti langkah-langkah berikut:
- Instal modul untuk akun Anda sendiri:
Install-Module Microsoft.Graph -Scope CurrentUser -Repository PSGallery -Force. Gunakan-Scope AllUsershanya jika Anda memiliki hak admin dan membutuhkan instalasi bersama. - Periksa hasilnya dengan
Get-InstalledModule Microsoft.Graph. - Perlu diketahui bahwa modul utamanya menginstal lebih dari 47 sub-modul. Halaman tersebut menjelaskan bahwa Anda dapat menginstal hanya sub-modul yang dibutuhkan, dan
Microsoft.Graph.Authenticationikut terinstal bersamanya. - Perbarui nanti dengan
Update-Module Microsoft.Graph. Modul yang sudah usang tercantum sebagai salah satu penyebab konflik versi.
Menginstal di satu versi PowerShell tidak otomatis menginstalnya di versi lain, jadi jalankan perintah di versi yang akan Anda gunakan.
Sekarang masuk (sign in). Halaman tentang perintah autentikasi menjelaskan bahwa SDK mendukung dua jenis akses: delegated dan app-only. Akses delegated bertindak atas nama pengguna yang sudah masuk, dan izinnya berupa scope. Akses app-only berjalan tanpa pengguna, dengan sertifikat, client secret, atau managed identity.
Untuk perintah pertama Anda, gunakan akses delegated dan minta satu scope hanya-baca:
Connect-MgGraph -Scopes "Sites.Read.All"
Jendela browser akan terbuka untuk proses masuk. Untuk memeriksa apa yang Anda dapatkan, jalankan Get-MgContext | Select -ExpandProperty Scopes. Microsoft mendokumentasikan Get-MgContext sebagai perintah yang mengembalikan detail sesi Anda saat ini, seperti client ID, tenant ID, scope, dan jenis autentikasi. Setelah selesai, jalankan Disconnect-MgGraph. Halaman tersebut menjelaskan bahwa Anda tetap masuk sampai Anda melakukannya, karena token disimpan dalam cache di bawah scope default CurrentUser. Tambahkan -ContextScope Process ke Connect-MgGraph jika Anda ingin sesi masuk hanya berlaku untuk sesi saat ini.
Perintah pertama untuk situs SharePoint
Referensi untuk Get-MgSite mencantumkan parameter utamanya: -Filter, -Search, -Property (alias -Select), -Top, -Sort, dan -All. Contoh dari halaman tersebut cukup singkat:
Get-MgSitemenampilkan daftar situs.Get-MgSite -Property "siteCollection,webUrl" -Filter "siteCollection/root ne null"hanya mengembalikan root site collection, dengan dua properti.
Lanjutkan dari sana:
- Daftar dengan paging. Jalankan
Get-MgSite -Alluntuk menelusuri setiap halaman hasil. Tanpa-All, Anda mungkin hanya melihat halaman pertama. - Pilih kolom. Tambahkan
-Property "id,displayName,webUrl"agar keluarannya tetap ringkas dan mudah dibaca. - Cari berdasarkan kata kunci. Jalankan
Get-MgSite -Search "finance". API pencarian Graph mencocokkan teks bebas di beberapa properti situs. - Ambil satu situs. Jalankan
Get-MgSite -SiteId <id>, dengan ID adalah nilaiiddari hasil sebelumnya. Formatnya berupa nama host, lalu dua GUID, dipisahkan dengan koma.
Setiap cmdlet ini dipetakan ke panggilan REST. Get-MgSite -All membaca koleksi sites di https://graph.microsoft.com/v1.0/sites, URL yang ditampilkan dokumentasi REST untuk daftar situs, dan -Filter, -Search, serta -Property menjadi opsi kueri pada URL tersebut. SDK memperoleh token melalui Microsoft Authentication Library (MSAL). Jika cmdlet untuk panggilan yang Anda butuhkan tidak tersedia, Invoke-MgGraphRequest dapat memanggil URI secara langsung. Halaman pemecahan masalah menggunakannya untuk memeriksa URI di balik galat Bad request.
Ada dua batasan yang penting. Pertama, endpoint daftar Graph mengembalikan situs dalam geografi default organisasi. Untuk semua geografi, Microsoft merujuk ke API getAllSites, yang sesuai dengan cmdlet Get-MgAllSite. Kedua, API pencarian hanya dapat mengurutkan berdasarkan createdDateTime.
Izin apa yang Anda butuhkan? Microsoft Graph PowerShell dan scope SharePoint
Izin Microsoft Graph adalah bagian yang sering mengejutkan pengguna baru. Untuk membaca situs, halaman cmdlet mencantumkan Sites.Read.All sebagai pilihan dengan hak istimewa paling rendah dan Sites.ReadWrite.All sebagai pilihan dengan hak istimewa lebih tinggi. Pilih yang pertama, kecuali skrip memang harus mengubah sesuatu.
Anda tidak perlu menghafal nama cakupan. Dua perintah bantu melakukan pencarian:
Find-MgGraphCommandmenampilkan izin yang dibutuhkan oleh sebuah cmdlet atau API. Halaman pemecahan masalah menggunakanFind-MgGraphCommand -command New-MgServicePrincipal | Select -First 1 -ExpandProperty Permissionssebagai contohnya.Find-MgGraphPermissionmencari izin berdasarkan area atau nama, misalnyaFind-MgGraphPermission application. Keluarannya menampilkan jenis (delegated atau application), apakah persetujuan harus diberikan oleh admin, dan deskripsinya.
Perhatikan satu hal yang tidak konsisten dalam dokumentasi. Halaman REST untuk mencantumkan situs hanya menampilkan izin aplikasi untuk panggilan tersebut dan menandai akses delegated sebagai tidak didukung. Halaman cmdlet untuk Get-MgSite mencantumkan keduanya. Uji panggilan Anda sendiri di penyewa nonproduksi dan baca teks kesalahannya jika gagal. Jangan berasumsi bahwa halaman cmdlet selalu benar untuk setiap panggilan.
Untuk tugas tanpa pengawasan, Anda memerlukan akses khusus aplikasi (app-only). Artinya, pendaftaran aplikasi di Microsoft Entra, izin aplikasi (juga disebut izin API), dan persetujuan administrator. Halaman pemecahan masalah menyebutkan bahwa izin aplikasi memerlukan persetujuan administrator. Gunakan sertifikat atau identitas terkelola, bukan kata sandi yang diketik.
Contoh: inventaris situs yang tidak lagi aktif dalam lima perintah
Angka dalam contoh ini bersifat fiktif.
Seorang admin ingin membuat daftar awal situs yang tidak ada seorang pun ubah selama setahun.
Connect-MgGraph -Scopes "Sites.Read.All"$sites = Get-MgSite -All -Property "id,displayName,webUrl,lastModifiedDateTime"$sites.Countmenghasilkan 480 dalam contoh ini.$old = $sites | Where-Object { $_.LastModifiedDateTime -lt (Get-Date).AddYears(-1) }$old | Select DisplayName, WebUrl, LastModifiedDateTime | Export-Csv stale-sites.csv -NoTypeInformation
Misalkan file tersebut berisi 60 baris. Itu berarti 60 dari 480, atau 12,5 persen, daftar yang cukup singkat untuk ditinjau bersama pemilik situs. Admin hanya memiliki akses baca dan tidak mengubah apa pun. Tanggal terakhir diubah pada sebuah situs tidak membuktikan bahwa tidak ada yang menggunakannya, jadi daftar ini adalah titik awal untuk mengajukan pertanyaan, bukan daftar untuk dihapus.
Kesalahan umum
- Terhubung tanpa cakupan. Masuk tanpa cakupan yang tepat menyebabkan kesalahan 403. Jalankan
Get-MgContextdan bandingkan cakupan yang aktif dengan yang dibutuhkan cmdlet. - Meminta cakupan tulis untuk pekerjaan baca.
Sites.ReadWrite.Alllebih dari yang dibutuhkan sebuah laporan. Mulailah denganSites.Read.All. - Lupa
-All. Tanpa parameter ini, daftar bisa tampak lengkap padahal hanya halaman pertama. - Keliru dengan versi modul. Microsoft merekomendasikan modul v1.0 untuk skrip. Modul beta masih pratinjau dan dapat berubah tanpa pemberitahuan.
- Melewatkan pembaruan. Versi
Microsoft.Graphyang lama tercantum sebagai salah satu penyebab konflik versi. JalankanUpdate-Module Microsoft.Graphsebelum menelusuri penyebab lain. - Tetap masuk di mesin bersama. Token disimpan dalam cache. Jalankan
Disconnect-MgGraphsetelah selesai.
Bagaimana perangkat lunak dapat membantu
Sebagian besar kebutuhan pertama bisa dipenuhi dengan alat yang sudah Anda miliki. Microsoft Graph PowerShell SDK menangani pembacaan dan ekspor. Pusat admin SharePoint menampilkan daftar dan pengaturan situs tanpa kode. Excel atau Power BI mengubah CSV menjadi laporan yang mudah dibaca pemilik situs. Untuk proses terjadwal, Azure Automation dapat menjalankan skrip dengan identitas terkelola.
Cari celah hanya setelah bulan pertama. Jika Anda terus menyusun ulang inventaris yang sama secara manual, skrip yang disimpan dengan folder output tetap dan pengingat bulanan biasanya sudah cukup.
Langkah berikutnya
Pasang SDK, jalankan Connect-MgGraph -Scopes "Sites.Read.All", dan ekspor keluaran Get-MgSite -All ke CSV hari ini. Setelah itu, gunakan Find-MgGraphCommand pada cmdlet berikutnya untuk mengetahui izinnya sebelum Anda menjalankan tugas SharePoint dengan Microsoft Graph PowerShell di lingkungan produksi.