Partager via

Accéder au journal d’activité de Power BI

  • Article

Cet article s’adresse aux administrateurs Power BI qui doivent accéder aux sources de données du journal d’activité de Power BI et les analyser. Il se concentre sur la récupération par programmation d’activités Power BI à l’aide du cmdlet Get-PowerBIActivityEvent à partir du module Gestion de Power BI. Il contient jusqu’à 30 jours d’historique. Ce cmdlet utilise l’opération d’API REST Power BI Get Activity Events, qui est une API d’administration. Les cmdlet PowerShell ajoutent une couche d’abstraction au-dessus des API sous-jacentes. Par conséquent, le cmdlet PowerShell simplifie l’accès au journal d’activité Power BI.

Il existe d’autres méthodes manuelles et programmatiques pour récupérer des activités Power BI. Pour plus d’informations, consultez Accéder aux données d’activité des utilisateurs.

L’analyse du journal d’activité Power BI est essentielle pour la gouvernance, la conformité et le suivi des efforts d’adoption. Pour plus d’informations sur le journal d’activité Power BI, consultez Suivre les activités des utilisateurs dans Power BI.

Conseil

Nous vous recommandons de consulter entièrement l’article Audit au niveau du locataire. Cet article traite de la planification, des décisions clés, des prérequis et des activités de développement de solutions clés à prendre en compte lors de la création d’une solution d’audit de bout en bout.

Exemples disponibles

L’objectif de cet article est de vous fournir des exemples pour vous aider à démarrer. Les exemples incluent des scripts qui récupèrent des données à partir du journal d’activité à l’aide du module PowerShell de gestion Power BI.

Avertissement

Les scripts ne sont pas prêts pour la production, car ils sont destinés uniquement à des fins éducatives. Toutefois, vous pouvez adapter les scripts à des fins de production en ajoutant une logique pour la journalisation, la gestion des erreurs, l’alerte et la refactorisation pour la réutilisation et la modularisation du code.

Comme ils sont destinés à l’apprentissage, les exemples sont simplistes, mais ils sont réels. Nous vous recommandons de passer en revue tous les exemples pour comprendre comment ils appliquent des techniques légèrement différentes. Une fois que vous avez identifié le type de données d’activité dont vous avez besoin, vous pouvez combiner et faire correspondre les techniques pour produire un script qui correspond le mieux à vos besoins.

Cet article inclut les exemples suivants.

Exemple de nom Type de données d’activité
S’authentifier auprès du service Power BI N/A
Afficher toutes les activités d’un utilisateur pendant une journée Tous
Afficher une activité pendant N jours Partager un rapport (lien ou accès direct)
Afficher trois activités pendant N jours Créer une application, mettre à jour une application et installer une application
Afficher toutes les activités d’un espace de travail pendant une journée Tous
Exporter toutes les activités des N jours précédents Tous

Par souci de simplicité, la plupart des exemples affichent leur résultat à l’écran. Par exemple, dans Visual Studio Code, les données sont sorties vers le panneau de terminal, qui contient un jeu de données tampon en mémoire.

La plupart des exemples récupèrent des données JSON brutes. L’utilisation des données JSON brutes présente de nombreux avantages.

  • Toutes les informations disponibles pour chaque événement d’activité sont retournées. Cela vous permet de savoir quelles données sont disponibles. N’oubliez pas que le contenu d’une réponse d’API diffère en fonction de l’événement d’activité réel. Par exemple, les données disponibles pour un événement CreateApp sont différentes de l’événement ViewReport.
  • Étant donné que les données disponibles dans le journal d’activité changent à mesure que Power BI évolue au fil du temps, vous pouvez vous attendre à ce que les réponses de l’API changent également. Ainsi, les nouvelles données introduites ne seront pas manquées. Votre processus est également plus résilient au changement et moins susceptible d’échouer.
  • Les détails d’une réponse d’API peuvent différer pour le cloud commercial Power BI et les clouds nationaux/régionaux.
  • Si vous avez différents membres de l’équipe (tels que les ingénieurs données) qui participent à ce processus, la simplification du processus initial pour extraire les données facilite la collaboration de plusieurs équipes.

Conseil

Nous vous recommandons de conserver vos scripts qui extraient des données aussi simples que possible. Par conséquent, évitez d’analyser, de filtrer ou de mettre en forme les données du journal d’activité au fur et à mesure qu’elles sont extraites. Cette approche utilise une méthodologie ELT (Extract, Load, Transform) qui comporte des étapes distinctes pour extraire, charger et transformer des données. Cet article se concentre uniquement sur la première étape, qui concerne l’extraction des données.

Configuration requise

Pour utiliser les scripts d’exemple, vous devez répondre aux exigences suivantes.

  • Outil client PowerShell : Utilisez votre outil préféré pour exécuter des commandes PowerShell. Tous les exemples ont été testés à l’aide de l’extension PowerShell pour Visual Studio Code avec PowerShell 7. Pour plus d’informations sur les outils clients et les versions de PowerShell, consultez Audit au niveau du locataire.
  • Module Gestion de Power BI : Installez tous les modules PowerShell Power BI. Si vous les avez déjà installés, nous vous recommandons de mettre à jour les modules pour vous assurer que vous utilisez la dernière version publiée.
  • Rôle administrateur Fabric : Les exemples de scripts sont conçus pour utiliser un flux d’authentification interactif. Par conséquent, l’utilisateur exécutant les exemples de scripts PowerShell doit se connecter pour utiliser les API REST Power BI. Pour récupérer les données du journal d’activité, l’utilisateur d’authentification doit appartenir au rôle administrateur Power BI (car la récupération des événements d’activité s’effectue avec une API d’administrateur). L’authentification du principal de service est hors de portée pour ces exemples d’apprentissage.

Le reste de cet article comprend des exemples de scripts qui vous montrent différentes façons de récupérer des données de journal d’activité.

Exemple 1 : S’authentifier auprès du service Power BI

Toutes les opérations d’API REST Power BI nécessitent une connexion. L’authentification (qui effectue la requête) et l’autorisation (ce que l’utilisateur a l’autorisation de faire) sont gérées par la plateforme d’identités Microsoft. L’exemple suivant utilise le cmdlet Connect-PowerBIServiceAccount à partir du module Gestion de Power BI. Ce cmdlet prend en charge une méthode simple de connexion.

Exemple de requête 1

Le premier script vous redirige vers un navigateur pour terminer le processus de connexion. Les comptes d’utilisateur pour lesquels l’authentification multifacteur (MFA) est activée peuvent utiliser ce flux d’authentification interactif pour se connecter.

Connect-PowerBIServiceAccount

Important

Les utilisateurs sans privilèges d’administrateur Power BI ne peuvent exécuter aucun des exemples de scripts qui sont présentés ci-après dans cet article. Les administrateurs Power BI sont autorisés à gérer le service Power BI et à récupérer les métadonnées à l’échelle du locataire (telles que les données du journal d’activité). Bien que l’utilisation de l’authentification du principal de service soit hors de portée pour ces exemples, nous vous recommandons vivement de configurer un principal de service pour les scripts sans assistance prêts pour la production qui s’exécuteront selon une planification.

Veillez à vous connecter avant d’exécuter l’un des scripts suivants.

Exemple 2 : Afficher toutes les activités d’un utilisateur pendant une journée

Parfois, vous devez vérifier toutes les activités qu’un utilisateur spécifique a effectuées un jour spécifique.

Conseil

Lors de l’extraction de données du journal d’activité à l’aide du cmdlet PowerShell, chaque requête peut extraire des données pendant un jour (un maximum de 24 heures). Par conséquent, l’objectif de cet exemple est de commencer simplement par vérifier un utilisateur pendant une journée. D’autres exemples plus loin dans cet article vous montrent comment utiliser une boucle pour exporter des données pendant plusieurs jours.

Exemple de requête 2

Ce script déclare deux variables PowerShell pour faciliter la réutilisation du script :

  • $UserEmailAddr : adresse e-mail de l’utilisateur qui vous intéresse.
  • $ActivityDate : date qui vous intéresse. Le format est AAAA-MM-JJ (format ISO 8601). Vous ne pouvez pas demander une date antérieure à 30 jours avant la date actuelle.
#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

Notes

Vous remarquerez peut-être un accent grave (`) à la fin de certaines lignes des scripts PowerShell. Dans PowerShell, vous pouvez utiliser l’accent grave comme caractère de continuation de ligne. Nous l’avons utilisé pour améliorer la lisibilité des scripts de cet article.

Conseil

Dans le script, chacune des variables PowerShell est corrélée à une valeur de paramètre obligatoire ou facultative dans le cmdlet Get-PowerBIActivityEvent. Par exemple, la valeur que vous affectez à la variable $UserEmailAddr est passée au paramètre -User. La déclaration de variables PowerShell de cette façon est une approche légère pour éviter le codage en dur des valeurs qui pourraient changer dans votre script. C’est une bonne habitude à adopter, et elle sera utile à mesure que vos scripts deviennent plus complexes. Les paramètres PowerShell sont plus robustes que les variables, mais ils ne sont pas concernés par cet article.

Exemple de réponse 2

Voici un exemple de réponse JSON. Il comprend deux activités effectuées par l’utilisateur :

  • La première activité montre qu’un utilisateur a consulté un rapport.
  • La deuxième activité montre qu’un administrateur a exporté des données à partir du journal d’activité 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"
  }
]

Conseil

L’extraction des données du journal d’activité Power BI est également une opération journalisée, comme indiqué dans la réponse précédente. Lorsque vous analysez les activités des utilisateurs, vous pouvez omettre les activités de l’administrateur ou les analyser séparément.

Exemple 3 : Afficher une activité pendant N jours

Dans certains cas, vous souhaiterez peut-être examiner un type d’activité spécifique pendant une série de jours. Cet exemple montre comment récupérer les activités de partage de rapport par élément. Il utilise une boucle pour récupérer les activités des sept jours précédents.

Exemple de requête 3

Le script déclare deux variables :

  • $ActivityType : nom de l’opération pour l’activité que vous examinez.
  • $NbrOfDaysToCheck : nombre de jours que vous souhaitez vérifier. Elle effectue une boucle qui fonctionne en arrière à partir du jour actuel. La valeur maximale autorisée est de 30 jours (car la date la plus ancienne que vous pouvez récupérer se situe 30 jours avant le jour actuel).
#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 
}

Conseil

Vous pouvez utiliser cette technique de boucle pour vérifier toutes les opérations enregistrées dans le journal d’activité.

Exemple de réponse 3

Voici un exemple de réponse JSON. Il comprend deux activités effectuées par l’utilisateur :

  • La première activité montre qu’un lien de partage a été créé pour un utilisateur. Notez que la valeur SharingAction diffère selon que l’utilisateur a créé, modifié ou supprimé un lien. Par souci de concision, un seul type d’activité concernant le lien de partage s’affiche dans la réponse.
  • La deuxième activité montre qu’un partage d’accès direct a été créé pour un groupe. Notez que la valeur SharingInformation diffère selon l’action effectuée. Par souci de concision, un seul type d’activité concernant le partage d’accès direct s’affiche dans la réponse.
[
  {
    "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"
  }
]

Notes

Cette réponse JSON montre que la structure des données est différente en fonction du type d’événement. Même le même type d’événement peut avoir des caractéristiques différentes qui produisent une sortie légèrement différente. Comme recommandé plus haut dans cet article, vous devez vous habituer à récupérer les données brutes.

Exemple 4 : Afficher trois activités pendant N jours

Dans certains cas, vous souhaiterez peut-être examiner plusieurs activités associées. Cet exemple montre comment récupérer trois activités spécifiques au cours des sept jours précédents. Il se concentre sur les activités liées aux applications Power BI, notamment la création, la mise à jour et l’installation d’une application.

Exemple de requête 4

Le script déclare les variables suivantes :

  • $NbrOfDaysToCheck : nombre de jours que vous souhaitez vérifier. Elle effectue une boucle qui fonctionne en arrière à partir du jour actuel. La valeur maximale autorisée est de 30 jours (car la date la plus ancienne que vous pouvez récupérer se situe 30 jours avant le jour actuel).
  • $Activity1 : nom de l’opération pour l’activité que vous examinez. Dans cet exemple, elle recherche des activités de création d’applications Power BI.
  • $Activity2 : nom de la deuxième opération. Dans cet exemple, elle recherche des activités de mise à jour d’applications Power BI.
  • $Activity3 : nom de la troisième opération. Dans cet exemple, elle recherche des activités d’installation d’applications Power BI.

Vous ne pouvez récupérer des événements d’activité que pour une seule activité à la fois. Par conséquent, le script recherche chaque opération séparément. Il combine les résultats de la recherche en une variable nommée $FullResults, qu’il affiche ensuite à l’écran.

Attention

L’exécution de nombreuses boucles plusieurs fois augmente considérablement la probabilité de limitation de requêtes de l’API. La limitation de requêtes peut se produire lorsque vous dépassez le nombre de requêtes que vous êtes autorisé à effectuer au cours d’une période donnée. L’opération Obtenir les événements d’activité est limitée à 200 requêtes par heure. Lorsque vous concevez vos scripts, veillez à ne pas récupérer les données d’origine plus de fois que nécessaire. En règle générale, il est préférable d’extraire toutes les données brutes une fois par jour, puis d’interroger, transformer, filtrer ou mettre en forme ces données séparément.

Le script affiche les résultats de la journée en cours.

Notes

Pour récupérer les résultats du jour précédent uniquement (en évitant les résultats partiels de la journée), consultez l’exemple Exporter toutes les activités des N jours précédents.)

#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

Exemple de réponse 4

Voici un exemple de réponse JSON. Il comprend trois activités effectuées par l’utilisateur :

  • La première activité montre qu’une application Power BI a été créée.
  • La deuxième activité montre qu’une application Power BI a été mise à jour.
  • La troisième activité montre qu’une application Power BI a été installée par un utilisateur.

Avertissement

La réponse inclut uniquement les autorisations utilisateur qui ont été modifiées. Par exemple, il est possible que trois audiences ont été créées dans un événement CreateApp. Dans l’événement UpdateApp, si une seule audience a changé, une seule audience apparaît dans les données OrgAppPermission. Pour cette raison, le fait de s’appuyer sur l’événement UpdateApp pour le suivi de toutes les autorisations d’application ne suffit pas, car le journal d’activité affiche uniquement ce qui a changé.

Pour obtenir une capture instantanée de toutes les autorisations d’application Power BI, utilisez plutôt l’opération d’API Obtenir les utilisateurs de l’application en tant qu’Administrateur.

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

Exemple 5 : Afficher toutes les activités d’un espace de travail pendant une journée

Dans certains cas, vous souhaiterez peut-être examiner les activités liées à un espace de travail spécifique. Cet exemple récupère toutes les activités de tous les utilisateurs pendant une journée. Il filtre ensuite les résultats afin que vous puissiez vous concentrer sur l’analyse des activités d’un espace de travail.

Exemple de requête 5

Le script déclare deux variables :

  • $ActivityDate : date qui vous intéresse. Le format est AAAA-MM-JJ. Vous ne pouvez pas demander une date antérieure à 30 jours avant la date actuelle.
  • $WorkspaceName : nom de l’espace de travail qui vous intéresse.

Ce script stocke les résultats dans la variable $Results. Il convertit ensuite les données JSON en objet afin que les résultats puissent être analysés. Puis, il filtre les résultats pour récupérer cinq colonnes spécifiques. Les données CreationTime sont renommées ActivityDateTime. Les résultats sont filtrés par le nom de l’espace de travail, puis affichés à l’écran.

Il n’existe aucun paramètre pour le cmdlet Get-PowerBIActivityEvent qui vous permet de spécifier un espace de travail lors de la vérification du journal d’activité (des exemples précédents de cet article utilisaient des paramètres PowerShell pour définir un utilisateur, une date ou un nom d’activité spécifique). Dans cet exemple, le script récupère toutes les données, puis analyse la réponse JSON pour filtrer les résultats d’un espace de travail spécifique.

Attention

Si vous êtes dans une grande organisation avec des centaines ou des milliers d’activités par jour, le filtrage des résultats une fois qu’ils ont été récupérés peut être très inefficace. Gardez à l’esprit que l’opération Obtenir les événements d’activité est limitée à 200 requêtes par heure.

Pour éviter la limitation des API (lorsque vous dépassez le nombre de requêtes que vous êtes autorisé à effectuer au cours d’une période donnée), ne récupérez pas les données d’origine plus que nécessaire. Vous pouvez continuer à travailler avec les résultats filtrés sans exécuter le script pour récupérer à nouveau les résultats. En cas de besoins continus, il est préférable d’extraire toutes les données une fois par jour, puis de les interroger plusieurs fois.

#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

Exemple de réponse 5

Voici les résultats filtrés, qui incluent un petit sous-ensemble de propriétés. Le format est plus facile à lire pour une analyse occasionnelle. Toutefois, nous vous recommandons de le convertir de nouveau au format JSON si vous envisagez de stocker les résultats.

Notes

Après avoir converti les résultats JSON en objet PowerShell, les valeurs d’heure sont converties en heure locale. Les données d’audit d’origine étant toujours enregistrées en heure UTC (Temps universel coordonné), nous vous recommandons de vous habituer à utiliser uniquement l’heure 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

Conseil

Vous pouvez utiliser cette technique pour filtrer les résultats par n’importe quelle propriété. Par exemple, vous pouvez utiliser un événement RequestId spécifique pour analyser seulement un événement spécifique.

Exemple 6 : Exporter toutes les activités des N jours précédents

Dans certains cas, vous souhaiterez peut-être exporter toutes les données d’activité dans un fichier afin de pouvoir utiliser les données en dehors de PowerShell. Cet exemple récupère toutes les activités de tous les utilisateurs pendant 30 jours. Il exporte les données dans un fichier JSON par jour.

Important

Les données du journal d’activité sont disponibles pendant un maximum de 30 jours. Il est important d’exporter et de conserver les données afin de pouvoir effectuer une analyse historique. Si vous n’exportez pas et ne stockez pas actuellement les données du journal d’activité, nous vous recommandons vivement de hiérarchiser cette opération.

Exemple de requête 6

Le script récupère toutes les activités pendant une série de jours. Il déclare trois variables :

  • $NbrDaysDaysToExtract : nombre de jours que vous souhaitez exporter. Elle effectue une boucle qui fonctionne en arrière à partir du jour actuel. La valeur maximale autorisée est de 30 jours (car la date la plus ancienne que vous pouvez récupérer se situe 30 jours avant le jour actuel).
  • $ExportFileLocation : chemin d’accès au dossier dans lequel vous souhaitez enregistrer les fichiers. Le dossier doit exister avant d’exécuter le script. N’incluez pas de caractère barre oblique inverse (\) à la fin du chemin du dossier (car il est automatiquement ajouté au moment de l’exécution). Nous vous recommandons d’utiliser un dossier distinct pour stocker des fichiers de données brutes.
  • $ExportFileName : préfixe de chaque nom de fichier. Étant donné qu’un fichier par jour est enregistré, le script ajoute un suffixe pour indiquer les données contenues dans le fichier, ainsi que la date et l’heure de récupération des données. Par exemple, si vous avez exécuté un script à 9 h (UTC) le 25 avril 2023 pour extraire des données d’activité pour le 23 avril 2023, le nom de fichier serait : PBIActivityEvents-20230423-202304250900. Bien que la structure de dossiers dans laquelle il est stocké soit utile, chaque nom de fichier doit être entièrement autodéscriptif.

Nous vous recommandons d’extraire des données au moins un jour avant le jour actuel. De cette façon, vous évitez de récupérer des événements d’une journée partielle et vous pouvez être sûr que chaque fichier d’exportation contient les 24 heures complètes de données.

Le script collecte jusqu’à 30 jours de données, jusqu’au jour précédent. Les horodatages pour les événements audités sont toujours en heure UTC. Nous vous recommandons de générer tous vos processus d’audit en fonction de l’heure UTC plutôt que de votre heure locale.

Le script produit un fichier JSON par jour. Le suffixe du nom de fichier inclut l’horodatage (au format UTC) des données extraites. Si vous extrayez plusieurs fois des données le même jour, le suffixe dans le nom de fichier vous aide à identifier le fichier le plus récent.

#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

Il existe plusieurs avantages à utiliser le cmdlet PowerShell Get-PowerBIActivityEvent plutôt que l’opération d’API REST Obtenir les événements d’activité.

  • Le cmdlet vous permet de demander un jour d’activité chaque fois que vous effectuez un appel à l’aide du cmdlet. Au contraire, lorsque vous communiquez directement avec l’API, vous ne pouvez demander qu’une heure par requête d’API.
  • Le cmdlet gère les jetons de continuation. Si vous utilisez l’API directement, vous devez vérifier le jeton de continuation pour déterminer s’il existe d’autres résultats à venir. Certaines API doivent utiliser des jetons de pagination et de continuation pour des raisons de performances lorsqu’elles retournent une grande quantité de données. Elles retournent le premier jeu d’enregistrements, puis avec un jeton de continuation, vous pouvez effectuer un appel d’API pour récupérer le jeu d’enregistrements suivant. Continuez à appeler l’API jusqu’à ce qu’aucun jeton de continuation ne soit retourné. L’utilisation du jeton de continuation est un moyen de consolider plusieurs requêtes d’API afin de pouvoir consolider un ensemble logique de résultats. Pour obtenir un exemple d’utilisation de jeton de continuation, consultez Evènements d’activité d’API REST.
  • L’applet de commande gère les expirations des jetons d’accès Microsoft Entra ID pour vous. Une fois que vous êtes authentifié, votre jeton d’accès expire au bout d’une heure (par défaut). Dans ce cas, le cmdlet demande automatiquement un jeton d’actualisation pour vous. Si vous communiquez directement avec l’API, vous devez demander un jeton d’actualisation.

Pour plus d’informations, consultez Choisir des API ou des applets de commande PowerShell.

Notes

Un exemple de réponse est omis, car il s’agit d’une sortie similaire aux réponses présentées dans les exemples précédents.

Contenu connexe

Pour plus d’informations en rapport avec cet article, consultez les ressources suivantes :