Weboldal keresés

Hozzon létre egy SharePoint Online Files jelentést a Graph PowerShell SDK segítségével

A SharePoint Online Files jelentésszkriptjének frissítése a Graph PowerShell SDK használatához

2022 júliusában írtam a Graph API-k használatáról a SharePoint Online dokumentumtárban lévő fájlok jelentésére. A szkript szerkezete egyszerű volt: válasszon ki egy webhelyet, válasszon egy dokumentumtárat a webhelyen belül, és jelentse a könyvtárban található fájlokat és mappákat. Ez volt az első lehetőségem, hogy a SharePoint Online szolgáltatással dolgozzam Graph API-k használatával, és felbecsülhetetlen értékű tanulási tapasztalat volt.

Az idő és a technológia halad, és ugyanez a feladat elvégezhető a Microsoft Graph PowerShell SDK-val. Ha lehetséges, jobban szeretem a Graph PowerShell SDK-t használni, mert könnyebb vele dolgozni. A parancsmagok szükség esetén megújítják a hozzáférési jogkivonatokat, és gondoskodnak a lapozásról az adatok lekérésekor. A parancsmagok PowerShell-objektumokat és így tovább. Természetesen a Graph PowerShell SDK-nak vannak bosszantó hibák, de általában megpróbálom a parancsmagokat használni a Graph API kérések helyett, amikor csak lehetséges.

A Microsoft 2023-ban adta ki a Graph PowerShell SDK V2-es verzióját. Úgy döntöttem, hogy átírom a szkriptet úgy, hogy a Graph SDK-parancsmagokat használjam annak felderítésére, hogy az SDK mennyire képes kezelni a SharePoint Online tartalmat. A Microsoft rendelkezik egy előnézeti Graph API-val a SharePoint Online kezeléséhez, amely utánozza a SharePoint Online felügyeleti PowerShell modulban elérhető funkciók egy részét. Nem sok előrelépés történt ennek a modulnak a fejlesztése terén, és itt nem térek ki rá.

A SharePoint Online hárompontos menüjében tartalmazza az Exportálás Excelbe opciót. Ez a beállítás létrehoz egy Microsoft Excel weblekérdezési fájlt (.iqy), amely a SharePoint webhely aktuális helyéhez csatlakozik, és exportálja az elemekre és mappákra vonatkozó információkat egy Excel-munkafüzet táblázatába. Az exportálás hasznosan tartalmazza az alapértelmezett nézetben látható összes tulajdonságot. Használhatja ezt a lehetőséget a most elmagyarázandó szkript helyett, de akkor nem fogja megtanulni, hogyan kommunikáljon a SharePoint Online szolgáltatással a Graph SDK-parancsmagok használatával!

Webhelyek, meghajtók és meghajtóelemek

Az emberek ismerik a SharePoint Online webhelyek fogalmát. A szkript a Get-MgSite parancsmag használatával kezdődik, hogy megkeresse a megfelelő megjelenített nevekkel vagy leírásokkal rendelkező webhelyeket. Az első példa egy karakterlánc, a második egy változó használatával keres:

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

A SharePoint Online levágja a webhelyek készletét, hogy kizárjon minden olyan webhelyet, amelyhez a bejelentkezett felhasználó nem férhet hozzá. Még a SharePoint-rendszergazdai vagy globális rendszergazdai szerepkörrel rendelkező fiókok sem férhetnek hozzá a webhelyekhez, hacsak nem tagjai a webhelynek. A Get-MgSite által visszaadott webhelykészlet tartalmazza a Teams privát és megosztott csatornáihoz létrehozott webhelyeket. A szkript ezt úgy kezeli, hogy megkéri a felhasználót, hogy válasszon webhelyet. A visszaadott érték tartalmaz egy webhelyazonosítót, amely így néz ki:

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

A SharePoint Online webhelyeken van egy alapértelmezett dokumentumtár, a Documents (angol nyelven). Egy webhely azonban több dokumentumtárat is átfoghat. API kifejezéssel ezeket meghajtóknak nevezzük. A Get-MgSiteDrive parancsmag lekéri a webhely meghajtóinak készletét:

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

Minden meghajtónak van egy azonosítója (Id), amely így néz ki:

b!2HT-rPvtbUOSS-AYZmYF7pehq6IdX2RIosdNrw_2N5t7xp_DBXMQTalVjpKlwdxk

Helyazonosítóval és meghajtó azonosítóval tudjuk lekérni a meghajtóban lévő elemeket (driveitems). A meghajtók fájlokat és mappákat tartalmaznak, így a két típusú elem feldolgozása némi munkát igényel. A szkript tartalmaz egy Get-DriveItems nevű függvényt a mappában lévő fájlok feldolgozásához, beleértve a beágyazott mappákban lévő elemek rekurzív feldolgozását. Az indításhoz a szkript a gyökér (legfelső szintű) mappában kezdődik:

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

Az egyes fájlokhoz gyűjtött információk tartalmazzák a megjelenített nevét, a mappát, amelyhez tartoznak, a szerzőt és a fájlt utoljára módosító személyt, a létrehozási és utolsó módosítási dátumokat, a fájlméretet, valamint azt, hogy van-e hozzárendelve megőrzési és érzékenységi címkék. Az 1. ábra a szkript futását mutatja.

Az általam tesztelt legnagyobb mappa 6523 fájlt tartalmazott.

Fájl megőrzési címkéjének beszerzése

A megőrzési címkéket az Office 365 E3 és újabb verzióval rendelkező bérlők támogatják. Nem minden bérlő használ megőrzési címkéket, ezért az első dolog az, hogy ellenőrizze, hogy vannak-e megőrzési címkék. A szkript a Get-MgSecurityLabelRetentionLabel parancsmagot használja a megőrzési címkék ellenőrzéséhez. A parancsmag futtatásához hozzájárulás szükséges a RecordsManagement.Read.All engedélyhez.

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

A szkript ezután tudja, hogy meg kell-e próbálnia lekérni egy fájl megőrzési címkéjét. A Graph SDK-parancsmagok lefedik a megőrzési címkék kezelését, de nem a megőrzési címke információk fájlból való lekérését. A megőrzési címke lekéréséhez a szkript egy Graph kérést használ:

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) 
   }
}

Fájl érzékenységi címkéjének beszerzése

A Get-MgBetaUserSecurityInformationProtectionSensitivityLabel parancsmag lekéri a bejelentkezett felhasználói fiókhoz elérhető (közzétett) érzékenységi címkéket, amelyhez az InformationProtectionPolicy.Read engedélyhez hozzájárulás szükséges. Ez a kód futtatja a parancsmagot az érzékenységi címkék készletének lekéréséhez, és összeállít egy hash-táblázatot a címkeazonosítóból és -névből. Az érzékenységi címkék által támogatott fájltípusokat tartalmazó tömb is meghatározásra került.

$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
}

A fájl érzékenységi címkéjének lekéréséhez a szkript az ExtractSensitivityLabels API-t használja. Egy fájlnak több érzékenységi címkéje is lehet, de csak egy címke alkalmazhat védelmet a jogkezelésen alapuló titkosítás révén. Mint látható, POST kérést használnak. Ennek az az oka, hogy az API frissíti a SharePoint Online webhelyet az érzékenységi címke részleteivel. Amint azt egy korábbi cikkben megjegyeztem, ez a művelet összeférhetetlen címkehibákat okozhat.

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) 
       }
     }
}

Néha hibák történnek a fájlok érzékenységi címkéinek olvasásakor, és a következő üzenet jelenik meg:

Hiba az érzékenységi címke adatok olvasásakor a fájlból 1. fejezet - Az Office 365 áttekintése - Final.docx

Ennek egyik oka az, hogy egy fájlt az Office Information Rights Management (IRM) véd érzékenységi címke helyett. A megoldás az IRM eltávolítása a fájlból. Ehhez nyissa meg a Dokumentum védelme szakaszát a fájlinformációk között, és állítsa be a védelmet korlátlan hozzáférésre (2. ábra).

Egy másik ok az, hogy a fájlhoz egy érzékenységi címkét rendeltek, amelyet eltávolítottak a bérlőből, vagy alcímkére változtattak. A megoldás itt az, hogy megkérjük a szerzőt (akinek mindig van joga megnyitni egy fájlt), hogy nyissa meg a fájlt, és rendeljen hozzá egy másik érzékenységi címkét. Biztos vagyok benne, hogy vannak más okok is, amelyek miatt az API meghibásodhat. Csak én nem találkoztam ezekkel a feltételekkel.

A jelentés kimenete

A szkript percenként 225 és 300 fájl közötti sebességgel dolgoz fel fájlokat. Általában minél kevesebb érzékenységi címkével ellátott fájl található egy webhelyen, annál gyorsabban fut a szkript. A szkript gyorsabb futtatásához módosítsa a kódot úgy, hogy eltávolítsa azokat a sorokat, amelyek információkat kérnek le a bérlőben meghatározott érzékenységi címkék készletéről, valamint azokat a sorokat, amelyek az extractSensitivityLabels API-t hívják meg az érzékenységi címke fájlból való lekéréséhez.

A kimenet egy PowerShell-lista (a 3. ábrán látható). A szkript a lista tartalmát CSV-fájlba is exportálja.

A teljes szkriptet letöltheti a GitHubról.

A generatív mesterséges intelligencia veszélyessé teszi a digitális törmeléket

Fennáll a kísértés, hogy egyedül hagyják a fájlokat a SharePoint-webhelyeken. A megőrzési házirendek segítenek a duzzadt fájlszámok ellenőrzésében tartani, de nem távolítják el azokat a fájlokat, amelyeknek hosszabb megőrzési időtartamú megőrzési címkéje van. A 3. ábrán látható, hogy az általam használt webhelyek némelyike 2017-ig visszamenőleg tartalmaz fájlokat. Hacsak a bérlői tárhelykvóta nem esik nyomás alá, a rendszergazdáknak nincs okuk időt fordítani az elavult és potenciálisan félrevezető fájlok megtalálására és eltávolítására.

Egészen addig, amíg el nem érkezett a generatív mesterséges intelligencia korszaka. Az olyan eszközök, mint a Copilot for Microsoft 365, a bejelentkezett felhasználó számára elérhető bármely webhely bármely fájljához hozzáférhetnek. A másodpilóta nem tudja, hogy egy fájl tartalma pontos vagy releváns-e. A tartalom csak több szót biztosít a Copilot számára, amellyel szembeszállhat, mivel a felhasználói utasításokra (kérésekre) válaszul kimenetet generál. Hacsak a másodpilóta-felhasználók nem vizsgálják át a generált kimenetet, fennáll a lehetőség, hogy pontatlan információk férkőznek be. Ez az egyik jó ok arra, hogy eltávolítsuk a régi és elavult fájlokat a SharePoint Online-ból, ahelyett, hogy hagynánk, hogy a digitális törmelék felgyülemlik a helyére.

Remélhetőleg ez a szkript segít az embereknek megérteni, hogyan használhatják a Microsoft Graph PowerShell SDK-t a SharePoint Online webhelyeken való navigáláshoz, és betekintést nyerhetnek abba, hogy mennyi régi tartalom maradt fenn. A következő logikus lépés a CSV-fájl szerkesztése lehet, hogy eltávolítsa azokat az elemeket, amelyeket meg kell őrizni, és a maradékot bemenetként használja az Elem törlése API-val történő eltávolításhoz. Ez egy újabb cikkre érdemes téma!

Kapcsolódó cikkek