Usar o PowerShell para resolve URLs do site em relatórios

Artigo
03/09/2024

Este artigo aborda como usar o PowerShell para exibir URLs do site em relatórios.

Como funciona

O API do Graph fornece uma API que permite listar todos os sites dentro de uma organização. Para usar essa API, você precisa ter um aplicativo com a permissão Sites.Read.All.

O script invoca esse ponto de extremidade da API para obter o mapeamento entre IDs do site e URLs do site e, em seguida, adiciona as URLs do site aos relatórios CSV exportados.

Por que não usar permissões delegadas?

A API /sites/getAllSites aceita apenas permissões de aplicativo.
A API /sites?search=* aceita permissões delegadas, mas não retorna todos os sites, mesmo usando uma conta de administrador.

Etapas

Para exibir URLs do site usando o PowerShell, siga estas etapas.

Criar um aplicativo de ID do Entra

Vá para centro de administração do Microsoft Entra>Applications>Registros de aplicativo.
Na página Registros de aplicativo, selecione Novos registros.
Escolha um nome para este aplicativo e use a configuração padrão para registrar o aplicativo.

Lembre-se de que a ID do cliente e a ID do locatário são exibidas na seção Essentials do aplicativo.

Captura de tela mostrando os campos da ID do cliente e do campo realçados.

Adicionar API do Graph permissão ao aplicativo

Na página de permissões de API de Solicitação do novo aplicativo, adicione a permissão Sites.Read.All.

Em seguida, conceda o consentimento do administrador.

Criar um segredo do cliente

Na seção Certificados & segredos do novo aplicativo, crie um novo segredo do cliente. Em seguida, armazene o valor do segredo em um lugar seguro e seguro.

Baixe os relatórios no Centro de administração do Microsoft 365

Baixe o relatório de detalhes do site nas duas páginas de relatório e coloque os arquivos de relatório CSV em uma pasta local.

Antes de baixar os relatórios, desative a configuração de privacidade para obter detalhes do usuário. Para obter detalhes, consulte Centro de administração do Microsoft 365 relatórios de atividades.

Para uso do site do SharePoint, acesse a página de uso do site do SharePoint no Centro de administração do Microsoft 365.

Para uso do site do OneDrive, acesse a página de uso do site do OneDrive no Centro de administração do Microsoft 365.

Atualizar os relatórios com URLs do site

Para atualizar os relatórios com URLs do site, execute o script do PowerShell.

.\Update-Report.ps1 -**tenantId** {tenant id above} -**clientId** {client id above} -**reportPaths** @("file path for report \#1", "file path for report \#2")

Para exibir o script do PowerShell Update-Report completo, confira PowerShell de relatório de atualização.

O script pedirá que você insira o valor do segredo criado acima.

Depois de executar o script, novas versões dos relatórios são criadas com URLs do site adicionadas.

Limpar o ambiente

Para limpo o ambiente, volte para a página Certificados & segredos do aplicativo e exclua o segredo que foi criado anteriormente.

Dica

Use O SSD (Unidade de Estado Sólido) para melhorar o desempenho de E/S. Execute o script em um computador com memória livre/não utilizado suficiente. O cache leva cerca de 2 GB para os 15 milhões de sites.

Update-Report script do PowerShell

A seguir está o script do PowerShell para Atualização-Relatório.

 param(
 [Parameter(Mandatory=$true)]
 [string]$tenantId,
 [Parameter(Mandatory=$true)]
 [string]$clientId,
 [Parameter(Mandatory=$false)]
 [string[]]$reportPaths
)

function Get-AccessToken {
 param(
     [Parameter(Mandatory=$true)]
     [string]$tenantId,
     [Parameter(Mandatory=$true)]
     [string]$clientId,
     [Parameter(Mandatory=$true)]
     [System.Security.SecureString]$clientSecret,
     [Parameter(Mandatory=$false)]
     [string]$scope = "https://graph.microsoft.com/.default"
 )

 $tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0/token"
 $tokenRequest = @{
     client_id     = $clientId
     scope         = $scope
     client_secret = ConvertFrom-SecureString $clientSecret -AsPlainText
     grant_type    = "client_credentials"
 }

 $tokenResponse = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $tokenRequest
 return $tokenResponse.access_token
}

Preparar o cache e o segredo do cliente

if ($reportPaths.Count -eq 0) {
  Write-Host "Please provide at least one report path" -ForegroundColor Red
  exit
}
$cache = New-Object 'System.Collections.Generic.Dictionary[[String],[String]]'
$clientSecret = Read-Host "Please enter client secret" -AsSecureString

Buscar informações do site de API do Graph

Write-Host
Write-Host "Getting information for all the sites..." -ForegroundColor Cyan

$uri = "https://graph.microsoft.com/v1.0/sites/getAllSites?`$select=sharepointIds&`$top=10000"
while ($uri -ne $null) {

  Write-Host $uri

  $isSuccess = $false
  while (-not $isSuccess) {
      try {
          $accessToken = Get-AccessToken -tenantId $tenantId -clientId $clientId -clientSecret $clientSecret
          $restParams = @{Headers=@{Authorization="Bearer $accessToken"}}
      }
      catch {
          Write-Host "Retrying...  $($_.Exception.Message)" -ForegroundColor Yellow
          continue
      }
      try {
          $sites = Invoke-RestMethod $uri @restParams
          $isSuccess = $true
      }
      catch {
          if ($_.Exception.Response -and $_.Exception.Response.Headers['Retry-After']) {
              $retryAfter = [int]$_.Exception.Response.Headers['Retry-After']
              Write-Output "Waiting for $retryAfter seconds before retrying..." -ForegroundColor Yellow
              Start-Sleep -Seconds $retryAfter
          }
          Write-Host "Retrying...  $($_.Exception.Message)" -ForegroundColor Yellow
          continue
      }
  }

  $sites.value | ForEach-Object {
      $cache[$_.sharepointIds.siteId] = $_.sharepointIds.siteUrl
  }

  $uri = $sites."@odata.nextLink"

  Write-Host "Total sites received: $($cache.Count)"
}

Atualizar o relatório usando informações de site armazenados em cache

foreach ($reportPath in $reportPaths) {
  Write-Host
  Write-Host "Updating report $($reportPath) ..." -ForegroundColor Cyan

  $outputPath = "$($reportPath)_$([Math]::Floor((Get-Date -UFormat %s))).csv"
  $writer = [System.IO.StreamWriter]::new($outputPath)
  $reader = [System.IO.StreamReader]::new($reportPath)
  $rowCount = 0

  while ($null -ne ($line = $reader.ReadLine())) {
      $rowCount++

      $columns = $line.Split(",")
      $siteId = $columns[1]

      $_guid = New-Object System.Guid
      if ([System.Guid]::TryParse($siteId, [ref]$_guid)) {
          $siteUrl = $cache[$siteId]
          $columns[2] = $siteUrl
          $line = $columns -join ","
      }
      
      $writer.WriteLine($line)

      if ($rowCount%1000 -eq 0) {
          Write-Host "Processed $($rowCount) rows"
      }
  }
  $writer.Close()
  $reader.Close()

  Write-Host "Processed $($rowCount) rows"
  Write-Host "Report updated: $($outputPath)" -ForegroundColor Cyan
}

Finalizar

Write-Host
Read-Host "Press any key to exit..."

Opção adicional para cenários de pequena escala

Para cenários de menor escala, os administradores com acesso apropriado podem usar a API REST do SharePoint ou o Microsoft API do Graph para recuperar informações sobre IDs do site referenciadas em relatórios afetados. A API REST do SharePoint pode ser usada para recuperar informações sobre uma ID de site específica.

Por exemplo, a seguinte solicitação de API REST do SharePoint recupera informações sobre o site da Contoso com a ID do site 15d43f38-ce4e-4f6b-bac6-766ece1fbcb4:

https://contoso.sharepoint.com/_api/v2.1/sites/contoso.sharepoint.com,15d43f38-ce4e-4f6b-bac6-766ece1fbcb4

O microsoft API do Graph pode ser usado para listar sites do SharePoint ou recuperar informações sobre uma ID de site específica. Para obter detalhes, confira Tipo de recurso do site.

Por exemplo:

https://graph.microsoft.com/v1.0/sites?search=*&$select=sharepointIds
https://graph.microsoft.com/v1.0/sites/{siteId}

O microsoft API do Graph também pode ser usado para recuperar informações sobre um determinado site de OneDrive for Business do usuário. Para obter detalhes, consulte tipo de recurso de unidade.