Tutorial: Gerar e analisar o relatório de uso de versão do site do SharePoint

Ao compreender o armazenamento de versão em um site, você pode otimizar melhor as configurações do histórico de versão para atender aos objetivos de recuperação da sua organização e gerenciar os custos de armazenamento.

Este tutorial mostra como você pode gerar um relatório de uso de armazenamento de versão e analisá-lo para entender melhor o volume de armazenamento da versão do site. O relatório também pode ser usado para executar uma análise hipotética da aplicação de diferentes limites de versão ou do corte de versões existentes.

Neste tutorial, abordamos como:

• Gere o arquivo de relatório de uso de armazenamento de versão para o site ou biblioteca.
• Verifique o progresso da geração do relatório.
• Entenda o arquivo de relatório.
• Analise o uso do armazenamento da versão usando o Excel ou o PowerShell.

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

Antes de começar

1. Identifique o site do SharePoint, a conta do OneDrive ou a biblioteca de documentos cujo uso de armazenamento de versão você deseja entender.
2. Escolha um local na biblioteca de documentos do SharePoint no qual você deseja salvar o relatório.
3. Baixe o Shell de Gerenciamento do SharePoint Online mais recente.

Gerar relatório de uso de versão para sites ou biblioteca

Você pode gerar um relatório sobre o uso de armazenamento da versão atual em um site executando o New-SPOSiteFileVersionExpirationReportJob comando ou em uma biblioteca executando o New-SPOListFileVersionBatchDeleteJob comando.

No exemplo a seguir, um trabalho é enfileirado para gerar um relatório com escopo de site no local 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 a seguir, um trabalho é enfileirado para gerar um relatório com escopo de biblioteca no local 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"

Verifique o progresso na geração do relatório

Use o Get-SPOListFileVersionExpirationReportJobProgress comando para acompanhar o progresso da solicitação de geração de relatório.

O exemplo abaixo mostra como você pode marcar se o relatório com escopo do site está 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 você pode marcar se o relatório com escopo da biblioteca está 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 retornará uma resposta no formato JSON. A resposta json retornada tem uma chave chamada status. Consulte a tabela abaixo para um dos seguintes valores esperados:

Entender o arquivo de relatório de versão

O relatório gerado está no formato CSV e cada linha corresponde a uma versão do arquivo. Aqui está um exemplo do relatório de expiração da versão do arquivo e seu detalhamento de coluna.

A primeira linha é o cabeçalho com os identificadores de coluna contendo identificadores de versão de arquivo, informações de metadados de versão e carimbo de data/hora de expiração. Colunas compactas são indicadas com .Compact post-fix que não repetirá valores se duas linhas consecutivas tiverem o mesmo valor. As outras linhas representam versões de arquivo, em que cada linha representa uma única versão.
Vamos examinar a primeira versão do arquivo exibida neste relatório.

• Os identificadores de versão de arquivo: WebId, DocId, MajorVersione MinorVersion identificam exclusivamente cada versão em seu site do SharePoint.

• Identificadores de metadados de versão:WebUrl indica a versão em https://contoso.sharepoint.come FileUrl indica que o arquivo dessa versão está localizado em DocLib/MyDocument.docx. Em outras palavras, ele está em uma biblioteca de documentos chamada DocLib, enquanto o arquivo está na pasta raiz e DocLib é nomeado MyDocument.docx.

• Size Indica que a versão ocupa 92.246 bytes de armazenamento.

• As próximas duas colunas ModifiedBy_UserId indicam ModifiedBy_DisplayName que a usuária Michelle Harris (com ID de usuário 6) criou essa versão.

• LastModifiedDate indica que o conteúdo da versão foi modificado pela última vez em 13 de março de 2023, às 22:36:09 UTC. SnapshotDate exibe que a versão se tornou uma versão histórica em 20 de março de 2023, às 16:56:51 UTC. IsSnapshotDateEstimatedmostra que SnapshotDate é a data real do snapshot.

• Identificadores de agendamento 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, essa versão também está definida para nunca expirar. TargetExpirationDate Indica que, se seguirmos este cronograma de corte, definiremos esta versão para nunca expirar.

Vejamos a terceira versão.

Os WebId valores and DocId estão vazios porque essas colunas são colunas compactas, indicadas por . Pós-correção compacta , significa que eles devem ter valores. Se procurarmos o último não vazio acima dessa linha, encontraremos WebId como 4c7a58c1-01f2-4fa3-a730-44081a44f689, e DocId como 18c3e09c-b5be-48e7-a754-7a2ce53e0999.

Também podemos ver que o TargetExpirationDate está marcado para 19 de abril de 2023, às 18:08:53 UTC. Isso significa que, se cortarmos com base nessa programação, definiremos a data de expiração desta versão para esse momento.

Analisar o armazenamento de versão dos sites

Antes de iniciar sua análise, você deve atualizar a TargetExpirationDate coluna no arquivo de relatório para as datas desejadas, como as versões a serem expiradas. Novamente, se você escolher uma data que está no passado para uma versão, essa versão será tratada como "versão que já expirou" e será excluída imediatamente após iniciar o corte.

Você pode atualizar manualmente as datas TargetExpirationDate editando o arquivo csv. No entanto, você pode ter muitas linhas para atualizar manualmente. Para atualizar a coluna em massa, você pode usar fórmulas do Excel ou também usar um dos scripts do PowerShell que fornecemos no Tutorial: Executar análise "What If". Especificamente, você pode escolher um modo de corte, executar o script correspondente para obter um arquivo csv atualizado com TargetExpirationDate preenchimento com base nesse modo de corte e continuar a partir daí.

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

Abra a pasta de trabalho compartilhada do Excel AnalyzeReportFile_Template.xlsx. Você pode encontrar as seguintes planilhas nele.

• Configuração: Use esta planilha para definir o intervalo de datas para gerar as diferentes exibições de relatório.
• Conjunto de dados: esta planilha é o conjunto de dados bruto importado do arquivo de relatório. Várias exibições de resumo de relatórios são construídas a partir desse conjunto de dados.
• Relatórios predefinidos: aqui está uma lista de exibições predefinidas que podem ser usadas para entender o impacto da aplicação da configuração selecionada em versões armazenadas no site:
  • Resumo: analise o estado atual do armazenamento de versão para este site e excluiu a distribuição de versão nas novas configurações.
  • Usuários afetados: examine os usuários cujas versões seriam afetadas nas novas configurações.
  • Contagem de versões: uma tabela e um gráfico mostrando os números de versões que estarão disponíveis ao longo do tempo na agenda atual e o número de versões que estarão disponíveis na nova programação.
  • Análise de tamanho de versão: Compare o tamanho das versões que serão excluídas ao longo do tempo sob a agenda atual e o número de versões que estarão disponíveis sob a nova agenda.
  • Análise de Nível de Arquivo: revise as exclusões de versão no nível de arquivo nas novas configurações.

Preencha a pasta de trabalho seguindo estas etapas:

1. Na planilha de configuração , insira o caminho completo para o arquivo de relatório What-If na célula B3.

   

2. Se você quiser alterar o intervalo de datas dos gráficos na planilha Número de Versões Disponíveis ou Tamanho da planilha Versões Expiradas , altere os valores correspondentes nas Células B6, B7, B10 e/ou B11. Ele é opcional.

   

3. Na parte superior do Excel, selecione a guia Dados e, na Faixa de Opções, selecione o botão Atualizar Tudo .

   

4. Na planilha Análise de Nível de Arquivo , preencha automaticamente as colunas Número de Versões e Número de Versões Restantes Após a Exclusão .

   

   

   Dica

   Você pode selecionar a célula com os dados e clicar duas vezes na alça de preenchimento para concluir o preenchimento automático.

5. Na planilha Usuários Afetados , preencha automaticamente a coluna Número de Versões Serão Excluídas .

   

Todas as planilhas agora devem estar atualizadas. Você pode marcar as informações de seu interesse.

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

1. Salve o script como um arquivo chamado 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

2. Abra o PowerShell e execute o seguinte comando, substituindo os valores de espaço reservado pelos valores apropriados.

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

3. A saída exibe quatro tabelas:

• Cronograma de expiração atual: esta tabela contém um resumo de séries temporais para suas versões como elas são. Ele tem as seguintes colunas:

  1. Data: a primeira coluna representa a data.
  2. NumberOfVersionsAvailable: o número de versões disponíveis nessa data de acordo com a agenda atual.
  3. NumberOfVersionsExpired: o número de versões expiradas nessa data de acordo com a agenda atual.
  4. SizeOfVersionsExpiredMB: o tamanho das versões expiradas nessa data de acordo com a agenda atual.

  

• Target Expiration Schedule: esta tabela é igual à Agenda de Expiração Atual, mas reflete a agenda atualizada. Esta tabela só será útil se você quiser testar diferentes cenários de expiração alterando a coluna TargetExpirationDate no relatório de expiração da versão do arquivo.

  

• Files with Less than 10 Versions: uma lista das URLs e o número de versões antes e depois da exclusão para aqueles arquivos cujo número de versões é inferior a 10 após a exclusão imediata (mas era mais de 10 antes da exclusão imediata).

  

• Usuários afetados: os usuários cujas versões seriam excluídas imediatamente.

  

Opcionalmente, você pode ajustar os parâmetros:

• TimelineStartDate: a data de início dos quadros 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 os quadros 1 e 2 acima.
• ShowFilesWithFewerThanNVersions: o limiar para o número de versões no quadro 3 acima.