Compartilhar via

Acessar o log de atividades do Power BI

  • Artigo

Este artigo se destina a administradores do Power BI que precisam acessar e analisar dados originados do log de atividades do Power BI. Ele se concentra na recuperação programática das atividades do Power BI usando o cmdlet Get-PowerBIActivityEvent do módulo Gerenciamento do Power BI. Até 30 dias de histórico estão disponíveis. Esse cmdlet usa a operação Obter Eventos de Atividade da API REST do Power BI, que é uma API de administrador. Os cmdlets do PowerShell adicionam uma camada de abstração sobre as APIs subjacentes. Portanto, o cmdlet do PowerShell simplifica o acesso ao log de atividades do Power BI.

Há outras maneiras manuais e programáticas de recuperar atividades do Power BI. Para obter mais informações, confira Acessar dados de atividade do usuário.

A análise do log de atividades do Power BI é crucial para governança e conformidade e para acompanhar os esforços de adoção. Para obter mais informações sobre o log de atividades do Power BI, confira Rastrear atividades do usuário no Power BI.

Dica

Recomendamos que você examine totalmente o artigo Auditoria no nível do locatário. Este artigo aborda o planejamento, as principais decisões, os pré-requisitos e as principais atividades de desenvolvimento de solução a serem consideradas ao criar uma solução de auditoria de ponta a ponta.

Exemplos disponíveis

O objetivo deste artigo é fornecer exemplos para ajudar você a começar. Os exemplos incluem scripts que recuperam dados do log de atividades usando o módulo PowerShell de Gerenciamento do Power BI.

Aviso

Os scripts não estão prontos para produção porque são destinados apenas para fins educacionais. No entanto, você pode adaptar os scripts para fins de produção adicionando lógica para registro em log, tratamento de erros, alertas e refatoração para reutilização e modularização de código.

Como eles têm fins de aprendizado, os exemplos são simplistas, mas são do mundo real. Recomendamos que você examine todos os exemplos para entender como eles aplicam técnicas ligeiramente diferentes. Depois de identificar o tipo de dados de atividade necessários, você poderá misturar e corresponder às técnicas para produzir um script que melhor atenda às suas necessidades.

Este artigo inclui os exemplos a seguir.

Nome de exemplo Tipo de dados de atividade
Autenticar com o serviço do Power BI N/D
Exibir todas as atividades de um usuário em um dia Tudo
Exibir uma atividade para N dias Compartilhar relatório (link ou acesso direto)
Exibir três atividades para N dias Criar aplicativo, atualizar aplicativo e instalar aplicativo
Exibir todas as atividades de um workspace em um dia Tudo
Exportar todas as atividades dos últimos N dias Tudo

Para simplificar, a maioria dos exemplos gera o resultado para a tela. Por exemplo, no Visual Studio Code, os dados são gerados para o painel de terminal, que contém um conjunto de buffers de dados na memória.

A maioria dos exemplos recupera dados JSON brutos. Trabalhar com os dados JSON brutos tem muitas vantagens.

  • Todas as informações disponíveis para cada evento de atividade são retornadas. Isso é útil para você saber quais dados estão disponíveis. Tenha em mente que o conteúdo de uma resposta de API é diferente dependendo do evento de atividade real. Por exemplo, os dados disponíveis para um evento CreateApp são diferentes do evento ViewReport.
  • Como os dados disponíveis no log de atividades mudam à medida que o Power BI evolui ao longo do tempo, você também pode esperar que as respostas à API sejam alteradas. Dessa forma, novos dados introduzidos não serão perdidos. Seu processo também é mais resiliente a alterações e menos propenso a falhar.
  • Os detalhes de uma resposta da API podem ser diferentes para a nuvem comercial do Power BI e para as nuvens nacionais/regionais.
  • Se você tiver diferentes membros da equipe (como engenheiros de dados) que se envolvem com esse processo, simplificar o processo inicial para extrair os dados facilita o trabalho de várias equipes em conjunto.

Dica

Recomendamos que você mantenha seus scripts que extraem dados o mais simples possível. Portanto, evite analisar, filtrar ou formatar os dados do log de atividades conforme eles são extraídos. Essa abordagem usa uma metodologia ELT, que tem etapas separadas para Extrair, Carregar e Transformar dados. Este artigo se concentra apenas na primeira etapa, que se preocupa com a extração dos dados.

Requisitos

Para usar os scripts de exemplo, você deve atender aos seguintes requisitos.

  • Ferramenta de cliente do PowerShell: Use sua ferramenta preferida para executar comandos do PowerShell. Todos os exemplos foram testados usando a extensão do PowerShell para Visual Studio Code com o PowerShell 7. Para obter informações sobre ferramentas de cliente e versões do PowerShell, confira Auditoria no nível do locatário.
  • Módulo de gerenciamento do Power BI: Instale todos os módulos do PowerShell do Power BI. Se você os instalou anteriormente, recomendamos que você atualize os módulos para garantir que você esteja usando a versão publicada mais recente.
  • Função de administrador do Fabric: os scripts de exemplo são projetados para usar um fluxo de autenticação interativo. Portanto, o usuário que executa os scripts de exemplo do PowerShell deve entrar para usar as APIs REST do Power BI. Para recuperar dados do log de atividades, o usuário autenticador deve pertencer à função de administrador do Power BI (porque a recuperação de eventos de atividade é feita com uma API de administrador). A autenticação da entidade de serviço está fora do escopo desses exemplos de aprendizagem.

O restante deste artigo inclui scripts de exemplo que mostram diferentes maneiras de recuperar dados do log de atividades.

Exemplo 1: Autenticar com o serviço do Power BI

Todas as operações da API REST do Power BI exigem que você entre. A autenticação (quem está fazendo a solicitação) e a autorização (o que o usuário tem permissão para fazer) são gerenciadas pela plataforma de identidade da Microsoft. O exemplo a seguir usa o cmdlet Connect-PowerBIServiceAccount do módulo Gerenciamento do Power BI. Esse cmdlet dá suporte a um método simples para entrar.

Exemplo de solicitação 1

O primeiro script redireciona você para um navegador para concluir o processo de entrada. As contas de usuário que têm a autenticação multifator (MFA) habilitada podem usar esse fluxo de autenticação interativa para entrar.

Connect-PowerBIServiceAccount

Importante

Os usuários sem privilégios de administrador do Power BI não podem executar nenhum dos scripts de exemplo a seguir neste artigo. Os administradores do Power BI têm permissão para gerenciar o serviço do Power BI e recuperar metadados em todo o locatário (como dados do log de atividades). Embora o uso da autenticação da entidade de serviço esteja fora do escopo para esses exemplos, é altamente recomendável que você configure uma entidade de serviço para scripts autônomos prontos para produção que serão executados em um agendamento.

Certifique-se de entrar antes de executar qualquer um dos scripts a seguir.

Exemplo 2: exibir todas as atividades de um usuário por um dia

Às vezes, você precisa marcar todas as atividades que um usuário específico realizou em um dia específico.

Dica

Ao extrair dados do log de atividades usando o cmdlet do PowerShell, cada solicitação pode extrair dados por um dia (no máximo 24 horas). Portanto, o objetivo deste exemplo é começar simplesmente verificando um usuário por um dia. Há outros exemplos posteriormente neste artigo que mostram como usar um loop para exportar dados por vários dias.

Exemplo de solicitação 2

Esse script declara duas variáveis do PowerShell para facilitar a reutilização do script:

  • $UserEmailAddr: o endereço de email do usuário no qual você está interessado.
  • $ActivityDate: a data em que você está interessado. O formato é AAAA-MM-DD (formato ISO 8601). Você não pode solicitar uma data anterior a 30 dias antes da data atual.
#Input values before running the script:
$UserEmailAddr = 'jordan@contoso.com'
$ActivityDate = '2023-03-15'
#----------------------------------------------------------------------
#View activity events:
Get-PowerBIActivityEvent `
    -StartDateTime ($ActivityDate + 'T00:00:00.000') `
    -EndDateTime ($ActivityDate + 'T23:59:59.999') `
    -User $UserEmailAddr

Observação

Pode haver um caractere de acento grave (`) no final de algumas das linhas nos scripts do PowerShell. No PowerShell, uma maneira de usar o caractere de acento grave é como um caractere de continuação de linha. Nós o usamos para melhorar a legibilidade dos scripts neste artigo.

Dica

No script, cada uma das variáveis do PowerShell se correlaciona a um valor de parâmetro obrigatório ou opcional no cmdlet Get-PowerBIActivityEvent. Por exemplo, o valor que você atribui à variável $UserEmailAddr é passado para o parâmetro -User. Declarar variáveis do PowerShell dessa forma é uma abordagem leve para evitar valores de codificação rígida que podem ser alterados em seu script. Esse é um bom hábito a ser adotado e será útil à medida que seus scripts se tornarem mais complexos. Os parâmetros do PowerShell são mais robustos do que as variáveis, mas estão fora do escopo deste artigo.

Resposta de exemplo 2

Esta é uma resposta JSON de exemplo. Ele inclui duas atividades realizadas pelo usuário:

  • A primeira atividade mostra que um usuário visualizou um relatório.
  • A segunda atividade mostra que um administrador exportou dados do log de atividades do Power BI.
[
  {
    "Id": "10af656b-b5a2-444c-bf67-509699896daf",
    "RecordType": 20,
    "CreationTime": "2023-03-15T15:18:30Z",
    "Operation": "ViewReport",
    "OrganizationId": "927c6607-8060-4f4a-a5f8-34964ac78d70",
    "UserType": 0,
    "UserKey": "100FFF92C7717B",
    "Workload": "PowerBI",
    "UserId": "jordan@contoso.com",
    "ClientIP": "192.168.1.1",
    "Activity": "ViewReport",
    "ItemName": "Gross Margin Analysis",
    "WorkSpaceName": "Sales Analytics",
    "DatasetName": "Sales Data",
    "ReportName": "Gross Margin Analysis",
    "WorkspaceId": "e380d1d0-1fa6-460b-9a90-1a5c6b02414c",
    "ObjectId": "Gross Margin Analysis",
    "DatasetId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
    "ReportId": "94e57e92-Cee2-486d-8cc8-218c97200579",
    "ArtifactId": "94e57e92-Cee2-486d-8cc8-218c97200579",
    "ArtifactName": "Gross Margin Analysis",
    "IsSuccess": true,
    "ReportType": "PowerBIReport",
    "RequestId": "53451b83-932b-f0b0-5328-197133f46fa4",
    "ActivityId": "beb41a5d-45d4-99ee-0e1c-b99c451e9953",
    "DistributionMethod": "Workspace",
    "ConsumptionMethod": "Power BI Web",
    "SensitivityLabelId": "e3dd4e72-5a5d-4a95-b8b0-a0b52b827793",
    "ArtifactKind": "Report"
  },
  {
    "Id": "5c913f29-502b-4a1a-a089-232edaf176f7",
    "RecordType": 20,
    "CreationTime": "2023-03-15T17:22:00Z",
    "Operation": "ExportActivityEvents",
    "OrganizationId": "927c6607-8060-4f4a-a5f8-34964ac78d70",
    "UserType": 2,
    "UserKey": "100FFF92C7717B",
    "Workload": "PowerBI",
    "UserId": "jordan@contoso.com",
    "ClientIP": "192.168.1.1",
    "UserAgent": "MicrosoftPowerBIMgmt/1.2.1111.0",
    "Activity": "ExportActivityEvents",
    "IsSuccess": true,
    "RequestId": "2af6a22d-6f24-4dc4-a26a-5c234ab3afad",
    "ActivityId": "00000000-0000-0000-0000-000000000000",
    "ExportEventStartDateTimeParameter": "2023-03-17T00:00:00Z",
    "ExportEventEndDateTimeParameter": "2023-03-17T23:59:59.999Z"
  }
]

Dica

Extrair os dados do log de atividades do Power BI também é uma operação registrada, conforme mostrado na resposta anterior. Ao analisar as atividades do usuário, convém omitir atividades de administrador ou analisá-las separadamente.

Exemplo 3: Exibir uma atividade por N dias

Às vezes, talvez você queira investigar um tipo específico de atividade por uma série de dias. Este exemplo mostra como recuperar atividades de compartilhamento de relatório por item . Ele usa um loop para recuperar atividades dos sete dias anteriores.

Solicitação de exemplo 3

O script declara duas variáveis:

  • $ActivityType: o nome da operação para a atividade que você está investigando.
  • $NbrOfDaysToCheck: quantos dias você está interessado em verificar. Ele executa um loop trabalhando para trás a partir do dia atual. O valor máximo permitido é de 30 dias (porque a data mais antiga que você pode recuperar é 30 dias antes do dia atual).
#Input values before running the script:
$ActivityType = 'ShareReport' 
$NbrOfDaysToCheck = 7 
#-----------------------------------------------------------------------

#Use today to start counting back the number of days to check:
$DayUTC = (([datetime]::Today.ToUniversalTime()).Date)

#Iteratively loop through each of the last N days to view events:
For($LoopNbr=0; $LoopNbr -le $NbrOfDaysToCheck; $LoopNbr++)
{
    $PeriodStart=$DayUTC.AddDays(-$LoopNbr)
    $ActivityDate=$PeriodStart.ToString("yyyy-MM-dd")
    Write-Verbose "Checking $ActivityDate" -Verbose 

    #Check activity events once per loop (once per day):
    Get-PowerBIActivityEvent `
        -StartDateTime ($ActivityDate + 'T00:00:00.000') `
        -EndDateTime ($ActivityDate + 'T23:59:59.999') `
        -ActivityType $ActivityType 
}

Dica

Você pode usar essa técnica de looping para marcar qualquer uma das operações registradas no log de atividades.

Resposta de exemplo 3

Esta é uma resposta JSON de exemplo. Inclui duas atividades realizadas pelo usuário:

  • A primeira atividade mostra que um link de compartilhamento para um usuário foi criado. Observe que o valor SharingAction difere dependendo se o usuário criou um link, editou um link ou excluiu um link. Para resumir, apenas um tipo de atividade de link de compartilhamento é mostrado na resposta.
  • A segunda atividade mostra que o compartilhamento de acesso direto para um grupo foi criado. Observe que o valor SharingInformation difere dependendo da ação executada. Para resumir, apenas um tipo de atividade de compartilhamento de acesso direto é mostrado na resposta.
[
  {
    "Id": "be7506e1-2bde-4a4a-a210-bc9b156142c0",
    "RecordType": 20,
    "CreationTime": "2023-03-15T19:52:42Z",
    "Operation": "ShareReport",
    "OrganizationId": "927c6607-8060-4f4a-a5f8-34964ac78d70",
    "UserType": 0,
    "UserKey": "900GGG12D2242A",
    "Workload": "PowerBI",
    "UserId": "morgan@contoso.com",
    "ClientIP": "192.168.1.1",
    "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/110.0",
    "Activity": "ShareReport",
    "ItemName": "Call Center Stats",
    "WorkSpaceName": "Sales Analytics",
    "SharingInformation": [
      {
        "RecipientEmail": "ellis@contoso.com",
        "RecipientName": "Turner",
        "ObjectId": "fc9bbc6c-e39b-44cb-9c8a-d37d5665ec57",
        "ResharePermission": "ReadReshare",
        "UserPrincipalName": "ellis@contoso.com"
      }
    ],
    "WorkspaceId": "e380d1d0-1fa6-460b-9a90-1a5c6b02414c",
    "ObjectId": "Call Center Stats",
    "Datasets": [
      {
        "DatasetId": "fgagrwa3-9044-3e1e-228f-k24bf72gg995",
        "DatasetName": "Call Center Data"
      }
    ],
    "ArtifactId": "81g22w11-vyy3-281h-1mn3-822a99921541",
    "ArtifactName": "Call Center Stats",
    "IsSuccess": true,
    "RequestId": "7d55cdd3-ca3d-a911-5e2e-465ac84f7aa7",
    "ActivityId": "4b8b53f1-b1f1-4e08-acdf-65f7d3c1f240",
    "SharingAction": "CreateShareLink",
    "ShareLinkId": "J_5UZg-36m",
    "ArtifactKind": "Report",
    "SharingScope": "Specific People"
  },
  {
    "Id": "b4d567ac-7ec7-40e4-a048-25c98d9bc304",
    "RecordType": 20,
    "CreationTime": "2023-03-15T11:57:26Z",
    "Operation": "ShareReport",
    "OrganizationId": "927c6607-8060-4f4a-a5f8-34964ac78d70",
    "UserType": 0,
    "UserKey": "900GGG12D2242A",
    "Workload": "PowerBI",
    "UserId": "morgan@contoso.com",
    "ClientIP": "69.132.26.0",
    "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/111.0",
    "Activity": "ShareReport",
    "ItemName": "Gross Margin Analysis",
    "WorkSpaceName": "Sales Analytics",
    "SharingInformation": [
      {
        "RecipientName": "SalesAndMarketingGroup-NorthAmerica",
        "ObjectId": "ba21f28b-6226-4296-d341-f059257a06a7",
        "ResharePermission": "Read"
      }
    ],
    "CapacityId": "1DB44EEW-6505-4A45-B215-101HBDAE6A3F",
    "CapacityName": "Shared On Premium - Reserved",
    "WorkspaceId": "e380d1d0-1fa6-460b-9a90-1a5c6b02414c",
    "ObjectId": "Gross Margin Analysis",
    "Datasets": [
      {
        "DatasetId": "cfafbeb1-8037-4d0c-896e-a46fb27ff229",
        "DatasetName": "Sales Data"
      }
    ],
    "ArtifactId": "94e57e92-Cee2-486d-8cc8-218c97200579",
    "ArtifactName": "Gross Margin Analysis",
    "IsSuccess": true,
    "RequestId": "82219e60-6af0-0fa9-8599-c77ed44fff9c",
    "ActivityId": "1d21535a-257e-47b2-b9b2-4f875b19855e",
    "SensitivityLabelId": "16c065f5-ba91-425e-8693-261e40ccdbef",
    "SharingAction": "Direct",
    "ArtifactKind": "Report",
    "SharingScope": "Specific People"
  }
]

Observação

Essa resposta JSON mostra que a estrutura de dados é diferente com base no tipo de evento. Mesmo o mesmo tipo de evento pode ter características diferentes que produzem uma saída ligeiramente diferente. Conforme recomendado anteriormente neste artigo, você deve se acostumar a recuperar os dados brutos.

Exemplo 4: Exibir três atividades para N dias

Às vezes, talvez você queira investigar várias atividades relacionadas. Este exemplo mostra como recuperar três atividades específicas dos sete dias anteriores. Ele se concentra em atividades relacionadas a aplicativos do Power BI, incluindo a criação de um aplicativo, a atualização de um aplicativo e a instalação de um aplicativo.

Solicitação de exemplo 4

O script declara as seguintes variáveis:

  • $NbrOfDaysToCheck: quantos dias você está interessado em verificar. Ele executa um loop que funciona para trás a partir do dia atual. O valor máximo permitido é de 30 dias (porque a data mais antiga que você pode recuperar é 30 dias antes do dia atual).
  • $Activity1: o nome da operação para a primeira atividade que você está investigando. Neste exemplo, ele está procurando atividades de criação de aplicativo do Power BI.
  • $Activity2: o segundo nome da operação. Neste exemplo, ele está procurando atividades de atualização de aplicativo do Power BI.
  • $Activity3: o terceiro nome da operação. Neste exemplo, ele está pesquisando atividades de instalação de aplicativos do Power BI.

Você só pode recuperar eventos de atividade para uma atividade por vez. Portanto, o script pesquisa cada operação separadamente. Ele combina os resultados da pesquisa em uma variável chamada $FullResults, que, em seguida, gera os resultados para a tela.

Cuidado

Executar muitos loops muitas vezes aumenta consideravelmente a probabilidade de limitação da API. A limitação pode acontecer quando você excede o número de solicitações que você tem permissão para fazer em um determinado período de tempo. A operação Obter Eventos de Atividade é limitada a 200 solicitações por hora. Ao criar seus scripts, tome cuidado para não recuperar os dados originais mais vezes do que você precisa. Geralmente, é uma prática melhor extrair todos os dados brutos uma vez por dia e, em seguida, consultar, transformar, filtrar ou formatar esses dados separadamente.

O script mostra os resultados do dia atual.

Observação

Para recuperar apenas os resultados do dia anterior, evitando resultados parciais do dia, confira o exemplo Exportar todas as atividades dos N dias anteriores.)

#Input values before running the script:
$NbrOfDaysToCheck = 7
$Activity1 = 'CreateApp'
$Activity2 = 'UpdateApp'
$Activity3 = 'InstallApp'
#-----------------------------------------------------------------------
#Initialize array which will contain the full resultset:
$FullResults = @() 

#Use today to start counting back the number of days to check:
$DayUTC = (([datetime]::Today.ToUniversalTime()).Date)

#Iteratively loop through each day (<Initilize> ; <Condition> ; <Repeat>)
#Append each type of activity to an array:
For($LoopNbr=0; $LoopNbr -le $NbrOfDaysToCheck; $LoopNbr++)
{
    $PeriodStart=$DayUTC.AddDays(-$LoopNbr)
    $ActivityDate=$PeriodStart.ToString("yyyy-MM-dd")
    Write-Verbose "Checking $ActivityDate" -Verbose 

    #Get activity 1 and append its results into the full resultset:
    $Activity1Results = @()
    $Activity1Results += Get-PowerBIActivityEvent `
        -StartDateTime ($ActivityDate+'T00:00:00.000') `
        -EndDateTime ($ActivityDate+'T23:59:59.999') `
        -ActivityType $Activity1 | ConvertFrom-Json
    If ($null -ne $Activity1Results) {$FullResults += $Activity1Results}
    
    #Get activity 2 and append its results into the full resultset:
    $Activity2Results = @()
    $Activity2Results += Get-PowerBIActivityEvent `
        -StartDateTime ($ActivityDate+'T00:00:00.000') `
        -EndDateTime ($ActivityDate+'T23:59:59.999') `
        -ActivityType $Activity2 | 
    ConvertFrom-Json
    If ($null -ne $Activity2Results) {$FullResults += $Activity2Results}  

    #Get activity 3 and append its results into the full resultset:
    $Activity3Results = @()
    $Activity3Results += Get-PowerBIActivityEvent `
        -StartDateTime ($ActivityDate+'T00:00:00.000') `
        -EndDateTime ($ActivityDate+'T23:59:59.999') `
        -ActivityType $Activity3 | 
    ConvertFrom-Json
    If ($null -ne $Activity3Results) {$FullResults += $Activity3Results}
    
}  
#Convert all of the results back to a well-formed JSON object:
$FullResults = $FullResults | ConvertTo-Json

#Display results on the screen:
$FullResults

Resposta de exemplo 4

Esta é uma resposta JSON de exemplo. Inclui três atividades realizadas pelo usuário:

  • A primeira atividade mostra que um aplicativo do Power BI foi criado.
  • A segunda atividade mostra que um aplicativo do Power BI foi atualizado.
  • A terceira atividade mostra que um aplicativo do Power BI foi instalado por um usuário.

Aviso

A resposta inclui apenas as permissões de usuário que foram modificadas. Por exemplo, é possível que três públicos possam ter sido criados em um evento CreateApp. No evento UpdateApp, se apenas um público fosse alterado, apenas um público apareceria nos dados OrgAppPermission. Por esse motivo, confiar no evento UpdateApp para acompanhar todas as permissões de aplicativo está incompleto porque o log de atividades mostra apenas o que foi alterado.

Para obter um instantâneo de todas as permissões de aplicativo do Power BI, use a operação da API Obter Usuários de Aplicativo como Administrador.

[
  {
    "Id": "65a26480-981a-4905-b3aa-cbb3df11c7c2",
    "RecordType": 20,
    "CreationTime": "2023-03-15T18:42:13Z",
    "Operation": "CreateApp",
    "OrganizationId": "927c6607-8060-4f4a-a5f8-34964ac78d70",
    "UserType": 0,
    "UserKey": "100FFF92C7717B",
    "Workload": "PowerBI",
    "UserId": "jordan@contoso.com",
    "ClientIP": "192.168.1.1",
    "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/111.0",
    "Activity": "CreateApp",
    "ItemName": "Sales Reconciliations App",
    "WorkSpaceName": "Sales Reconciliations",
    "OrgAppPermission": {
      "recipients": "Sales Reconciliations App(Entire Organization)",
      "permissions": "Sales Reconciliations App(Read,CopyOnWrite)"
    },
    "WorkspaceId": "9325a31d-067e-4748-a592-626d832c8001",
    "ObjectId": "Sales Reconciliations App",
    "IsSuccess": true,
    "RequestId": "ab97a4f1-9f5e-4a6f-5d50-92c837635814",
    "ActivityId": "9bb54a9d-b688-4028-958e-4d7d21ca903a",
    "AppId": "42d60f97-0f69-470c-815f-60198956a7e2"
  },
  {
    "Id": "a1dc6d26-b006-4727-bac6-69c765b7978f",
    "RecordType": 20,
    "CreationTime": "2023-03-16T18:39:58Z",
    "Operation": "UpdateApp",
    "OrganizationId": "927c6607-8060-4f4a-a5f8-34964ac78d70",
    "UserType": 0,
    "UserKey": "100GGG12F9921B",
    "Workload": "PowerBI",
    "UserId": "morgan@contoso.com",
    "ClientIP": "192.168.1.1",
    "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/111.0",
    "Activity": "UpdateApp",
    "ItemName": "Sales Analytics",
    "WorkSpaceName": "Sales Analytics",
    "OrgAppPermission": {
      "recipients": "Sales Reps Audience(SalesAndMarketingGroup-NorthAmerica,SalesAndMarketingGroup-Europe)",
      "permissions": "Sales Reps Audience(Read,CopyOnWrite)"
    },
    "WorkspaceId": "c7bffcd8-8156-466a-a88f-0785de2c8b13",
    "ObjectId": "Sales Analytics",
    "IsSuccess": true,
    "RequestId": "e886d122-2c09-4189-e12a-ef998268b864",
    "ActivityId": "9bb54a9d-b688-4028-958e-4d7d21ca903a",
    "AppId": "c03530c0-db34-4b66-97c7-34dd2bd590af"
  },
  {
    "Id": "aa002302-313d-4786-900e-e68a6064df1a",
    "RecordType": 20,
    "CreationTime": "2023-03-17T18:35:22Z",
    "Operation": "InstallApp",
    "OrganizationId": "927c6607-8060-4f4a-a5f8-34964ac78d70",
    "UserType": 0,
    "UserKey": "100HHH12F4412A",
    "Workload": "PowerBI",
    "UserId": "ellis@contoso.com",
    "ClientIP": "192.168.1.1",
    "UserAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:109.0) Gecko/20100101 Firefox/111.0",
    "Activity": "InstallApp",
    "ItemName": "Sales Reconciliations App",
    "ObjectId": "Sales Reconciliations App",
    "IsSuccess": true,
    "RequestId": "7b3cc968-883f-7e13-081d-88b13f6cfbd8",
    "ActivityId": "9bb54a9d-b688-4028-958e-4d7d21ca903a"
  }
]

Exemplo 5: exibir todas as atividades de um workspace por um dia

Às vezes, talvez você queira investigar atividades relacionadas a um workspace específico. Este exemplo recupera todas as atividades para todos os usuários por um dia. Em seguida, ele filtra os resultados para que você possa se concentrar na análise de atividades de um workspace.

Solicitação de exemplo 5

O script declara duas variáveis:

  • $ActivityDate: a data em que você está interessado. O formato é AAAA-MM-DD. Você não pode solicitar uma data anterior a 30 dias antes da data atual.
  • $WorkspaceName: O nome do workspace de seu interesse.

O script armazena os resultados na variável $Results. Em seguida, ele converte os dados JSON em um objeto para que os resultados possam ser analisados. Em seguida, ele filtra os resultados para recuperar cinco colunas específicas. Os dados CreationTime são renomeados como ActivityDateTime. Os resultados são filtrados pelo nome do workspace e, em seguida, são gerados para a tela.

Não há um parâmetro para o cmdlet Get-PowerBIActivityEvent que permite especificar um workspace ao verificar o log de atividades (exemplos anteriores neste artigo usaram parâmetros do PowerShell para definir um nome de usuário, data ou atividade específico). Neste exemplo, o script recupera todos os dados e analisa a resposta JSON para filtrar os resultados de um workspace específico.

Cuidado

Se você estiver em uma grande organização que tenha centenas ou milhares de atividades por dia, filtrar os resultados depois que eles forem recuperados poderá ser muito ineficiente. Tenha em mente que a operação Obter Eventos de Atividade é limitada a 200 solicitações por hora.

Para evitar a limitação da API (quando você exceder o número de solicitações que você tem permissão para fazer em um determinado período de tempo), não recupere os dados originais mais do que você precisa. Você pode continuar a trabalhar com os resultados filtrados sem executar o script para recuperar os resultados novamente. Para necessidades contínuas, é uma prática recomendada extrair todos os dados uma vez por dia e consultá-los muitas vezes.

#Input values before running the script:
$ActivityDate = '2023-03-22'
$WorkspaceName = 'Sales Analytics'
#----------------------------------------------------------------------
#Run cmdlet to check activity events and store intermediate results:
$Events = Get-PowerBIActivityEvent `
    -StartDateTime ($ActivityDate+'T00:00:00.000') `
    -EndDateTime ($ActivityDate+'T23:59:59.999')
    
#Convert from JSON so we can parse the data:
$ConvertedResults = $Events | ConvertFrom-Json

#Obtain specific attributes and save to a PowerShell object:
$FilteredResults = $ConvertedResults `
    | 
    Select-Object `
    @{Name="ActivityDateTime";Expression={$PSItem.CreationTime}}, ` #alias name
    Activity, `
    UserId, `
    ArtifactName, `
    WorkspaceName `
    | 
    #Filter the results:
    Where-Object {($PSItem.WorkspaceName -eq $WorkspaceName)}

#View the filtered results:
$FilteredResults 

#Optional - Save back to JSON format:
#$FilteredResults = $FilteredResults | ConvertTo-Json -Depth 10
#$FilteredResults

Resposta de exemplo 5

Aqui estão os resultados filtrados, que incluem um pequeno subconjunto de propriedades. O formato é mais fácil de ler para análise ocasional. No entanto, é recomendável convertê-lo novamente no formato JSON se você planeja armazenar os resultados.

Observação

Depois de converter os resultados JSON em um objeto do PowerShell, os valores de hora são convertidos em hora local. Os dados de auditoria originais são sempre registrados no formato de hora UTC (Tempo Universal Coordenado), portanto, recomendamos que você se acostume a usar apenas a o formato de hora UTC.

ActivityDateTime : 4/25/2023 3:18:30 PM
Activity         : ViewReport
UserId           : jordan@contoso.com
ArtifactName     : Gross Margin Analysis
WorkSpaceName    : Sales Analytics

CreationTime     : 4/25/2023 5:32:10 PM
Activity         : ShareReport
UserId           : ellis@contoso.com
ArtifactName     : Call Center Stats
WorkSpaceName    : Sales Analytics

CreationTime     : 4/25/2023 9:03:05 PM
Activity         : ViewReport
UserId           : morgan@contoso.com
ArtifactName     : Call Center Stats
WorkSpaceName    : Sales Analytics

Dica

Você pode usar essa técnica para filtrar os resultados por qualquer propriedade nos resultados. Por exemplo, você pode usar um evento específico RequestId para analisar apenas um evento específico.

Exemplo 6: Exportar todas as atividades dos últimos N dias

Às vezes, talvez você queira exportar todos os dados de atividade para um arquivo para poder trabalhar com os dados fora do PowerShell. Este exemplo recupera todas as atividades para todos os usuários por até 30 dias. Ele exporta os dados para um arquivo JSON por dia.

Importante

Os dados do log de atividades estão disponíveis por no máximo 30 dias. É importante exportar e reter os dados para que você possa fazer uma análise histórica. Se você não exportar e armazenar os dados do log de atividades no momento, recomendamos que você priorize isso.

Solicitação de exemplo 6

O script recupera todas as atividades de uma série de dias. Ele declara três variáveis:

  • $NbrDaysDaysToExtract: quantos dias você está interessado em exportar. Ele executa um loop, trabalhando para trás em relação ao dia anterior. O valor máximo permitido é de 30 dias (porque a data mais antiga que você pode recuperar é 30 dias antes do dia atual).
  • $ExportFileLocation: o caminho da pasta em que você deseja salvar os arquivos. A pasta deve existir antes de executar o script. Não inclua um caractere de barra invertida (\) no final do caminho da pasta (porque ele é adicionado automaticamente no runtime). Recomendamos que você use uma pasta separada para armazenar arquivos de dados brutos.
  • $ExportFileName: o prefixo para cada nome de arquivo. Como um arquivo por dia é salvo, o script adiciona um sufixo para indicar os dados contidos no arquivo e a data e hora em que os dados foram recuperados. Por exemplo, se você executou um script às 9h (UTC) em 25 de abril de 2023 para extrair dados de atividade para 23 de abril de 2023, o nome do arquivo seria: PBIActivityEvents-20230423-202304250900. Embora a estrutura de pastas em que ela está armazenada seja útil, cada nome de arquivo deve ser totalmente autodescritivo.

Recomendamos que você extraia dados de pelo menos um dia antes do dia atual. Dessa forma, você evita a recuperação de eventos parciais do dia e pode ter certeza de que cada arquivo de exportação contém as 24 horas completas de dados.

O script coleta até 30 dias de dados até o dia anterior. Os carimbos de data/hora para eventos auditados estão sempre em UTC. Recomendamos que você crie todos os seus processos de auditoria com base no horário UTC em vez da hora local.

O script produz um arquivo JSON por dia. O sufixo do nome do arquivo inclui o carimbo de data/hora (no formato UTC) dos dados extraídos. Se você extrair o mesmo dia de dados mais de uma vez, o sufixo no nome do arquivo ajudará você a identificar o arquivo mais recente.

#Input values before running the script:
$NbrDaysDaysToExtract = 7
$ExportFileLocation = 'C:\Power-BI-Raw-Data\Activity-Log'
$ExportFileName = 'PBIActivityEvents'
#--------------------------------------------

#Start with yesterday for counting back to ensure full day results are obtained:
[datetime]$DayUTC = (([datetime]::Today.ToUniversalTime()).Date).AddDays(-1) 

#Suffix for file name so we know when it was written:
[string]$DateTimeFileWrittenUTCLabel = ([datetime]::Now.ToUniversalTime()).ToString("yyyyMMddHHmm")

#Loop through each of the days to be extracted (<Initilize> ; <Condition> ; <Repeat>)
For($LoopNbr=0 ; $LoopNbr -lt $NbrDaysDaysToExtract ; $LoopNbr++)
{
    [datetime]$DateToExtractUTC=$DayUTC.AddDays(-$LoopNbr).ToString("yyyy-MM-dd")

    [string]$DateToExtractLabel=$DateToExtractUTC.ToString("yyyy-MM-dd")
    
    #Create full file name:
    [string]$FullExportFileName = $ExportFileName `
    + '-' + ($DateToExtractLabel -replace '-', '') `
    + '-' + $DateTimeFileWrittenUTCLabel `
    + '.json' 

    #Obtain activity events and store intermediary results:
    [psobject]$Events=Get-PowerBIActivityEvent `
        -StartDateTime ($DateToExtractLabel+'T00:00:00.000') `
        -EndDateTime ($DateToExtractLabel+'T23:59:59.999')

    #Write one file per day:
    $Events | Out-File "$ExportFileLocation\$FullExportFileName"

    Write-Verbose "File written: $FullExportFileName" -Verbose 
}
Write-Verbose "Extract of Power BI activity events is complete." -Verbose

Há várias vantagens em usar o cmdlet Get-PowerBIActivityEvent do PowerShell em vez da operação da API REST Obter Eventos de Atividade.

  • O cmdlet permite que você solicite um dia de atividade sempre que fizer uma chamada usando o cmdlet. Já quando você se comunica diretamente com a API, só pode solicitar uma hora por solicitação de API.
  • O cmdlet gerencia tokens de continuação para você. Se você usar a API diretamente, precisará verificar o token de continuação para determinar se há mais resultados por vir. Algumas APIs precisam usar tokens de paginação e continuação por motivos de desempenho quando retornam uma grande quantidade de dados. Eles retornam o primeiro conjunto de registros e, em seguida, com um token de continuação, você pode fazer uma chamada à API subsequente para recuperar o próximo conjunto de registros. Você continuará chamando a API até que um token de continuação não seja retornado. Usar o token de continuação é uma maneira de consolidar várias solicitações de API para que você possa consolidar um conjunto lógico de resultados. Para obter um exemplo de como usar um token de continuação, confira API REST de Eventos de Atividade.
  • O cmdlet lida com as expirações do token de acesso do Microsoft Entra ID para você. Depois de autenticado, o token de acesso expira após uma hora (por padrão). Nesse caso, o cmdlet solicita automaticamente um token de atualização para você. Se você se comunicar diretamente com a API, precisará solicitar um token de atualização.

Para obter mais informações, confira Escolher APIs ou cmdlets do PowerShell.

Observação

Uma resposta de exemplo é omitida porque é uma saída semelhante às respostas mostradas nos exemplos anteriores.

Conteúdo relacionado

Para obter mais informações relacionadas a este artigo, confira os seguintes recursos: