Tutorial: Gerar e analisar o relatório de utilização de versões do site SharePoint

Artigo
10/26/2024

Ao compreender o armazenamento de versões num site, pode otimizar melhor as definições do Histórico de versões para cumprir os objetivos de recuperação da sua organização e gerir os custos de armazenamento.

Este tutorial mostra como pode gerar um relatório de utilização do armazenamento de versões e analisá-lo para compreender melhor a quantidade de armazenamento de versões do site. O relatório também pode ser utilizado para executar a análise "what-if" da aplicação de diferentes limites de versão ou de limitação de versões existentes.

Neste tutorial, vamos abordar como:

Gerar o ficheiro de relatório de utilização do armazenamento de versões para o site ou biblioteca.
Verifique o progresso da geração de relatórios.
Compreenda o ficheiro de relatório.
Analise a utilização do armazenamento de versões com o Excel ou o PowerShell.

Em tutoriais posteriores, reveja como pode executar a análise de impacto no relatório CSV gerado.

Antes de começar

Identifique o site do SharePoint, a conta do OneDrive ou a biblioteca de documentos cuja utilização de armazenamento de versões quer compreender.
Escolha uma localização na biblioteca de documentos do SharePoint na qual pretende guardar o relatório.
Baixe o Shell de Gerenciamento do SharePoint Online mais recente.

Observação

O ficheiro de relatório é gerado na localização do relatório especificada.
A localização do relatório tem de estar numa biblioteca de documentos do SharePoint.
Não pode haver um ficheiro com o mesmo nome que o relatório na biblioteca de documentos.

Gerar relatório de utilização de versões para sites ou bibliotecas

Pode gerar um relatório sobre a utilização atual do armazenamento de versões num site ao executar o New-SPOSiteFileVersionExpirationReportJob comando ou numa biblioteca ao executar o New-SPOListFileVersionBatchDeleteJob comando .

No exemplo seguinte, é colocada uma tarefa em fila para gerar um relatório no âmbito do site na localização do relatório, 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"

No exemplo seguinte, é colocada uma tarefa em fila para gerar um relatório com âmbito de biblioteca na localização do relatório, 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"

Verificar o progresso na geração de relatórios

Utilize o Get-SPOListFileVersionExpirationReportJobProgress comando para controlar o progresso do pedido de geração de relatórios.

O exemplo abaixo mostra como pode marcar se o relatório no âmbito do site estiver totalmente preenchido e pronto para ser analisado. 

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

O exemplo abaixo mostra como pode marcar se o relatório no âmbito da biblioteca estiver totalmente preenchido e pronto para ser analisado.  

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

O cmdlet devolverá uma resposta no formato JSON. A resposta json devolvida tem uma chave com o nome status. Veja a tabela abaixo para obter um dos seguintes valores esperados:

Resposta de Estado JSON	Explicação
"concluído"	A tarefa foi concluída com êxito e o relatório está totalmente preenchido.
"in_progress"	Existe um trabalho ativo. O relatório é parcialmente preenchido.
"no_report_found"	Não existem tarefas ativas a preencher o ficheiro especificado.
"falhou"	A tarefa para gerar o relatório falhou devido à mensagem de erro. Verifique "error_message" para obter a mensagem de erro da falha.

Compreender o ficheiro de relatório de versão

O relatório gerado está no formato CSV, com cada linha a corresponder a uma versão de ficheiro. Eis um exemplo do relatório de expiração da versão do ficheiro e a divisão das colunas.

A primeira linha é o cabeçalho com os identificadores de coluna que contêm Identificadores de Versão do Ficheiro, informações de Metadados de Versão e carimbo de data/hora de expiração. As colunas compactas são indicadas com .Compact pós-correção que não repetem valores se duas linhas consecutivas tiverem o mesmo valor. As outras linhas representam versões de ficheiro, em que cada linha representa uma única versão.
Vamos percorrer a primeira versão do ficheiro apresentada neste relatório.

Identificadores de versão do ficheiro: WebId, DocId, MajorVersione MinorVersion identificam exclusivamente cada versão no seu site do SharePoint.
Identificadores de metadados de versão:WebUrl indica a versão no https://contoso.sharepoint.come FileUrl indica que o ficheiro para esta versão está localizado no DocLib/MyDocument.docx. Por outras palavras, está numa Biblioteca de Documentos denominada DocLib, enquanto o ficheiro está na pasta raiz de DocLib e tem o nome MyDocument.docx.
Size indica que a versão requer 92 246 bytes de armazenamento.
As duas colunas ModifiedBy_UserId seguintes indicam ModifiedBy_DisplayName que a utilizadora Michelle Harris (com o ID de utilizador 6) criou esta versão.
LastModifiedDate indica que o conteúdo da versão foi modificado pela última vez a 13 de março de 2023 às 22:36:09 UTC. SnapshotDate mostra que a versão se tornou uma versão histórica a 20 de março de 2023, às 16:56:51 UTC. IsSnapshotDateEstimatedmostra que SnapshotDate é a data de snapshot real.
Identificadores de agenda de expiração:CurrentExpirationDate indica que esta versão está atualmente definida para nunca expirar. AutomaticPolicyExpirationDate mostra que, na política de expiração automática, esta versão também está definida para nunca expirar. TargetExpirationDate indica que, se seguirmos esta agenda para a limitação, definiríamos que esta versão nunca expiraria.

Observação

As versões de ficheiro armazenadas na biblioteca de suspensão de preservação também serão incluídas neste relatório.

Vejamos a terceira versão.

Os WebId valores e DocId estão vazios porque estas colunas são colunas compactas, indicadas por . Compactar pós-correção significa que devem ter valores. Se procurarmos o último valor acima dessa linha, encontramos WebId como 4c7a58c1-01f2-4fa3-a730-44081a44f689e DocId como 18c3e09c-b5be-48e7-a754-7a2ce53e0999.

Também podemos ver que o TargetExpirationDate está definido para 19 de abril de 2023, às 18:08:53 UTC. Significa que se cortarmos com base nesta agenda, estaríamos a definir a data de expiração para esta versão para essa hora.

Observação

Todas as datas são representadas no formato de ida e volta. Para obter mais informações, veja Cadeias de formato de data e hora padrão – .NET | Microsoft Learn

Analisar o armazenamento de versões dos sites

Antes de iniciar a sua análise, deve atualizar a TargetExpirationDate coluna no ficheiro de relatório para as datas pretendidas, como as versões a expirar. Mais uma vez, se escolher uma data anterior para uma versão, essa versão será tratada como "versão que já tinha expirado" e será eliminada imediatamente após iniciar o corte.

Pode atualizar manualmente as datas no TargetExpirationDate ao editar o ficheiro csv. No entanto, pode ter demasiadas linhas para atualizar manualmente. Para atualizar a coluna em massa, pode utilizar fórmulas do Excel ou também pode utilizar um dos scripts do PowerShell que fornecemos no Tutorial: Executar a análise "What-If". Especificamente, pode escolher um modo de corte, executar o script correspondente para obter um ficheiro csv atualizado com TargetExpirationDate preenchido com base nesse modo de corte e continuar a partir daí.

Opção um: Analisar o relatório com o Excel

Abra o livro partilhado do Excel AnalyzeReportFile_Template.xlsx. Pode encontrar as seguintes folhas de cálculo na mesma.

Configuração: utilize esta folha de cálculo para definir o intervalo de datas para gerar as diferentes vistas de relatório.
Conjunto de dados: esta folha de cálculo é o conjunto de dados não processado importado do ficheiro de relatório. Várias vistas de resumo de relatórios são construídas a partir deste conjunto de dados.
Relatórios Predefinidos: eis uma lista de vistas predefinidas que podem ser utilizadas para compreender o impacto da aplicação da definição selecionada em versões armazenadas no site:
- Resumo: Analise o estado atual do armazenamento de versões para este site e elimine a distribuição de versões nas novas definições.
- Utilizadores Afetados: reveja os utilizadores cujas versões seriam afetadas nas novas definições.
- Contagem de Versões: uma tabela e um gráfico que mostram os números de versões que estarão disponíveis ao longo do tempo de acordo com a agenda atual e o número de versões que estarão disponíveis ao abrigo da nova agenda.
- Tamanho das Versões Expiradas: compare o tamanho das versões que serão eliminadas ao longo do tempo de acordo com a agenda atual e o número de versões que estarão disponíveis ao abrigo da nova agenda.
- Análise ao Nível do Ficheiro: reveja as eliminações de versões ao nível do ficheiro nas novas definições.

Preencha o livro ao seguir estes passos:

Na folha de cálculo Configuração , introduza o caminho completo para o ficheiro de relatório What-If na Célula B3.
Se quiser alterar o intervalo de datas dos gráficos na folha de cálculo Número de Versões Disponíveis ou Tamanho das Versões Expirado , altere os valores correspondentes nas Células B6, B7, B10 e/ou B11. É opcional.
Na parte superior do Excel, selecione o separador Dados e, no Friso, selecione o botão Atualizar Tudo .
Na folha de cálculo Cálculos , preenchimento automático das colunas Número de Versões e Número de Versões Restantes Após Eliminação .
Na folha de cálculo Utilizadores Afetados , preenchimento automático da coluna Número de Versões Será Eliminado .

Todas as folhas de cálculo devem estar atualizadas. Pode marcar as informações que lhe interessam.

Opção dois: Analisar o relatório com o PowerShell

Guarde o script como um ficheiro com o nome 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

Abra o PowerShell e execute o seguinte comando, substituindo os valores do marcador de posição pelos valores adequados.

Observação

Utilize o PowerShell 7 para executar os comandos. Pode instalar o PowerShell 7 ao seguir estas instruções: Instalar o PowerShell no Windows - PowerShell | Microsoft Learn.

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

O resultado apresenta quatro tabelas:

Agenda de Expiração Atual: esta tabela contém um resumo de série temporal para as suas versões tal como estão. Tem as seguintes colunas:
1. Data: a primeira coluna representa a data.
2. NumberOfVersionsAvailable: o número de versões disponíveis nessa data ao abrigo da agenda atual.
3. NumberOfVersionsExpired: o número de versões expirou nessa data de acordo com a agenda atual.
4. SizeOfVersionsExpiredMB: o tamanho das versões expirou nessa data de acordo com a agenda atual.
Agenda de Expiração de Destino: esta tabela é igual à Agenda de Expiração Atual, mas reflete antes a agenda atualizada. Esta tabela só é útil se quiser testar diferentes cenários de expiração ao alterar a coluna TargetExpirationDate no relatório de expiração da versão do ficheiro.
Ficheiros com Menos de 10 Versões: uma lista dos URLs e o número de versões antes e depois da eliminação dos ficheiros cujo número de versões é inferior a 10 após a eliminação imediata (mas foi mais de 10 antes da eliminação imediata).
Utilizadores Afetados: os utilizadores cujas versões seriam imediatamente eliminadas.

Opcionalmente, pode ajustar os parâmetros:

TimelineStartDate: a data de início da Tabela 1 e 2 acima.
TimelineStepDays: o número de dias entre linhas para a Tabela 1 e 2 acima.
TimelineNumSteps: o número de linhas a calcular para a Tabela 1 e 2 acima.
ShowFilesWithFewerThanNVersions: o limiar do número de versões na Tabela 3 acima.

Compartilhar via

Tutorial: Gerar e analisar o relatório de utilização de versões do site SharePoint

Antes de começar

Gerar relatório de utilização de versões para sites ou bibliotecas

Verificar o progresso na geração de relatórios

Compreender o ficheiro de relatório de versão

Analisar o armazenamento de versões dos sites

Opção um: Analisar o relatório com o Excel

Opção dois: Analisar o relatório com o PowerShell

Comentários

Recursos adicionais