Acceso al registro de actividad de Power BI

  • Artículo

Este artículo está destinado a los administradores de Power BI que necesitan acceder y analizar orígenes de datos del registro de actividad de Power BI. Se centra en la recuperación mediante programación de actividades de Power BI mediante el cmdlet Get-PowerBIActivityEvent del módulo de administración de Power BI. Hasta 30 días de historial disponibles. Este cmdlet usa la operación Obtener eventos de actividad de la API REST de Power BI, que es una API de administración. Los cmdlets de PowerShell agregan una capa de abstracción sobre las API subyacentes. Por lo tanto, el cmdlet de PowerShell simplifica el acceso al registro de actividad de Power BI.

Hay otras formas, tanto manuales como mediante programación, de recuperar actividades de Power BI. Para obtener más información, consulte Acceso a los datos de actividad del usuario.

El análisis del registro de actividad de Power BI es fundamental para la gobernanza, el cumplimiento y realizar un seguimiento de los esfuerzos de adopción . Para obtener más información sobre el registro de actividad de Power BI, consulte Seguimiento de actividades de usuario en Power BI.

Sugerencia

Le recomendamos que revise completamente el artículo Auditoría de nivel de inquilino . En este artículo se tratan las actividades de planeamiento, decisiones clave, requisitos previos y desarrollo de soluciones clave que se deben tener en cuenta al crear una solución de auditoría de un extremo a otro.

Ejemplos disponibles

El objetivo de este artículo es proporcionarle ejemplos para ayudarle a empezar. Los ejemplos incluyen scripts que recuperan datos del registro de actividad mediante el módulo PowerShell de administración de Power BI.

Advertencia

Los scripts no están listos para producción porque solo están diseñados para fines educativos. Sin embargo, puede adaptar los scripts con fines de producción mediante la adición de lógica para el registro, el control de errores, las alertas y la refactorización para la reutilización y la modularización del código.

Dado que están pensados para aprender, los ejemplos son simplistas, pero son reales. Le recomendamos que revise todos los ejemplos para comprender cómo aplican técnicas ligeramente diferentes. Una vez que identifique el tipo de datos de actividad que necesita, puede mezclar y hacer coincidir las técnicas para generar un script que se adapte mejor a sus requisitos.

En este artículo se incluyen los ejemplos siguientes.

Nombre del ejemplo Tipo de datos de actividad
Autenticación con el servicio Power BI N/A
Ver todas las actividades de un usuario durante un día All
Ver una actividad durante N días Compartir informe (vínculo o acceso directo)
Ver tres actividades durante N días Creación, actualización e instalación de una aplicación
Ver todas las actividades de un área de trabajo durante un día All
Exportar todas las actividades de los N días anteriores All

Para simplificar, la mayoría de los ejemplos generan el resultado en la pantalla. Por ejemplo, en Visual Studio Code, los datos se generan en el panel de terminal, que contiene un conjunto de datos en memoria de búfer.

La mayoría de los ejemplos recuperan datos JSON sin procesar. Trabajar con los datos JSON sin procesar tiene muchas ventajas.

  • Se devuelve toda la información disponible para cada evento de actividad. Esto resulta útil para aprender qué datos están disponibles. Tenga en cuenta que el contenido de una respuesta de API difiere en función del evento de actividad real. Por ejemplo, los datos disponibles para un evento CreateApp son diferentes al evento ViewReport .
  • Dado que los datos que están disponibles en el registro de actividad cambian a medida que Power BI evoluciona con el tiempo, también puede esperar que las respuestas de la API cambien. De este modo, no se perderán los nuevos datos introducidos. El proceso también es más resistente al cambio y menos probable que se produzca un error.
  • Los detalles de una respuesta de API pueden diferir para la nube comercial de Power BI y las nubes nacionales o regionales.
  • Si tiene diferentes miembros del equipo (como ingenieros de datos) que participan en este proceso, simplificar el proceso inicial para extraer los datos facilita que varios equipos trabajen juntos.

Sugerencia

Le recomendamos que mantenga los scripts que extraigan los datos lo más sencillos posible. Por lo tanto, evite analizar, filtrar o dar formato a los datos del registro de actividad a medida que se extraiga. Este enfoque usa una metodología ELT, que tiene pasos independientes para extraer, cargar y transformar datos. Este artículo solo se centra en el primer paso, que se refiere a la extracción de los datos.

Requisitos

Para usar los scripts de ejemplo, debe cumplir los siguientes requisitos.

  • Herramienta cliente de PowerShell: Use la herramienta preferida para ejecutar comandos de PowerShell. Todos los ejemplos se probaron mediante la extensión de PowerShell para Visual Studio Code con PowerShell 7. Para obtener información sobre las herramientas de cliente y las versiones de PowerShell, consulte Auditoría de nivel de inquilino.
  • Módulo de administración de Power BI: Instale todos los módulos de PowerShell de Power BI. Si los instaló anteriormente, se recomienda actualizar los módulos para asegurarse de que usa la versión publicada más reciente.
  • Rol Administrador de tejido: Los scripts de ejemplo se han diseñado para usar un flujo de autenticación interactivo. Por lo tanto, el usuario que ejecuta los scripts de ejemplo de PowerShell debe iniciar sesión para usar las API de REST de Power BI. Para recuperar los datos del registro de actividad, el usuario autenticado debe pertenecer al rol de administrador de Power BI (porque la recuperación de eventos de actividad se realiza con una API de administración). La autenticación de entidad de servicio está fuera del ámbito de estos ejemplos de aprendizaje.

En el resto de este artículo se incluyen scripts de ejemplo que muestran diferentes formas de recuperar los datos del registro de actividad.

Ejemplo 1: Autenticación con el servicio Power BI

Todas las operaciones de la API REST de Power BI requieren que inicie sesión. La autenticación (quién realiza la solicitud) y la autorización (lo que el usuario tiene permiso para hacer) se administran mediante la Plataforma de identidad de Microsoft. En el ejemplo siguiente se usa el cmdlet Connect-PowerBIServiceAccount del módulo de administración de Power BI. Este cmdlet admite un método sencillo para iniciar sesión.

Solicitud de ejemplo 1

El primer script le redirige a un explorador para completar el proceso de inicio de sesión. Las cuentas de usuario que tienen habilitada la autenticación multifactor (MFA) pueden usar este flujo de autenticación interactiva para iniciar sesión.

Connect-PowerBIServiceAccount

Importante

Los usuarios sin privilegios de administrador de Power BI no pueden ejecutar ninguno de los scripts de ejemplo siguientes en este artículo. Los administradores de Power BI tienen permiso para administrar el servicio Power BI y recuperar metadatos de todo el inquilino (como los datos del registro de actividad). Aunque el uso de la autenticación de entidad de servicio está fuera del ámbito de estos ejemplos, se recomienda encarecidamente configurar una entidad de servicio para scripts desatendidos listos para producción que se ejecutarán según una programación.

Asegúrese de iniciar sesión antes de ejecutar cualquiera de los siguientes scripts.

Ejemplo 2: Ver todas las actividades de un usuario durante un día

A veces es necesario comprobar todas las actividades que ha realizado un usuario específico en un día específico.

Sugerencia

Al extraer datos del registro de actividad mediante el cmdlet de PowerShell, cada solicitud puede extraer datos durante un día (un máximo de 24 horas). Por lo tanto, el objetivo de este ejemplo es empezar simplemente comprobando un usuario durante un día. Hay otros ejemplos más adelante en este artículo que muestran cómo usar un bucle para exportar datos durante varios días.

Solicitud de ejemplo 2

Este script declara dos variables de PowerShell para facilitar la reutilización del script:

  • $UserEmailAddr: la dirección de correo electrónico del usuario que le interesa.
  • $ActivityDate: la fecha en la que está interesado. El formato es AAAA-MM-DD (formato ISO 8601). No se puede solicitar una fecha anterior a 30 días antes de la fecha actual.
#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

Es posible que observe un carácter de verso (') al final de algunas de las líneas de los scripts de PowerShell. En PowerShell, una manera de usar el carácter de verso es como un carácter de continuación de línea. Lo hemos usado para mejorar la legibilidad de los scripts de este artículo.

Sugerencia

En el script, cada una de las variables de PowerShell se correlaciona con un valor de parámetro obligatorio o opcional en el cmdlet Get-PowerBIActivityEvent . Por ejemplo, el valor que se asigna a la variable $UserEmailAddr se pasa al parámetro -User. Declarar variables de PowerShell de esta manera es un enfoque ligero para evitar valores de codificación rígida que podrían cambiar en el script. Ese es un buen hábito de adoptar y será útil a medida que los scripts se vuelven más complejos. Los parámetros de PowerShell son más sólidos que las variables, pero están fuera del ámbito de este artículo.

Respuesta de ejemplo 2

Aquí se muestra una respuesta JSON de ejemplo. Incluye dos actividades que realizó el usuario:

  • La primera actividad muestra que un usuario ha visto un informe.
  • La segunda actividad muestra que un administrador exportó datos del registro de actividad de 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"
  }
]

Sugerencia

Extraer los datos del registro de actividad de Power BI también es una operación registrada, como se muestra en la respuesta anterior. Al analizar las actividades del usuario, es posible que quiera omitir las actividades de administrador, o analizarlas por separado.

Ejemplo 3: Ver una actividad durante N días

A veces, es posible que desee investigar un tipo específico de actividad durante una serie de días. En este ejemplo se muestra cómo recuperar actividades de uso compartido de informes por elemento . Usa un bucle para recuperar actividades de los siete días anteriores.

Solicitud de ejemplo 3

El script declara dos variables:

  • $ActivityType: nombre de la operación de la actividad que está investigando.
  • $NbrOfDaysToCheck: cuántos días le interesa comprobar. Realiza un bucle trabajando hacia atrás desde el día actual. El valor máximo permitido es 30 días (porque la fecha más antigua que se puede recuperar es de 30 días antes del día actual).
#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 
}

Sugerencia

Puede usar esta técnica de bucle para comprobar cualquiera de las operaciones registradas en el registro de actividad.

Respuesta de ejemplo 3

Aquí se muestra una respuesta JSON de ejemplo. Incluye dos actividades que realizó el usuario:

  • La primera actividad muestra que se creó un vínculo para compartir para un usuario. Tenga en cuenta que el valor SharingAction difiere en función de si el usuario creó un vínculo, editó un vínculo o eliminó un vínculo. Por motivos de brevedad, solo se muestra un tipo de actividad de vínculo de uso compartido en la respuesta.
  • La segunda actividad muestra que se creó el uso compartido de acceso directo para un grupo. Tenga en cuenta que el valor SharingInformation difiere en función de la acción realizada. Por motivos de brevedad, solo se muestra un tipo de actividad de acceso directo de uso compartido en la respuesta.
[
  {
    "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

Esta respuesta JSON muestra que la estructura de datos es diferente en función del tipo de evento. Incluso el mismo tipo de evento puede tener características diferentes que producen una salida ligeramente diferente. Como se recomienda anteriormente en este artículo, debería acostumbrarse a recuperar los datos sin procesar.

Ejemplo 4: Ver tres actividades durante N días

A veces, es posible que quiera investigar varias actividades relacionadas. En este ejemplo se muestra cómo recuperar tres actividades específicas para los siete días anteriores. Se centra en las actividades relacionadas con las aplicaciones de Power BI, incluida la creación de una aplicación, la actualización de una aplicación y la instalación de una aplicación.

Solicitud de ejemplo 4

El script declara las siguientes variables:

  • $NbrOfDaysToCheck: cuántos días le interesa comprobar. Realiza un bucle que trabaje hacia atrás desde el día actual. El valor máximo permitido es 30 días (porque la fecha más antigua que se puede recuperar es de 30 días antes del día actual).
  • $Activity1: nombre de la operación de la primera actividad que está investigando. En este ejemplo, se buscan actividades de creación de aplicaciones de Power BI.
  • $Activity2: el nombre de la segunda operación. En este ejemplo, se buscan actividades de actualización de aplicaciones de Power BI.
  • $Activity3: el nombre de la tercera operación. En este ejemplo, se buscan actividades de instalación de aplicaciones de Power BI.

Solo puede recuperar eventos de actividad para una actividad a la vez. Por lo tanto, el script busca cada operación por separado. Combina los resultados de búsqueda en una variable denominada $FullResults, que luego genera en la pantalla.

Precaución

La ejecución de muchos bucles muchas veces aumenta considerablemente la probabilidad de limitación de API. La limitación puede producirse cuando se supera el número de solicitudes que puede realizar en un período de tiempo determinado. La operación Obtener eventos de actividad está limitada a 200 solicitudes por hora. Al diseñar los scripts, tenga cuidado de no recuperar los datos originales más veces de lo que necesita. Por lo general, es recomendable extraer todos los datos sin procesar una vez al día y, a continuación, consultar, transformar, filtrar o dar formato a esos datos por separado.

El script muestra los resultados del día actual.

Nota

Para recuperar resultados solo para el día anterior (evitar resultados parciales del día), consulte el ejemplo Exportar todas las actividades de los N días 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

Respuesta de ejemplo 4

Aquí se muestra una respuesta JSON de ejemplo. Incluye tres actividades que realizó el usuario:

  • La primera actividad muestra que se creó una aplicación de Power BI.
  • La segunda actividad muestra que se actualizó una aplicación de Power BI.
  • La tercera actividad muestra que un usuario instaló una aplicación de Power BI.

Advertencia

La respuesta solo incluye los permisos de usuario que se modificaron. Por ejemplo, es posible que se hayan creado tres audiencias en un evento CreateApp. En el evento UpdateApp, si solo ha cambiado una audiencia, solo aparecerá una audiencia en los datos de OrgAppPermission. Por ese motivo, confiar en el evento UpdateApp para realizar el seguimiento de todos los permisos de la aplicación está incompleto porque el registro de actividad solo muestra lo que ha cambiado.

Para obtener una instantánea de todos los permisos de aplicación de Power BI, use la operación Obtener usuarios de la aplicación como Administración de API en su lugar.

[
  {
    "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"
  }
]

Ejemplo 5: Ver todas las actividades de un área de trabajo durante un día

A veces, es posible que quiera investigar actividades relacionadas con un área de trabajo específica. En este ejemplo se recuperan todas las actividades de todos los usuarios durante un día. A continuación, filtra los resultados para que pueda centrarse en el análisis de actividades de un área de trabajo.

Solicitud de ejemplo 5

El script declara dos variables:

  • $ActivityDate: la fecha en la que está interesado. El formato es AAAA-MM-DD. No se puede solicitar una fecha anterior a 30 días antes de la fecha actual.
  • $WorkspaceName: el nombre del área de trabajo que le interesa.

Almacena los resultados en la variable $Results. A continuación, convierte los datos JSON en un objeto para que se puedan analizar los resultados. A continuación, filtra los resultados para recuperar cinco columnas específicas. Se cambia el nombre de los datos CreationTime como ActivityDateTime. Los resultados se filtran por el nombre del área de trabajo y, a continuación, se envían a la pantalla.

No hay ningún parámetro para el cmdlet Get-PowerBIActivityEvent que le permite especificar un área de trabajo al comprobar el registro de actividad (en los ejemplos anteriores de este artículo se usaban parámetros de PowerShell para establecer un nombre de usuario, fecha o actividad específico). En este ejemplo, el script recupera todos los datos y, a continuación, analiza la respuesta JSON para filtrar los resultados de un área de trabajo específica.

Precaución

Si se encuentra en una organización grande que tiene cientos o miles de actividades al día, el filtrado de los resultados después de que se hayan recuperado puede ser muy ineficaz. Tenga en cuenta que la operación Obtener eventos de actividad está limitada a 200 solicitudes por hora.

Para evitar la limitación de API (cuando se supera el número de solicitudes que se le permite realizar en un período de tiempo determinado), no recupere los datos originales más de lo que necesita. Puede seguir trabajando con los resultados filtrados sin ejecutar el script para recuperar los resultados de nuevo. En el caso de las necesidades continuas, se recomienda extraer todos los datos una vez al día y, a continuación, consultarlos muchas veces.

#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

Respuesta de ejemplo 5

Estos son los resultados filtrados, que incluyen un pequeño subconjunto de propiedades. El formato es más fácil de leer para análisis ocasionales. Sin embargo, se recomienda volver a convertirla en formato JSON si tiene previsto almacenar los resultados.

Nota

Después de convertir los resultados JSON en un objeto de PowerShell, los valores de hora se convierten en hora local. Los datos de auditoría originales siempre se registran en hora universal coordinada (UTC), por lo que se recomienda que esté acostumbrado a usar solo la 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

Sugerencia

Puede usar esta técnica para filtrar los resultados por cualquier propiedad de los resultados. Por ejemplo, puede usar un evento RequestId específico para analizar solo un evento específico.

Ejemplo 6: Exportar todas las actividades de los N días anteriores

A veces, es posible que desee exportar todos los datos de actividad a un archivo para que pueda trabajar con los datos fuera de PowerShell. En este ejemplo se recuperan todas las actividades de todos los usuarios durante 30 días. Exporta los datos a un archivo JSON al día.

Importante

Los datos del registro de actividad están disponibles durante un máximo de 30 días. Es importante que exporte y conserve los datos para poder realizar análisis históricos. Si actualmente no exporta y almacena los datos del registro de actividad, se recomienda encarecidamente priorizarlo.

Solicitud de ejemplo 6

El script recupera todas las actividades de una serie de días. Declara tres variables:

  • $NbrDaysDaysToExtract: cuántos días le interesa exportar. Realiza un bucle trabajando hacia atrás desde el día anterior. El valor máximo permitido es 30 días (porque la fecha más antigua que se puede recuperar es de 30 días antes del día actual).
  • $ExportFileLocation: ruta de acceso de carpeta donde desea guardar los archivos. La carpeta debe existir antes de ejecutar el script. No incluya un carácter de barra diagonal inversa (\) al final de la ruta de acceso de la carpeta (porque se agrega automáticamente en tiempo de ejecución). Se recomienda usar una carpeta independiente para almacenar archivos de datos sin procesar.
  • $ExportFileName: el prefijo de cada nombre de archivo. Dado que se guarda un archivo al día, el script agrega un sufijo para indicar los datos contenidos en el archivo y la fecha y hora en que se recuperaron los datos. Por ejemplo, si ejecutó un script a las 9:00 (UTC) el 25 de abril de 2023 para extraer datos de actividad para el 23 de abril de 2023, el nombre de archivo sería: PBIActivityEvents-20230423-202304250900. Aunque la estructura de carpetas en la que se almacena es útil, cada nombre de archivo debe ser totalmente autodescriptivo.

Se recomienda extraer datos que son al menos un día antes del día actual. De este modo, evita recuperar eventos de día parciales y puede estar seguro de que cada archivo de exportación contiene las 24 horas completas de datos.

El script recopila hasta 30 días de datos hasta el día anterior. Las marcas de tiempo de los eventos auditados siempre están en UTC. Le recomendamos que compile todos los procesos de auditoría en función de la hora UTC en lugar de la hora local.

El script genera un archivo JSON al día. El sufijo del nombre de archivo incluye la marca de tiempo (en formato UTC) de los datos extraídos. Si extrae el mismo día de datos más de una vez, el sufijo en el nombre de archivo le ayuda a identificar el archivo más reciente.

#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

Hay varias ventajas para usar el cmdlet Get-PowerBIActivityEvent de PowerShell en lugar de la operación Obtener eventos de actividad de API de REST.

  • El cmdlet permite solicitar un día de actividad cada vez que realice una llamada mediante el cmdlet. Mientras que cuando se comunica directamente con la API, solo puede solicitar una hora por solicitud de API.
  • El cmdlet le gestiona los tokens de continuación. Si usa la API directamente, debe comprobar el token de continuación para determinar si hay más resultados. Algunas API deben usar tokens de paginación y continuación por motivos de rendimiento cuando devuelven una gran cantidad de datos. Devuelven el primer conjunto de registros y, a continuación, con un token de continuación, puede realizar una llamada API posterior para recuperar el siguiente conjunto de registros. Seguirá llamando a la API hasta que no se devuelva un token de continuación. El uso del token de continuación es una manera de consolidar varias solicitudes de API para que pueda consolidar un conjunto lógico de resultados. Para obtener un ejemplo del uso de un token de continuación, consulte la REST API de eventos de actividad.
  • El cmdlet controla las expiraciones del token de acceso de Microsoft Entra ID (anteriormente conocido como Azure Active Directory). Después de autenticarse, el token de acceso expira después de una hora (de forma predeterminada). En este caso, el cmdlet solicita automáticamente un token de actualización. Si se comunica directamente con la API, debe solicitar un token de actualización.

Para obtener más información, consulte Elegir API o cmdlets de PowerShell.

Nota

Se omite una respuesta de ejemplo porque es una salida similar a las respuestas que se muestran en los ejemplos anteriores.

Contenido relacionado

Para obtener más información sobre este artículo, consulte los recursos siguientes: