教學課程：產生和分析 SharePoint 網站的版本使用量報告

發行項
10/26/2024

藉由了解網站上的版本記憶體，您可以更有效地優化版本歷程記錄設定，以符合組織的復原目標和管理記憶體成本。

本教學課程說明如何產生版本記憶體使用量報告並加以分析，以進一步了解網站的版本記憶體使用量。報告也可以用來執行套用不同版本限制或修剪現有版本的「假設」分析。

在本教學課程中，我們將討論如何：

產生月臺或文檔庫的版本記憶體使用量報告檔案。
檢查報表產生進度。
瞭解報表檔案。
使用 Excel 或 PowerShell 分析版本記憶體使用。

在稍後的教學課程中，請檢閱如何在產生的 CSV 報表上執行影響分析。

開始之前

識別您想要瞭解其版本記憶體使用量的 SharePoint 網站、OneDrive 帳戶或文檔庫。
選擇您要儲存報表的 SharePoint 文件庫中的位置。
下載最新的 SharePoint Online 管理命令介面。

注意事項

報表檔案會在指定的報表位置內產生。
報表位置必須位於 SharePoint 文件庫本身內。
文件庫中不能有與報表同名的檔案。

產生網站或文檔庫的版本使用量報告

您可以執行命令，或在連結庫上New-SPOListFileVersionBatchDeleteJob執行命令，以在站New-SPOSiteFileVersionExpirationReportJob臺上產生目前版本記憶體使用的報表。

在下列範例中，作業會排入佇列，以在報表位置產生網站範圍的報表。 https://contoso.sharepoint.com/sites/sites1/reports/MyReports/VersionReport.csv

New-SPOSiteFileVersionExpirationReportJob -Identity https://contoso.sharepoint.com/sites/site1 -ReportUrl "https://contoso.sharepoint.com/sites/sites1/reports/MyReports/VersionReport.csv"

在下列範例中，作業會排入佇列，以在報表位置產生連結庫範圍的報表。 https://contoso.sharepoint.com/sites/sites1/reports/MyReports/VersionReport.csv

New-SPOListFileVersionExpirationReportJob -Site https://contoso.sharepoint.com/sites/site1 -List "Documents" -ReportUrl "https://contoso.sharepoint.com/sites/sites1/reports/MyReports/VersionReport.csv"

檢查產生報告的進度

Get-SPOListFileVersionExpirationReportJobProgress使用命令來追蹤報告產生要求的進度。

下列範例示範如何檢查 您的網站範圍報 表是否已完整填入並準備好進行分析。 

Get-SPOSiteFileVersionExpirationReportJobProgress -Identity https://contoso.sharepoint.com/sites/site1 -ReportUrl "https://contoso.sharepoint.com/sites/sites1/reports/MyReports/VersionReport.csv"

下列範例示範如何檢查您的 文檔庫範圍報 表是否已完整填入並準備好進行分析。  

Get-SPOListFileVersionExpirationReportJobProgress -Site https://contoso.sharepoint.com/sites/site1 -List "Documents" -ReportUrl "https://contoso.sharepoint.com/sites/sites1/reports/MyReports/VersionReport.csv"

Cmdlet 會以 JSON 格式傳回回應。傳回的 json 回應具有名為 status 的索引鍵。如需下列其中一個預期值，請參閱下表：

JSON 狀態回應	說明
“completed”	作業已順利完成，且報表已完全填入。
“in_progress”	有作用中的作業。報表會部分填入。
“no_report_found”	沒有使用中的作業會填入指定的檔案。
“failed”	產生報告的作業因錯誤訊息而失敗。檢查「error_message」，以取得失敗的錯誤訊息。

瞭解版本報表檔案

產生的報表是 CSV 格式，且每個數據列對應至檔案版本。以下是檔案版本到期報表及其數據行明細的範例。

第一個數據列是具有包含檔案版本標識碼、版本元數據資訊和到期時間戳之數據行標識碼的標頭。壓縮數據行會以 .Compact 後置修正表示，如果兩個連續的數據列具有相同的值，則不會重複值。其他數據列代表檔案版本，其中每個數據列都代表單一版本。
讓我們瀏覽此報表中顯示的第一個檔案版本。

檔案版本標識碼： WebId、 DocId、 MajorVersion和 MinorVersion 可唯一識別 SharePoint 網站中的每個版本。
版本元數據識別碼：WebUrl 表示中的 https://contoso.sharepoint.com版本，並 FileUrl 指出此版本的檔案位於 DocLib/MyDocument.docx。換句話說，它是在名為的 DocLib文檔庫中，而檔案位於的 DocLib 根資料夾中，並命名為 MyDocument.docx。
Size 表示版本需要 92,246 個字節的記憶體。
接下來的兩個數據行， ModifiedBy_UserId 指出 ModifiedBy_DisplayName 使用者具有使用者標識碼 6 的使用者 () 已建立此版本。
LastModifiedDate 表示版本的內容上次修改時間為 2023 年 3 月 13 日 22：36：09 UTC。 SnapshotDate 顯示版本在 2023 年 3 月 20 日 16：56：51 UTC 變成歷程記錄版本。 IsSnapshotDateEstimated 會顯示 SnapshotDate 為實際的快照集日期。
到期排程標識碼：CurrentExpirationDate 表示此版本目前設定為永不過期。 AutomaticPolicyExpirationDate 顯示在自動到期原則下，此版本也會設定為永不過期。 TargetExpirationDate 表示如果我們遵循此排程進行修剪，我們會將此版本設定為永不過期。

注意事項

儲存在檔保留庫中的檔案版本也會包含在此報表中。

讓我們看看第三個版本。

和 WebIdDocId 值是空的，因為這些數據行是壓縮數據行，以表示 。壓縮 後置修正，這表示它們應該有值。如果我們尋找該資料列上方的最後一個非空白，我們會將尋找為 4c7a58c1-01f2-4fa3-a730-44081a44f689，並將 DocId 視為 18c3e09c-b5be-48e7-a754-7a2ce53e0999WebId 。

我們也可以看到設定 TargetExpirationDate 為 2023 年 4 月 19 日 18：08：53 UTC。這表示，如果我們根據此排程進行修剪，我們會將此版本的到期日設定為該時間。

注意事項

所有日期時間都是以來回格式表示。如需詳細資訊，請參閱 Standard 日期和時間格式字串 - .NET |Microsoft Learn

分析月臺的版本記憶體

開始分析之前，您應該將報表檔案中的數據行更新 TargetExpirationDate 為您想要的日期，例如要過期的版本。同樣地，如果您為某個版本選擇過去的日期，則該版本會被視為「已過期的版本」，並且會在您開始修剪之後立即刪除。

您可以編輯 csv 檔案，手動更新中的 TargetExpirationDate 日期。不過，您可能有太多數據列無法手動更新。若要大量更新數據行，您可以使用 Excel 公式，也可以使用我們在教學課程：執行『What-If』分析中提供的其中一個 PowerShell 腳本。具體而言，您可以選擇修剪模式、執行對應的腳本，以根據該修剪模式取得已填寫的已更新 csv 檔案 TargetExpirationDate ，然後從該處繼續。

選項一：使用 Excel 分析報表

開啟共用Excel活頁簿 AnalyzeReportFile_Template.xlsx。您可以在其中找到下列工作表。

設定：使用此工作表來設定產生不同報表檢視的日期範圍。
數據集：此工作表是從報表檔案匯入的原始數據集。各種報表摘要檢視都是從此數據集建構而來。
預設報表：以下是預設檢視清單，可用來瞭解在網站儲存的版本上套用所選設定的影響：
- 摘要：分析此月臺的版本記憶體目前狀態，以及新設定下的已刪除版本散發。
- 受影響的使用者：檢閱其版本在新設定下會受到影響的使用者。
- 版本計數：數據表和圖表，顯示在目前排程下一段時間內可用的版本數目，以及新排程下可用的版本數目。
- 版本大小分析：比較將在目前排程下一段時間刪除的版本大小，以及新排程下可用的版本數目。
- 檔案層級分析：檢閱新設定下的檔案層級版本刪除。

依照下列步驟填入活頁簿：

在 [ 組態] 工作表上，輸入單元格 B3 中 What-If 報表檔案的完整路徑。
如果您想要變更 [ 可用的版本數 目] 工作表或 [版本過期] 工作表的大小中的圖表日期範圍，請變更單元格 B6、B7、B10 和/或 B11 中的對應值。這是選擇性的。
在 Excel 頂端，選取 [ 數據] 索 引標籤，然後在功能區中選取 [ 全部重新整理] 按鈕。
在 [檔案層級分析] 工作表上，自動填入 [ 版本數目 ] 和 [ 刪除后剩餘的版本數 目] 資料行。

提示

您可以選取包含數據的數據格，然後按兩下填滿句柄以完成自動填滿。
在 [ 受影響的使用者 ] 工作表上，自動填入 [ 將會刪除的版本數目] 資料行。

所有工作表現在都應該是最新狀態。您可以檢查您感興趣的資訊。

選項 2：使用 PowerShell 分析報表

將腳本儲存為名為AnalyzeReportFile.ps1 的檔案。

# save this file as AnalyzeReportFile.ps1

Param(
  [Parameter(Mandatory=$true)][string] $ReportLocalFilePath,
  [Parameter(Mandatory=$false)][int]$ShowFilesWithFewerThanNVersions=10,
  [Parameter(Mandatory=$false)][DateTime]$TimelineStartDate=[DateTime]::Now,
  [Parameter(Mandatory=$false)][int]$TimelineStepDays=10,
  [Parameter(Mandatory=$false)][int]$TimelineNumSteps=10
)
function Import-Dataset($DatasetFilePath)
{
  $Dataset = Import-CSV $DatasetFilePath
  $Columns = $Dataset `
    | Get-Member -MemberType 'NoteProperty' `
    | Select-Object -ExpandProperty Name
  $CompactColumns = $Columns | Where-Object { $_ -Match ".Compact" }
   
  $Timer = [Diagnostics.Stopwatch]::StartNew()
  for ($RowIndex = 0; $RowIndex -lt $Dataset.Count; $RowIndex++)
  {
    if ($RowIndex -gt 0)
    {
      $PrevRow = $Dataset[$RowIndex-1]
    }
    $Row = $Dataset[$RowIndex]
   
    foreach ($ColName in $Columns)
    {
      if ([string]::IsNullOrEmpty($Row.$ColName))
      {
        if (($ColName -in $CompactColumns) -and ($RowIndex -gt 0))
        {
          $Row.$ColName = $PrevRow.$ColName
        }
        else
        {
          $Row.$ColName = $null
        }
      }
    }
   
    $Row."WebId.Compact" = [Guid]$Row."WebId.Compact"
    $Row."DocId.Compact" = [Guid]$Row."DocId.Compact"
    $Row."MajorVersion" = [Int32]$Row."MajorVersion"
    $Row."MinorVersion" = [Int32]$Row."MinorVersion"
    $Row."WebUrl.Compact" = [String]$Row."WebUrl.Compact"
    $Row."FileUrl.Compact" = [String]$Row."FileUrl.Compact"
    $Row."Size" = [Int64]$Row."Size"
    $Row."ModifiedBy_UserId.Compact" = [String]$Row."ModifiedBy_UserId.Compact"
    $Row."ModifiedBy_DisplayName.Compact" = [String]$Row."ModifiedBy_DisplayName.Compact"
    $Row."LastModifiedDate" = [DateTime]$Row."LastModifiedDate"
    $Row."SnapshotDate" = [DateTime]$Row."SnapshotDate"
    $Row."IsSnapshotDateEstimated" = [bool]$Row."IsSnapshotDateEstimated"
    $Row."CurrentExpirationDate" = [System.Nullable[DateTime]]$Row."CurrentExpirationDate"
    $Row."AutomaticPolicyExpirationDate" = [System.Nullable[DateTime]]$Row."AutomaticPolicyExpirationDate"
    $Row."TargetExpirationDate" = [System.Nullable[DateTime]]$Row."TargetExpirationDate"
    $Percent = [Math]::Ceiling(100 * $RowIndex / $Dataset.Count)
    Write-Progress `
      -Activity "Reading dataset" `
      -Status "$Percent% Complete ($($RowIndex + 1) / $($Dataset.Count) rows):" `
      -PercentComplete $Percent `
      -SecondsRemaining $(($Dataset.Count - ($RowIndex + 1)) / (($RowIndex + 1) / $Timer.Elapsed.Totalseconds))
  }
  $Timer.Stop()
  return $Dataset
}
function Get-NumVersionExpiresByDate($Dataset, $ColName, $DateCutoff)
{
  $VersionsExpired = $Dataset | Where-Object { ($null -ne $_.$ColName) -and ($_.$ColName -le $DateCutoff) }
  $IsTodayStr = ""
  If ((Get-Date).Date -eq ($DateCutoff).Date) 
  {
    $IsTodayStr = "*"
  }
  return [PSCustomObject]@{
    Today              = $IsTodayStr
    Date              = $DateCutoff
    NumberOfVersionsAvailable    = $Dataset.Count - $VersionsExpired.Count
    NumberOfVersionsExpired     = $VersionsExpired.Count
    SizeOfVersionsExpiredInBytes  = ($VersionsExpired | Measure-Object Size -Sum).Sum
  }
}
function Get-FilesWithFewerThanNVersions($Dataset, $NumVersions)
{
  $AvailableVersionsByFile = $Dataset `
    | Where-Object { ($null -eq $_.TargetExpirationDate) -or ($_.TargetExpirationDate -gt [DateTime]::Now) } `
    | Group-Object -Property WebId.Compact, DocId.Compact
  $AvailableFilesWithNotEnoughVersions = @{}
  # Files with some versions left but not enough
  $AvailableVersionsByFile `
    | Where-Object Count -lt $NumVersions `
    | ForEach-Object { $AvailableFilesWithNotEnoughVersions[$_.Name] = $_.Count }
  # Files with 0 versions left
  $Dataset `
    | Group-Object -Property WebId.Compact, DocId.Compact `
    | Where-Object { $AvailableVersionsByFile.Name -notcontains $_.Name } `
    | ForEach-Object { $AvailableFilesWithNotEnoughVersions[$_.Name] = 0 }
  # Stitch all of the data together
  return $Dataset `
    | Group-Object -Property WebId.Compact, DocId.Compact `
    | Where-Object Count -ge $NumVersions `
    | Where-Object { $AvailableFilesWithNotEnoughVersions.Contains($_.Name) } `
    | ForEach-Object `
      {
        $fileUrl = $_.Group[0]."WebUrl.Compact" + "/" + $_.Group[0]."FileUrl.Compact"
        $numberOfVersionsAvailableBeforeTrim = $_.Count
        $numberOfVersionsAvailableAfterTrim = $AvailableFilesWithNotEnoughVersions[$_.Name]
        $numberOfVersionsTrimmed = $numberOfVersionsAvailableBeforeTrim - $numberOfVersionsAvailableAfterTrim
        [PSObject]::new() | 
          Add-Member -PassThru -NotePropertyMembers ([Ordered]@{
            FileUrl = $fileUrl
            NumberOfVersionsAvailableBeforeTrim = $numberOfVersionsAvailableBeforeTrim
            NumberOfVersionsAvailableAfterTrim = $numberOfVersionsAvailableAfterTrim
            NumberOfVersionsTrimmed = $numberOfVersionsTrimmed
          })
      } `
    | Sort-Object -Property NumberOfVersionsAvailableAfterTrim
}
function Get-MostImpactedUsers($Dataset)
{
  $VersionsExpired = $Dataset | Where-Object { ($null -ne $_.TargetExpirationDate) -and ($_.TargetExpirationDate -le [DateTime]::Now) }
  return $VersionsExpired `
    | Group-Object -Property ModifiedBy_UserId.Compact `
    | Select-Object `
      @{ L = "UserId"; E = { $_.Group[0]."ModifiedBy_UserId.Compact" } }, `
      @{ L = "UserDisplayName"; E = { $_.Group[0]."ModifiedBy_DisplayName.Compact" } },
      @{ L = "NumberOfVersionsTrimmed"; E = { $_.Count } } `
    | Sort-Object -Property NumberOfVersionsTrimmed -Descending
}
$Dataset = Import-Dataset -DatasetFilePath $ReportLocalFilePath
$CurrentExpirationSummaryTable = @()
$TargetExpirationSummaryTable = @()
$Timer = [Diagnostics.Stopwatch]::StartNew()
for ($Step = 0; $Step -lt $TimelineNumSteps; $Step++)
{
  $DateCutOff = $TimelineStartDate.AddDays($TimelineStepDays * $Step)
  $CurrentExpirationSummaryTable += `
    Get-NumVersionExpiresByDate -Dataset $Dataset -ColName CurrentExpirationDate -DateCutoff $DateCutOff
  $TargetExpirationSummaryTable += `
    Get-NumVersionExpiresByDate -Dataset $Dataset -ColName TargetExpirationDate -DateCutoff $DateCutOff
}
$Timer.Stop()
Write-Host "===========================" -ForegroundColor Yellow
Write-Host "Current Expiration Schedule" -ForegroundColor Yellow
Write-Host "===========================" -ForegroundColor Yellow
$CurrentExpirationSummaryTable | Format-Table -Autosize | Out-String | Write-Host
Write-Host "Total elapsed seconds: $($Timer.Elapsed.TotalSeconds / 2)" -ForegroundColor Green
Write-Host
Write-Host "==========================" -ForegroundColor Yellow
Write-Host "Target Expiration Schedule" -ForegroundColor Yellow
Write-Host "==========================" -ForegroundColor Yellow
$TargetExpirationSummaryTable | Format-Table -Autosize | Out-String | Write-Host
Write-Host "Total elapsed seconds: $($Timer.Elapsed.TotalSeconds / 2)" -ForegroundColor Green
Write-Host
Write-Host "================================" -ForegroundColor Yellow
Write-Host "Files with Fewer Than $ShowFilesWithFewerThanNVersions Versions" -ForegroundColor Yellow
Write-Host "================================" -ForegroundColor Yellow
$Timer = [Diagnostics.Stopwatch]::StartNew()
Get-FilesWithFewerThanNVersions -Dataset $Dataset -NumVersions $ShowFilesWithFewerThanNVersions | Format-Table -Autosize | Out-String | Write-Host
$Timer.Stop()
Write-Host "Total elapsed seconds: $($Timer.Elapsed.TotalSeconds)" -ForegroundColor Green
Write-Host
Write-Host "==============" -ForegroundColor Yellow
Write-Host "Users Impacted" -ForegroundColor Yellow
Write-Host "==============" -ForegroundColor Yellow
$Timer = [Diagnostics.Stopwatch]::StartNew()
Get-MostImpactedUsers -Dataset $Dataset | Format-Table -Autosize | Out-String | Write-Host
$Timer.Stop()
Write-Host "Total elapsed seconds: $($Timer.Elapsed.TotalSeconds)" -ForegroundColor Green
Write-Host

開啟 PowerShell 並執行下列命令，並將佔位符值取代為適當的值。

注意事項

使用 PowerShell 7 執行命令。您可以依照下列指示安裝 PowerShell 7：在 Windows 上安裝 PowerShell - PowerShell |Microsoft Learn。

. “<path to AnalyzeReportFile.ps1>” –ReportLocalFilePath “<path to the file version expiration What-If report .csv file>”

輸出會顯示四個資料表：

目前的到期排程： 此數據表包含版本的時間序列摘要。它具有下列資料列：
1. 日期：第一個數據行代表日期。
2. NumberOfVersionsAvailable：在目前排程下該日期可用的版本數目。
3. NumberOfVersionsExpired：在目前排程下該日期到期的版本數目。
4. SizeOfVersionsExpiredMB：在目前排程下該日期到期的版本大小。
目標到期排程： 此數據表與目前到期排程相同，但會改為反映更新的排程。只有當您想要藉由變更檔案版本到期報告中的 TargetExpirationDate 數據行來測試不同的到期案例時，此數據表才有説明。
版本少於 10 個的檔案：URL 清單，以及在立即刪除之後版本數目小於 10 的檔案刪除前後的版本數目 (，但在立即刪除) 之前超過 10 個。
受影響的使用者： 會立即刪除其版本的使用者。