存取 Power BI 活動記錄

  • 發行項

本文以需要存取和分析Power BI活動記錄中數據源的Power BI系統管理員為目標。 其著重於使用 Power BI 管理模組中的 Get-PowerBIActivityEvent Cmdlet，以程式設計方式擷取 Power BI 活動。 最多30天的歷程記錄可供使用。 此 Cmdlet 會使用 取得活動事件 Power BI REST API 作業，這是系統管理員 API。 PowerShell Cmdlet 在基礎 API 之上新增一層抽象概念。 因此，PowerShell Cmdlet 可簡化對 Power BI 活動記錄的存取。

還有其他手動和程序設計方式可擷取 Power BI 活動。 如需詳細資訊，請參閱 存取用戶活動數據。

分析Power BI活動記錄對於治理、合規性及追蹤 採用 工作至關重要。 如需 Power BI 活動記錄的詳細資訊，請參閱 追蹤 Power BI 中的用戶活動。

提示

建議您完整檢閱 租用戶層級稽核 一文。 本文涵蓋在建置端對端稽核解決方案時要考慮的規劃、重要決策、必要條件和關鍵解決方案開發活動。

可用的範例

本文的目標是提供範例來協助您開始使用。 這些範例包括使用 Power BI 管理 PowerShell 模組從活動記錄擷取數據的腳本。

警告

腳本尚未準備好生產環境，因為它們僅供教育用途使用。 不過，您可以新增記錄、錯誤處理、警示，以及重構程式代碼重複使用和模組化的邏輯，來調整腳本以用於生產用途。

因為它們是為了學習，所以範例是簡單明瞭，但它們是真實世界。 建議您檢閱所有範例，以了解它們如何套用稍微不同的技術。 一旦您識別所需的活動數據類型，您可以混合並比對技術，以產生最符合您需求的腳本。

本文包含下列範例。

範例名稱 活動數據類型
使用 Power BI 服務 進行驗證 N/A
檢視使用者一天的所有活動 全部
檢視 N 天的活動 共用報表 （連結或直接存取）
檢視 N 天三個活動 建立應用程式、更新應用程式及安裝應用程式
檢視工作區的所有活動一天 全部
匯出前 N 天的所有活動 全部

為了簡單起見，大部分範例都會將其結果輸出到畫面。 例如，在Visual Studio Code 中，資料會輸出至 終端機面板，該面板會保存記憶體中的一組緩衝區數據。

大部分範例都會擷取原始 JSON 數據。 使用原始 JSON 數據有許多優點。

  • 會傳回每個活動事件可用的所有資訊。 這可協助您瞭解可用的數據。 請記住，API 回應的內容會根據實際活動事件而有所不同。 例如，CreateApp 事件可用的數據與 ViewReport 事件不同。
  • 由於活動記錄檔中可用的數據隨著 Power BI 隨時間變化而改變，因此您也可以預期 API 回應也會變更。 如此一來，引進的新數據就不會錯過。 您的程式也會更有彈性地變更，而且不太可能失敗。
  • Power BI 商業雲端和 國家/地區雲端的 API 回應詳細數據可能會有所不同。
  • 如果您有不同的小組成員（例如數據工程師）參與此程式，請簡化初始程式以擷取數據，讓多個小組更輕鬆地共同作業。

提示

我們建議您保留盡可能簡單擷取數據的腳本。 因此，請避免在擷取活動記錄數據時剖析、篩選或格式化活動記錄數據。 此方法使用 ELT 方法，其具有擷取、載入和轉換數據的不同步驟。 本文僅著重於擷取數據的第一個步驟。

需求

若要使用範例腳本，您必須符合下列需求。

  • PowerShell 用戶端工具： 使用您慣用的工具來執行 PowerShell 命令。 所有範例都是使用適用於 Visual Studio Code 的 PowerShell 延伸模組 搭配 PowerShell 7 進行測試。 如需用戶端工具和 PowerShell 版本的相關信息，請參閱 租用戶層級稽核。
  • Power BI 管理模組： 安裝所有 Power BI PowerShell 模組。 如果您先前已安裝這些模組，建議您更新模組，以確保您使用的是最新的已發佈版本。
  • 網狀架構系統管理員角色： 範例腳本是設計來使用互動式驗證流程。 因此，執行 PowerShell 範例腳本的用戶必須登入，才能使用 Power BI REST API。 若要擷取活動記錄數據，驗證用戶必須屬於Power BI系統管理員角色（因為擷取活動事件是使用系統管理 API 完成的）。 這些學習範例的服務主體驗證範圍不足。

本文的其餘部分包含範例腳本，示範擷取活動記錄數據的不同方式。

範例 1：使用 Power BI 服務 進行驗證

所有 Power BI REST API 作業都需要您登入。 驗證（提出要求的人員）和授權（用戶有權執行的動作）是由 Microsoft 身分識別平台 管理。 下列範例使用 Power BI 管理模組中的 連線-PowerBIServiceAccount Cmdlet。 此 Cmdlet 支援登入的簡單方法。

範例要求 1

第一個腳本會將您重新導向至瀏覽器，以完成登入程式。 已啟用多重要素驗證的用戶帳戶能夠使用此互動式驗證流程登入。

Connect-PowerBIServiceAccount

重要

沒有 Power BI 系統管理員許可權的使用者無法執行本文所遵循的任何範例腳本。 Power BI 系統管理員有權管理 Power BI 服務，以及擷取全租使用者的元數據（例如活動記錄數據）。 雖然使用這些範例的服務主體驗證範圍不足，但我們強烈建議您為生產就緒的自動腳本設定 服務主體 ，以依排程執行。

在執行下列任何腳本之前，請務必先登入。

範例 2：檢視使用者的所有活動一天

有時候，您需要檢查特定使用者在特定一天執行的所有活動。

提示

使用 PowerShell Cmdlet 從活動記錄擷取數據時，每個要求都可以擷取一天的數據（最多 24 小時）。 因此，此範例的目標是只要檢查一位使用者一天即可開始。 本文稍後有其他範例示範如何使用循環來導出數據多天。

範例要求 2

此文稿會宣告兩個 PowerShell 變數，以便更輕鬆地重複使用腳本：

  • $UserEmailAddr：您感興趣的使用者電子郵件位址。
  • $ActivityDate：您感興趣的日期。 格式為YYYY-MM-DD（ISO 8601 格式）。 您無法在目前日期之前的 30 天前要求日期。
#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

注意

您可能會注意到 PowerShell 腳本中某些行尾端有一個反引號字元。 在 PowerShell 中，您可以使用反引號字元的其中一種方式是做為行接續字元。 我們已使用它來改善本文中腳本的可讀性。

提示

在腳本中，每個 PowerShell 變數都會與 Get-PowerBIActivityEvent Cmdlet 中的必要或選擇性參數值相互關聯。 例如，您指派給 $UserEmailAddr 變數的值會傳遞至 -User 參數。 以這種方式宣告 PowerShell 變數是一種輕量型方法，可避免在腳本中變更的硬式編碼值。 這是採用的好習慣，當您的腳本變得更複雜時，這會很有用。 PowerShell 參數 比變數更強固，但超出本文的範圍。

範例回應 2

以下是範例 JSON 回應。 它包含使用者執行的兩個活動：

  • 第一個活動顯示使用者已檢視報表。
  • 第二個活動顯示系統管理員從 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"
  }
]

提示

擷取 Power BI 活動記錄數據也是記錄的作業，如先前的回應所示。 當您分析使用者活動時，您可能會想要省略系統管理員活動，或個別分析它們。

範例 3：檢視 N 天的活動

有時候，您可能會想要調查一系列特定類型的活動。 此範例示範如何擷取 個別專案報表共享 活動。 它會使用迴圈從前七天擷取活動。

範例要求 3

文稿會宣告兩個變數：

  • $ActivityType：您要調查之活動的作業名稱。
  • $NbrOfDaysToCheck：您有興趣檢查多少天。 它會從目前一天往後執行迴圈。 允許的最大值是 30 天（因為您可以擷取的最早日期是在目前日期前 30 天）。
#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 
}

提示

您可以使用這個循環技術來檢查活動記錄檔中記錄的任何 作業 。

範例回應 3

以下是範例 JSON 回應。 它包含使用者執行的兩個活動：

  • 第一個活動顯示已建立使用者的共享連結。 請注意， SharingAction 值會根據使用者建立連結、編輯連結或刪除連結而有所不同。 為了簡潔起見，回應中只會顯示一種類型的共享連結活動。
  • 第二個活動顯示已建立群組的直接存取共用。 請注意， SharingInformation 值會根據所採取的動作而有所不同。 為了簡潔起見，回應中只會顯示一種直接存取共享活動。
[
  {
    "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"
  }
]

注意

此 JSON 回應顯示數據結構會根據事件類型而有所不同。 即使是相同類型的事件，也可以有不同的特性來產生稍微不同的輸出。 如本文稍早所建議，您應該習慣擷取原始數據。

範例 4：檢視 N 天三個活動

有時候您可能會想要調查數個相關活動。 此範例示範如何擷取過去七天三個特定活動。 其著重於與 Power BI 應用程式 相關的活動，包括建立應用程式、更新應用程式，以及安裝應用程式。

範例要求 4

文稿會宣告下列變數：

  • $NbrOfDaysToCheck：您有興趣檢查多少天。 它會執行從目前一天回溯運作的迴圈。 允許的最大值是 30 天（因為您可以擷取的最早日期是在目前日期前 30 天）。
  • $Activity1：您要 調查之第一個活動的作業名稱 。 在此範例中，它會搜尋Power BI 應用程式建立活動。
  • $Activity2：第二個作業名稱。 在此範例中，它會搜尋Power BI 應用程式更新活動。
  • $Activity3：第三個作業名稱。 在此範例中，它會搜尋Power BI 應用程式安裝活動。

您一次只能擷取一個活動的活動事件。 因此，腳本會分別搜尋每個作業。 它會將搜尋結果合併成名為的 $FullResults變數，然後輸出至畫面。

警告

多次執行許多迴圈會大幅增加 API 節流的可能性。 當您超過在指定時段內允許提出的要求數目時，可能會發生節流。 取得活動事件作業限制為每小時 200 個要求。 當您設計文本時，請小心不要擷取原始數據超過您需要的次數。 一般而言，最好每天擷取一次原始數據，然後個別查詢、轉換、篩選或格式化該數據。

此文稿會顯示目前日期的結果。

注意

若要只擷取前一天的結果，請避免部分日期結果，請參閱 匯出前 N 天 的所有活動範例。

#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

範例回應 4

以下是範例 JSON 回應。 找不到使用者執行的三個活動：

  • 第一個活動顯示已建立Power BI 應用程式。
  • 第二個活動顯示Power BI 應用程式已更新。
  • 第三個活動會顯示使用者已安裝Power BI 應用程式。

警告

回應只包含已修改的用戶許可權。 例如，有可能在 CreateApp 事件中建立三個物件。 在 UpdateApp 事件中，如果只有一個物件變更，則只有一個物件會出現在 OrgAppPermission 數據中。 因此，依賴 UpdateApp 事件來追蹤所有應用程式許可權不完整，因為活動記錄只會顯示變更的內容。

如需所有 Power BI 應用程式許可權的快照集，請改用取得應用程式使用者作為 管理員 API 作業。

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

範例 5：檢視工作區的所有活動一天

有時候，您可能想要調查與特定工作區相關的活動。 本範例會擷取所有使用者一天的所有活動。 然後，它會篩選結果，讓您可以專注於分析一個 工作區的活動。

範例要求 5

文稿會宣告兩個變數：

  • $ActivityDate：您感興趣的日期。 格式為YYYY-MM-DD。 您無法在目前日期之前的 30 天前要求日期。
  • $WorkspaceName：您感興趣的工作區名稱。

腳本會將結果儲存在變數中 $Results 。 然後，它會將 JSON 資料轉換成 物件，以便剖析結果。 然後，它會篩選結果以擷取五個特定數據行。 CreationTime 數據會重新命名為 ActivityDateTime。 結果會依工作區名稱進行篩選，然後輸出至畫面。

Get-PowerBIActivityEvent Cmdlet 沒有參數，可讓您在檢查活動記錄時指定工作區（本文先前的範例使用 PowerShell 參數來設定特定使用者、日期或活動名稱）。 在此範例中，腳本會擷取所有數據，然後剖析 JSON 回應，以篩選特定工作區的結果。

警告

如果您是在每天有數百或數千個活動的大型組織中，在擷取結果之後篩選結果可能會非常沒有效率。 請記住， 取得活動事件 作業限制為每小時 200 個要求。

若要避免 API 節流（當您超過在指定時段內允許提出的要求數目時），請勿擷取原始資料超過所需的要求數目。 您可以繼續使用篩選的結果，而不執行腳本來再次擷取結果。 針對持續的需求，最好每天擷取所有數據一次，然後再查詢多次。

#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

範例回應 5

以下是篩選的結果，其中包含一小部分的屬性。 此格式比較容易閱讀，以便偶爾進行分析。 不過，如果您打算儲存結果，建議您將其轉換為 JSON 格式。

注意

將 JSON 結果轉換成 PowerShell 物件之後，時間值會轉換成當地時間。 原始稽核數據一律會以國際標準時間 （UTC） 時間記錄，因此我們建議您習慣只使用 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

提示

您可以使用這項技術，依結果中的任何屬性來篩選結果。 例如，您可以使用特定事件 RequestId 只分析一個特定事件。

範例 6：匯出前 N 天的所有活動

有時候，您可能想要將所有活動數據匯出至檔案，以便使用PowerShell外部的數據。 此範例會擷取所有使用者最多30天的所有活動。 它會每天將數據匯出至一個 JSON 檔案。

重要

活動記錄數據最多 30 天可用。 請務必匯出並保留數據，以便執行歷程記錄分析。 如果您目前未匯出並儲存活動記錄數據，強烈建議您優先執行此動作。

範例要求 6

腳本會擷取一連串的所有活動。 它會宣告三個變數：

  • $NbrDaysDaysToExtract：您有興趣匯出多少天。 它會執行迴圈，從前一天往後工作。 允許的最大值是 30 天（因為您可以擷取的最早日期是在目前日期前 30 天）。
  • $ExportFileLocation：您要儲存盤案的資料夾路徑。 執行文稿之前，資料夾必須存在。 請勿在資料夾路徑結尾包含反斜杠 （\） 字元（因為它會在運行時間自動新增）。 建議您使用個別的資料夾來儲存原始資料檔。
  • $ExportFileName：每個檔名的前置詞。 由於每天儲存一個檔案，腳本會新增後綴來指出檔案中包含的數據，以及擷取數據的日期和時間。 例如，如果您在 2023 年 4 月 25 日上午 9 點執行腳本，以擷取 2023 年 4 月 23 日的活動數據，檔名會是：PBIActivityEvents-20230423-202304250900。 雖然儲存所在的資料夾結構很有説明，但每個檔名都應該完整自我描述。

建議您擷取至少一天前一天的數據。 如此一來，您可以避免擷取部分日事件，而且您可以確信每個匯出檔案都包含完整的 24 小時數據。

腳本會收集最多 30 天的數據，到前一天。 稽核事件的時間戳一律為UTC。 建議您根據 UTC 時間而非當地時間建置所有稽核程式。

腳本每天會產生一個 JSON 檔案。 檔名的後綴包含所擷取數據的時間戳（UTC 格式）。 如果您多次擷取同一天的數據，檔名中的後綴可協助您識別較新的檔案。

#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

使用 Get-PowerBIActivityEvent PowerShell Cmdlet，而不是 取得活動事件 REST API 作業有幾個優點。

  • Cmdlet 可讓您在每次使用 Cmdlet 進行呼叫時要求一天的活動。 當您直接與 API 通訊時，您只能要求每個 API 要求一小時。
  • Cmdlet 會為您處理接續令牌。 如果您直接使用 API，您需要檢查接續令牌，以判斷是否有更多結果要來。 某些 API 在傳回大量數據時，基於效能考慮需要使用分頁和接續令牌。 它們會傳回第一組記錄，然後使用接續令牌進行後續 API 呼叫，以擷取下一組記錄。 您會繼續呼叫 API，直到未傳回接續令牌為止。 使用接續令牌是合併多個 API 要求的方式，讓您可以合併一組邏輯結果。 如需使用接續令牌的範例，請參閱 活動事件 REST API。
  • Cmdlet 會為您處理 Microsoft Entra ID（先前稱為 Azure Active Directory）存取令牌到期。 經過驗證之後，您的存取令牌會在一小時后到期（根據預設）。 在此情況下，Cmdlet 會自動為您要求重新整理令牌。 如果您直接與 API 通訊，您必須要求重新整理令牌。

如需詳細資訊，請參閱 選擇 API 或 PowerShell Cmdlet。

注意

省略範例回應，因為它是類似先前範例所示回應的輸出。

相關內容

如需本文的詳細資訊，請參閱下列資源：