Partilhar via

Aceder ao registo de atividades do Power BI

  • Artigo

Este artigo destina-se a administradores do Power BI que precisam acessar e analisar dados provenientes do log de atividades do Power BI. Ele se concentra na recuperação programática de atividades do Power BI usando o cmdlet Get-PowerBIActivityEvent do módulo Gerenciamento do Power BI. Até 30 dias de história estão disponíveis. Este cmdlet usa a operação Get Activity Events Power BI REST API, que é uma API de administração. 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, consulte os dados de atividade do usuário do Access.

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

Gorjeta

Recomendamos que você revise completamente 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ções a serem consideradas ao criar uma solução de auditoria de ponta a ponta.

Exemplos disponíveis

O objetivo deste artigo é fornecer exemplos para ajudá-lo 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 roteiros 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, tratamento de erros, alertas e refatoração para reutilização e modularização de código.

Por serem destinados à aprendizagem, os exemplos são simplistas, mas são do mundo real. Recomendamos que você revise todos os exemplos para entender como eles aplicam técnicas ligeiramente diferentes. Depois de identificar o tipo de dados de atividade de que precisa, você pode misturar e combinar as técnicas para produzir um script que melhor atenda às suas necessidades.

Este artigo inclui os seguintes exemplos.

Nome de exemplo Tipo de dados de atividade
Autenticar com o serviço do Power BI N/A
Ver todas as atividades de um utilizador durante um dia Todos
Ver uma atividade durante N dias Compartilhar relatório (link ou acesso direto)
Veja três atividades para N dias Criar aplicativo, atualizar aplicativo e instalar aplicativo
Ver todas as atividades de um espaço de trabalho por um dia Todos
Exportar todas as atividades dos N dias anteriores Todos

Para simplificar, a maioria dos exemplos envia seu resultado para a tela. Por exemplo, no Visual Studio Code, os dados são enviados para o painel do terminal, que contém um conjunto de buffer 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. Lembre-se de que o conteúdo de uma resposta de API difere 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ê pode esperar que as respostas da API também mudem. Dessa forma, novos dados introduzidos não serão perdidos. Seu processo também é mais resiliente à mudança e menos propenso a falhar.
  • Os detalhes de uma resposta de API podem diferir para a nuvem comercial do Power BI e 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 torna mais fácil para várias equipes trabalharem juntas.

Gorjeta

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 à medida que 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 PowerShell 7. Para obter informações sobre ferramentas de cliente e versões do PowerShell, consulte Auditoria em nível de 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 atualize os módulos para garantir que está usando a versão publicada mais recente.
  • Função de administrador de malha: 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. Este cmdlet oferece suporte a um método simples para entrar.

Pedido de amostra 1

O primeiro script redireciona você para um navegador para concluir o processo de login. As contas de usuário que têm a autenticação multifator (MFA) habilitada podem usar esse fluxo de autenticação interativo 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 de 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 desses 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 uma agenda.

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

Exemplo 2: Ver todas as atividades de um utilizador durante um dia

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

Gorjeta

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 mais adiante neste artigo que mostram como usar um loop para exportar dados por vários dias.

Pedido de amostra 2

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

  • $UserEmailAddr: O endereço de e-mail do usuário em que você está interessado.
  • $ActivityDate: A data em que está interessado. O formato é AAAA-MM-DD (formato ISO 8601). Não é possível 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

Nota

Você pode notar um caractere de backtick (') no final de algumas das linhas nos scripts do PowerShell. No PowerShell, uma maneira de usar o caractere backtick é como um caractere de continuação de linha. Usámo-lo para melhorar a legibilidade dos scripts neste artigo.

Gorjeta

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 atribuído à $UserEmailAddr variável é passado para o -User parâmetro. Declarar variáveis do PowerShell dessa maneira é uma abordagem leve para evitar valores de codificação 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 da amostra 2

Aqui está um exemplo de resposta JSON. Ele inclui duas atividades que o usuário realizou:

  • 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"
  }
]

Gorjeta

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 as atividades do administrador ou analisá-las separadamente.

Exemplo 3: Ver uma atividade durante N dias

Às vezes, você pode querer 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.

Pedido de amostra 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 
}

Gorjeta

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

Resposta da amostra 3

Aqui está um exemplo de resposta JSON. Ele inclui duas atividades que o usuário realizou:

  • 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 maior brevidade, 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. Por uma questão de brevidade, 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"
  }
]

Nota

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. Como recomendado anteriormente neste artigo, você deve se acostumar a recuperar os dados brutos.

Exemplo 4: Ver três atividades durante N dias

Às vezes, você pode querer 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 aos aplicativos do Power BI, incluindo a criação de um aplicativo, a atualização de um aplicativo e a instalação de um aplicativo.

Pedido de amostra 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 por atividades de criação de aplicativos do Power BI.
  • $Activity2: O segundo nome da operação. Neste exemplo, ele está procurando por atividades de atualização do aplicativo Power BI.
  • $Activity3: O nome da terceira operação. Neste exemplo, ele está procurando por atividades de instalação do aplicativo Power BI.

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

Atenção

A execução de 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 pode fazer em um determinado período de tempo. A operação Get Activity Events está limitada a 200 solicitações por hora. Ao criar seus scripts, tome cuidado para não recuperar os dados originais mais vezes do que o necessário. 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 para o dia atual.

Nota

Para recuperar resultados apenas do dia anterior, evitando resultados parciais do dia, consulte o exemplo Exportar todas as atividades para 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 da amostra 4

Aqui está um exemplo de resposta JSON. Inclui três atividades que o usuário realizou:

  • 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 tenham 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 rastrear todas as permissões do aplicativo está incompleto porque o registro de atividades mostra apenas o que foi alterado.

Para obter um instantâneo de todas as permissões do aplicativo Power BI, use a operação Obter Usuários do Aplicativo como API de 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 espaço de trabalho por um dia

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

Pedido de amostra 5

O script declara duas variáveis:

  • $ActivityDate: A data em que está interessado. O formato é AAAA-MM-DD. Não é possível solicitar uma data anterior a 30 dias antes da data atual.
  • $WorkspaceName: O nome do espaço de trabalho em que está interessado.

O script armazena $Results os resultados na variável. Em seguida, ele converte os dados JSON em um objeto para que os resultados possam ser analisados. Em seguida, 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 espaço de trabalho e, em seguida, enviados para a tela.

Não há um parâmetro para o cmdlet Get-PowerBIActivityEvent que permita especificar um espaço de trabalho 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, em seguida, analisa a resposta JSON para filtrar os resultados de um espaço de trabalho específico.

Atenção

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 pode 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 pode fazer em um determinado período de tempo), não recupere os dados originais mais do que o necessário. 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 melhor extrair todos os dados uma vez por dia e, em seguida, 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 da amostra 5

Aqui estão os resultados filtrados, que incluem um pequeno subconjunto de propriedades. O formato é mais fácil de ler para análises ocasionais. No entanto, recomendamos que você o converta novamente para o formato JSON se planeja armazenar os resultados.

Nota

Depois de converter os resultados JSON em um objeto do PowerShell, os valores de tempo são convertidos em hora local. Os dados de auditoria originais são sempre registados na hora UTC (Tempo Universal Coordenado), pelo que recomendamos que se habitue a utilizar apenas a 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

Gorjeta

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

Exemplo 6: Exportar todas as atividades dos N dias anteriores

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

Importante

Os dados do registo de atividades estão disponíveis por um período máximo de 30 dias. É importante que você exporte e retenha os dados para que possa fazer a análise histórica. Se você não exporta e armazena atualmente os dados do registro de atividades, é altamente recomendável priorizar isso.

Pedido de amostra 6

O script recupera todas as atividades por uma série de dias. 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 onde 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 tempo de execução). 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) de 25 de abril de 2023 para extrair dados de atividade de 23 de abril de 2023, o nome do arquivo seria: PBIActivityEvents-20230423-202304250900. Embora a estrutura de pastas onde está armazenado seja útil, cada nome de arquivo deve ser totalmente autodescrito.

Recomendamos que extraia dados pelo menos um dia antes do dia atual. Dessa forma, você evita recuperar 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 reúne até 30 dias de dados, até o dia anterior. Os carimbos de data/hora para eventos auditados estão sempre em UTC. Recomendamos que crie todos os seus processos de auditoria com base na hora UTC e não na 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 ajuda 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 PowerShell em vez da operação Get Activity Events REST API.

  • O cmdlet permite que você solicite um dia de atividade cada vez que fizer uma chamada usando o cmdlet. Considerando que, quando você se comunica diretamente com a API, só pode solicitar uma hora por solicitação de API.
  • O cmdlet lida com 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, com um token de continuação, você pode fazer uma chamada de API subsequente para recuperar o próximo conjunto de registros. Você continua 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 uso de um token de continuação, consulte API REST de eventos de atividade.
  • O cmdlet lida com expirações de 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, consulte Escolher APIs ou cmdlets do PowerShell.

Nota

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

Conteúdos relacionados

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