สร้างรายงานไฟล์ SharePoint Online ด้วย Graph PowerShell SDK

การอัปเดตสคริปต์รายงานไฟล์ SharePoint Online เพื่อใช้กราฟ PowerShell SDK

ในเดือนกรกฎาคม 2022 ฉันเขียนเกี่ยวกับการใช้ Graph API เพื่อรายงานไฟล์ในไลบรารีเอกสาร SharePoint Online โครงสร้างสคริปต์ตรงไปตรงมา: เลือกไซต์ เลือกไลบรารีเอกสารภายในไซต์ และรายงานไฟล์และโฟลเดอร์ที่พบในไลบรารี นี่เป็นโอกาสแรกของฉันที่ได้ทำงานกับ SharePoint Online โดยใช้ Graph API และเป็นประสบการณ์การเรียนรู้อันล้ำค่า

เวลาและเทคโนโลยีเดินหน้าต่อไป และเป็นไปได้ที่จะทำงานเดียวกันด้วย Microsoft Graph PowerShell SDK ฉันชอบใช้ Graph PowerShell SDK เมื่อเป็นไปได้เพราะทำงานง่ายกว่า Cmdlet จะต่ออายุโทเค็นการเข้าถึงเมื่อจำเป็น และดูแลการแบ่งหน้าเมื่อดึงข้อมูล Cmdlet ของผลลัพธ์วัตถุ PowerShell และอื่นๆ แน่นอนว่า Graph PowerShell SDK มีข้อบกพร่องที่น่ารำคาญ แต่โดยทั่วไปแล้วฉันพยายามใช้ cmdlets แทนคำขอ Graph API ทุกครั้งที่เป็นไปได้

Microsoft เปิดตัว Graph PowerShell SDK เวอร์ชัน 2 ในปี 2023 ฉันตัดสินใจเขียนสคริปต์ใหม่เพื่อใช้ Graph SDK cmdlets เพื่อสำรวจว่า SDK มีความสามารถในการจัดการกับเนื้อหา SharePoint Online ได้อย่างไร Microsoft มี API กราฟแสดงตัวอย่างสำหรับการจัดการ SharePoint Online ที่เลียนแบบฟังก์ชันการทำงานบางอย่างที่มีอยู่ในโมดูล PowerShell การจัดการ SharePoint Online ไม่มีความคืบหน้ามากนักในการพัฒนาโมดูลนี้ และฉันไม่ได้กล่าวถึงที่นี่

SharePoint Online รวมตัวเลือกส่งออกไปยัง Excel ในเมนูจุดไข่ปลา ตัวเลือกนี้จะสร้างไฟล์ Microsoft Excel Web Query (.iqy) เพื่อเชื่อมต่อกับตำแหน่งปัจจุบันในไซต์ SharePoint และส่งออกข้อมูลเกี่ยวกับรายการและโฟลเดอร์ไปยังตารางในสมุดงาน Excel เป็นประโยชน์อย่างยิ่งที่การส่งออกจะรวมคุณสมบัติทั้งหมดที่แสดงในมุมมองเริ่มต้น คุณสามารถใช้ตัวเลือกนี้แทนสคริปต์ที่ฉันกำลังจะอธิบาย แต่คุณจะไม่ได้เรียนรู้วิธีการโต้ตอบกับ SharePoint Online โดยใช้ Graph SDK cmdlets!

ไซต์ ไดรฟ์ และรายการไดรฟ์

ผู้คนคุ้นเคยกับแนวคิดของไซต์ SharePoint Online สคริปต์เริ่มต้นด้วยการใช้ Get-MgSite cmdlet เพื่อค้นหาไซต์ที่มีชื่อที่แสดงหรือคำอธิบายที่ตรงกัน ตัวอย่างแรกค้นหาโดยใช้สตริง ตัวอย่างที่สองใช้ตัวแปร:

Get-MgSite -Search 'Projects'
$SiteName = 'Office 365'
Get-MgSite -Search ($SiteName)

SharePoint Online จะเล็มชุดของไซต์เพื่อแยกไซต์ใดๆ ที่ผู้ใช้ที่ลงชื่อเข้าใช้ไม่สามารถเข้าถึงได้ แม้แต่บัญชีที่มีบทบาทผู้ดูแลระบบ SharePoint หรือผู้ดูแลระบบส่วนกลางก็ไม่สามารถเข้าถึงไซต์ได้เว้นแต่จะเป็นสมาชิกของไซต์ ชุดไซต์ที่ส่งคืนโดย Get-MgSite ประกอบด้วยไซต์ที่สร้างขึ้นสำหรับช่องทางส่วนตัวและช่องทางที่ใช้ร่วมกันของ Teams สคริปต์จัดการสิ่งนี้โดยขอให้ผู้ใช้เลือกไซต์ ค่าที่ส่งคืนจะมีตัวระบุไซต์ซึ่งมีลักษณะดังนี้:

Office365itpros.sharepoint.com,acfe74d8-edfb-436d-924b-e018666605ee,a2aba197-5f1d-4864-a2c7-4daf0ff6379b

ไซต์ SharePoint Online มีไลบรารีเอกสารเริ่มต้นที่เรียกว่าเอกสาร (เป็นภาษาอังกฤษ) อย่างไรก็ตาม ไซต์สามารถขยายไลบรารีเอกสารได้หลายไลบรารี ในแง่ API สิ่งเหล่านี้เรียกว่าไดรฟ์ Get-MgSiteDrive cmdlet จะดึงข้อมูลชุดของไดรฟ์ในไซต์:

[array]$Drives = Get-MgSiteDrive -SiteId $Site.Id

แต่ละไดรฟ์มีตัวระบุ (Id) ที่มีลักษณะดังนี้:

b!2HT-rPvtbUOSS-AYZmYF7pehq6IdX2RIosdNrw_2N5t7xp_DBXMQTalVjpKlwdxk

ด้วยตัวระบุไซต์และตัวระบุไดรฟ์ เราสามารถดึงข้อมูลรายการ (รายการไดรฟ์) ในไดรฟ์ได้ ไดรฟ์ประกอบด้วยไฟล์และโฟลเดอร์ ดังนั้นงานบางอย่างจึงจำเป็นในการประมวลผลรายการทั้งสองประเภท สคริปต์มีฟังก์ชันที่เรียกว่า Get-DriveItems เพื่อประมวลผลไฟล์ในโฟลเดอร์ รวมถึงการประมวลผลรายการในโฟลเดอร์ที่ซ้อนกันแบบเรียกซ้ำ ในการเริ่มต้น สคริปต์เริ่มต้นที่โฟลเดอร์รูท (ระดับบนสุด):

Get-DriveItems -Drive $Drive.Id -FolderId "root"

ข้อมูลที่รวบรวมสำหรับแต่ละไฟล์ประกอบด้วยชื่อที่แสดง โฟลเดอร์ของไฟล์ ผู้เขียนและผู้ที่แก้ไขไฟล์ครั้งล่าสุด วันที่สร้างและแก้ไขล่าสุด ขนาดไฟล์ และกำหนดป้ายกำกับการเก็บรักษาและความลับหรือไม่ รูปที่ 1 แสดงสคริปต์ที่ทำงานอยู่

โฟลเดอร์ที่ใหญ่ที่สุดที่ฉันทดสอบเทียบกับไฟล์ที่เก็บไว้ 6,523 ไฟล์

การรับป้ายกำกับการเก็บรักษาสำหรับไฟล์

ป้ายการเก็บข้อมูลได้รับการสนับสนุนโดยผู้เช่าที่มี Office 365 E3 ขึ้นไป ไม่ใช่ผู้เช่าทุกรายจะใช้ป้ายกำกับการเก็บรักษา ดังนั้นสิ่งแรกคือการตรวจสอบว่ามีป้ายกำกับการเก็บรักษาอยู่หรือไม่ สคริปต์ใช้ cmdlet Get-MgSecurityLabelRetentionLabel เพื่อตรวจสอบป้ายกำกับการเก็บรักษา การเรียกใช้ cmdlet ต้องได้รับความยินยอมสำหรับสิทธิ์ RecordsManagement.Read.All

# Discover if the tenant uses retention labels
[array]$RetentionLabels = Get-MgSecurityLabelRetentionLabel
If ($RetentionLabels) {
    $Global:RetentionLabelsAvailable = $true
} Else {
    $Global:RetentionLabelsAvailable = $false
}

สคริปต์จะรู้ว่าควรพยายามดึงป้ายกำกับการเก็บรักษาสำหรับไฟล์หรือไม่ cmdlet ของกราฟ SDK ครอบคลุมการจัดการป้ายกำกับการเก็บรักษาแต่ไม่ครอบคลุมการดึงข้อมูลป้ายกำกับการเก็บรักษาจากไฟล์ หากต้องการรับป้ายกำกับการเก็บรักษา สคริปต์จะใช้คำขอกราฟ:

If ($RetentionLabelsAvailable -eq $true) {
  Try {
    $Uri = ("https://graph.microsoft.com/v1.0/drives/{0}/items/{1}/retentionLabel" -f $Drive, $File.Id)
   [array]$RetentionLabelInfo = Invoke-MgGraphRequest -Uri $Uri -Method Get
   RetentionLabelName = $RetentionLabelInfo.name
   } Catch {
   Write-Host ("Error reading retention label data from file {0}" -f $File.Name) 
   }
}

รับป้ายกำกับความไวสำหรับไฟล์

Get-MgBetaUserSecurityInformationProtectionSensitivityLabel cmdlet จะดึงป้ายกำกับความลับที่มีอยู่ (เผยแพร่แล้ว) ไปยังบัญชีผู้ใช้ที่ลงชื่อเข้าใช้ ซึ่งต้องได้รับความยินยอมสำหรับสิทธิ์ InformationProtectionPolicy.Read โค้ดนี้เรียกใช้ cmdlet เพื่อดึงชุดป้ายกำกับความลับและสร้างตารางแฮชจากตัวระบุและชื่อป้ายกำกับ อาร์เรย์ที่เก็บประเภทไฟล์ที่รองรับโดยป้ายกำกับความลับก็ถูกกำหนดเช่นกัน

$Account = (Get-MgContext).Account
[array]$SensitivityLabels = Get-MgBetaUserSecurityInformationProtectionSensitivityLabel -UserId $Account
If ($SensitivityLabels) {
    $Global:SensitivityLabelsAvailable = $true
    [array]$Global:ValidFileTypes = "docx", "pptx", "xlsx", "pdf"
    $Global:SensitivityLabelsHash = @{}
    ForEach ($Label in $SensitivityLabels) {
        $SensitivityLabelsHash.Add($Label.Id, $Label.Name)
    }
} Else {
    $Global:SensitivityLabelsAvailable = $false
}

หากต้องการดึงป้ายกำกับความลับสำหรับไฟล์ สคริปต์จะใช้ extractSensitivityLabels API ไฟล์สามารถมีป้ายกำกับความลับได้หลายป้าย แต่มีเพียงป้ายกำกับเดียวเท่านั้นที่สามารถใช้การป้องกันผ่านการเข้ารหัสตามการจัดการสิทธิ์ได้ อย่างที่คุณเห็นมีการใช้คำขอ POST เนื่องจาก API จะอัปเดตไซต์ SharePoint Online ด้วยรายละเอียดของป้ายชื่อความลับ ตามที่ฉันได้ระบุไว้ในบทความก่อนหน้านี้ การดำเนินการนี้อาจทำให้เกิดข้อผิดพลาดป้ายกำกับที่เข้ากันไม่ได้

If ($SensitivityLabelsAvailable -eq $true) {
  # Only check for sensitivity labels if they are available
  $FileType = $File.Name.Split(".")[1]
  If ($FileType -in $ValidFileTypes) { 
    $Uri = ("https://graph.microsoft.com/beta/sites/{0}/drive/items/{1}/extractSensitivityLabels" -f $Site.Id, $file.id)
    Try {
     [array]$SensitivityLabelInfo = Invoke-MgGraphRequest -Uri $Uri -Method POST 
     If ($SensitivityLabelInfo.labels.sensitivityLabelId) { 
       [array]$LabelName = $SensitivityLabelsHash[$SensitivityLabelInfo.labels.sensitivityLabelId]
     } Catch {
        Write-Host ("Error reading sensitivity label data from file {0}" -f $File.Name) 
       }
     }
}  

บางครั้งข้อผิดพลาดเกิดขึ้นเมื่ออ่านป้ายความลับจากไฟล์ และคุณจะเห็นข้อความลักษณะนี้:

ข้อผิดพลาดในการอ่านข้อมูลป้ายกำกับความลับจากไฟล์บทที่ 1 - ภาพรวม Office 365 - Final.docx

สาเหตุหนึ่งที่ทำให้เกิดเหตุการณ์เช่นนี้คือเมื่อไฟล์ได้รับการป้องกันโดย Office Information Rights Management (IRM) แทนที่จะเป็นป้ายความลับ วิธีแก้ไขคือการลบ IRM ออกจากไฟล์โดยเปิดส่วนป้องกันเอกสารของข้อมูลไฟล์และตั้งค่าการป้องกันการเข้าถึงแบบไม่จำกัด (รูปที่ 2)

อีกเหตุผลหนึ่งคือไฟล์ได้รับการกำหนดป้ายกำกับความลับที่ถูกลบออกจากผู้เช่าหรือถูกเปลี่ยนเป็นหรือจากป้ายกำกับย่อย วิธีแก้ไขคือขอให้ผู้เขียน (ผู้ที่มีสิทธิ์เปิดไฟล์เสมอ) เปิดไฟล์และกำหนดป้ายกำกับความลับอื่น ฉันแน่ใจว่ามีเหตุผลอื่นที่ทำให้ API อาจล้มเหลว แค่ฉันไม่ได้พบกับเงื่อนไขเหล่านั้น

ผลลัพธ์ของรายงาน

สคริปต์ประมวลผลไฟล์ที่ระหว่าง 225 ถึง 300 ไฟล์ต่อนาที โดยทั่วไป ยิ่งพบไฟล์ที่มีป้ายกำกับความลับในไซต์น้อยเท่าใด สคริปต์ก็จะยิ่งทำงานเร็วขึ้นเท่านั้น หากต้องการเรียกใช้สคริปต์เร็วขึ้น ให้แก้ไขโค้ดเพื่อลบบรรทัดที่ดึงข้อมูลเกี่ยวกับชุดป้ายกำกับความลับที่กำหนดไว้ในผู้เช่าและบรรทัดที่เรียก API extractSensitivityLabels เพื่อดึงป้ายกำกับความลับจากไฟล์

ผลลัพธ์คือรายการ PowerShell (แสดงในรูปที่ 3) สคริปต์ยังส่งออกเนื้อหาของรายการเป็นไฟล์ CSV

คุณสามารถดาวน์โหลดสคริปต์ตัวเต็มได้จาก GitHub

AI เจนเนอเรชั่นทำให้เศษขยะดิจิทัลเป็นอันตราย

มีสิ่งล่อใจให้ปล่อยไฟล์ไว้ตามลำพังในไซต์ SharePoint นโยบายการเก็บรักษาช่วยควบคุมหมายเลขไฟล์ที่เพิ่มขึ้น แต่จะไม่ลบไฟล์ใดๆ ที่มีป้ายกำกับการเก็บรักษาซึ่งมีระยะเวลาการเก็บรักษานานกว่า ดังที่คุณเห็นจากรูปที่ 3 เว็บไซต์บางแห่งที่ฉันใช้มีไฟล์ย้อนหลังไปถึงปี 2017 ผู้ดูแลระบบไม่มีเหตุผลที่จะอุทิศเวลาในการค้นหาและลบไฟล์ที่ล้าสมัยและอาจทำให้เข้าใจผิด เว้นแต่ว่าโควต้าพื้นที่เก็บข้อมูลของผู้เช่าจะถูกกดดัน

จนกระทั่งถึงยุคของ Generative AI เครื่องมือเช่น Copilot สำหรับ Microsoft 365 สามารถเข้าถึงไฟล์ใดก็ได้ในไซต์ใดก็ตามที่พร้อมใช้งานสำหรับผู้ใช้ที่ลงชื่อเข้าใช้ Copilot ไม่รู้ว่าเนื้อหาของไฟล์นั้นถูกต้องหรือเกี่ยวข้องหรือไม่ เนื้อหาเพียงให้คำเพิ่มเติมเพื่อให้ Copilot ใช้งานได้ในขณะที่สร้างเอาต์พุตเพื่อตอบสนองต่อคำแนะนำของผู้ใช้ (คำขอ) เว้นแต่ผู้ใช้ Copilot จะกลั่นกรองผลลัพธ์ที่สร้างขึ้น ก็มีโอกาสที่จะมีข้อมูลที่ไม่ถูกต้องคืบคลานเข้ามา นั่นเป็นเหตุผลที่ดีประการหนึ่งในการลบไฟล์เก่าและล้าสมัยออกจาก SharePoint Online แทนที่จะปล่อยให้เศษดิจิทัลเกิดขึ้น

หวังว่าสคริปต์นี้จะช่วยให้ผู้คนเข้าใจวิธีใช้ Microsoft Graph PowerShell SDK เพื่อนำทางไซต์ SharePoint Online และรับข้อมูลเชิงลึกเกี่ยวกับเนื้อหาเก่าที่ยังคงอยู่ ขั้นตอนถัดไปเชิงตรรกะอาจเป็นการแก้ไขไฟล์ CSV เพื่อลบรายการที่ควรเก็บไว้ และใช้ส่วนที่เหลือเป็นอินพุตสำหรับการลบโดย Delete Item API นั่นเป็นหัวข้อที่คุ้มค่ากับบทความอื่น!