在組織的Power BI內嵌式分析應用程式中內嵌快速報表

Power BI 用戶端 API 可讓您快速從應用程式的數據建立互動式報表和數據集，而不需要使用者離開應用程式。使用此用戶端連結庫，您將提供數據源的相關信息，Power BI 將用來在 Power BI 服務內產生數據集。同時，Power BI 會自動產生報表，其中包含用戶數據的深入解析，以探索和自定義以符合其需求。

在本教學課程中，您將瞭解如何：

設定內嵌環境
設定物件以儲存數據源的相關信息並自定義報表
將此物件傳遞至 API，以將資料探索功能新增至您的應用程式

若要使用此體驗，您的用戶必須登入 Power BI。

您將使用組態物件來儲存資料源的相關信息。此外，您也可以使用組態對象來自定義報表的外觀和行為。例如，您可以調整組態物件中的主題和位置設定。當您建立並內嵌數據集時，您接著會將該對象傳遞至 API。

重要

如果您要內嵌國家雲端的內容，本教學課程的前幾個步驟會有所不同。如需詳細資訊，請參閱內嵌國家雲端的內容。

先決條件

開始本教學課程之前，請確認您有下列 Power BI 和程式代碼相依性：

Power BI 相依性
- 您自己的 Azure Active Directory 租使用者。
- 下列其中一個授權，用於測試目的：
  - Power BI 免費
  - Power BI Pro
  - 每位用戶進階版（PPU）
程序代碼相依性
- 文字編輯器
- 命令行終端機，例如 PowerShell

方法

下列各節說明如何使用您慣用的文本編輯器來內嵌和設定 Power BI 內容。

IQuickCreateConfiguration 介面會顯示組態物件可以提供給 Power BI 用戶端 API 的屬性，說明您要建立的數據集：

例

interface IQuickCreateConfiguration { 
    type?: "quickCreate"; 
    accessToken: string; 
    settings?: ISettings; 
    tokenType?: TokenType; 
    theme?: IReportTheme; 
    embedUrl?: string; 
    datasetCreateConfig: IDatasetCreateConfiguration; 
    reportCreationMode?: ReportCreationMode; 
    eventHooks?: EventHooks; 
}

QuickCreate 的存取令牌許可權

僅支援AAD 令牌。請確定您的應用程式具有下列範圍：

Content.Create
Dataset.ReadWrite.All
Report.Read.All
Workspace.Read.All

如需詳細資訊，請參閱註冊應用程式以內嵌Power BI內容。

內嵌 URL

這種內嵌形式獨一無二，此體驗有特殊的路由 /quickcreate。此體驗的典型內嵌 URL 如下所示：https://app.powerbi.com/quickcreate

步驟 1.1 - 建立不含數據源的數據集

如果您無法設定數據源，PowerBI 提供簡單的方法，讓開發人員直接在對 Power BI 的要求中包含數據。我們確實將要求的大小限制為 16MB。請注意，因為 Power BI 沒有要連接的數據源，因此您無法在建立之後重新整理數據集。

IDataTable

IDataTable 基本上是 2D 字串陣列的包裝函式，您應該在其中填入數據。雖然數據是數位，但我們目前只支援 1 個數據表。您可以設定名稱，但它必須符合ITableSchema中的名稱。

為了讓 Power BI 以正確的格式剖析您的資料，您應該遵循 M 語言值規格來格式化您的資料值。 IQuickCreateConfiguration 中定義的地區設定屬性也會影響值的剖析。若要深入瞭解，請參閱 M 語言值 - PowerQuery M。

您的數據應該傳入數據列。每個數據列都應該包含ITableSchema 中定義的相同數據行數目。  

注意

數據和 tableSchemaList 必須成對。

例

const data: IDataTable = [
    { "name": "MyTableName", 
      "rows": [ 
              ["1", "1", "1991"], 
              ["1", "1", "1991"], 
        ]
    } 
]

注意

目前無法自定義 name 屬性，因此您無法命名數據表。屬性的預設名稱為「Table」。

ITableSchema

若要讓 Power BI 瞭解您的資料，您必須提供資料表每個資料行的架構。每個數據行架構都必須有名稱和類型。建立數據集之後，此名稱將做為欄位清單名稱。此類型是 M 語言類型規格的子集。支援的型別會方便列在 DataType 中。若要深入瞭解，請參閱 M 語言類型 - PowerQuery M。

與數據屬性類似，雖然 tableSchemaList 定義為數位，但我們目前只支援單一數據表。
```
export const enum DataType { 
    Number = "Number", 
    Currency = "Currency", 
    Int32 = "Int32", 
    Percentage = "Percentage", 
    DateTime = "DateTime", 
    DateTimeZone = "DateTimeZone", 
    Date = "Date", 
    Time = "Time", 
    Duration = "Duration", 
    Text = "Text", 
    Logical = "Logical", 
    Binary = "Binary",  
    }
```
除了名稱和 dataType 之外，使用者可以為每個數據行提供選擇性屬性 aggregateFunction，以指定數據行的預設匯總。支援的聚合函數數目是以 AggregateFunction 列舉類型為基礎。

例

const tableSchemaList: ITableSchema = [{ 
    name: "MyTableName",  
    columns: [ 
        { 
            name: "createdby", 
            dataType: DataType.Text
             aggregateFunction: 6 // Count 
        }, 
        { 
            name: "createdon", 
            dataType: DataType.DateTime 
        }, 
        { 
            name: "size", 
            dataType: DataType.Number 
        } 
    ]     
}];   
const data: IDataTable = [
    { 
        "name": "MyTableName", 
        "rows": [ 
                ["1", "1", "1991"],
                ["1", "1", "1991"],
        ]
    }
] 
const datasetCreateConfig: IDatasetCreateConfiguration = {
    "modelName": "my model", 
    "locale": "en_US", 
    "tableSchemaList": tableSchemaList,
    "data": data
}

步驟 1.2 - 使用現有的數據源建立數據集

IDatasetCreateConfiguration 是一種設定，可讓Power BI知道如何建立數據集。這包括 Mashup 檔、數據集的地區設定，以及告知 Power BI 如何連線至數據源的連接資訊。

混搭檔

混搭檔或 M 檔有自己的語言規格。為了達到此內嵌體驗的目的，最簡單的開始方式是在Power BI Desktop 中聯機到您選擇的數據源，然後將產生的混搭查詢從查詢編輯器檢視複製出來。如需詳細資訊，請參閱 Power BI Desktop 查詢編輯器檔。

例

Let Source = Csv.Document(Web.Contents("https://yourdomain.com/sample.csv"), [Delimiter=",", QuoteStyle=QuoteStyle.None]), #"Promoted Headers" = Table.PromoteHeader(Source, [PromoteAllScalars=true]) in #"Promoted Headers";"

若要將上述原始程式碼轉換成混搭檔，您只需要在新增區段。區段包括：

section-name;
shared section-member-name = expression;
其中 expression 將是您的混搭查詢，
和 section-member-name 會顯示在 Power BI 中，做為數據表/實體名稱。

針對上述提供的範例混搭查詢，以下是對應的混搭檔範例：

"section Section1; shared #"Table" = let Source = Csv.Document(Web.Contents("https://yourdomain.com/sample.csv"), [Delimiter=",", QuoteStyle=QuoteStyle.None]), #"Promoted Headers" = Table.PromoteHeaders(Source, [PromoteAllScalars=true]) in #"Promoted Headers";"

  一旦您擁有混搭文件之後，您就可以識別哪些元件是靜態的，哪些部分是動態的，而且可以程序設計方式填入。在上述範例中，我們有一些可調整的變數、Web 內容域、分隔符、引號樣式，以及是否要升級標頭。因此，查詢可以轉換成範本，並填入裝載應用程式端的適當參數，視用戶當時所耗用的數據而定。

現場

PowerBI 會使用此組態中提供的地區設定資訊，在提供原始數據時評估混搭檔並剖析值。

數據源組態

數據源的授權

目前，我們僅支持與數據源的匿名連線。這表示Power BI 必須能夠連線到您的數據源，而不需要驗證。

注意

如果您直接在要求中包含數據，您應該省略 dataSourceConnection 屬性。

DataCacheMode

針對大部分的數據源，匯入模式應符合您的需求。不過，在某些情況下，當數據快速變更或數據源非常大時，您也可以使用 DirectQuery 模式。如果您認為這可能適用於您，請閱讀深入瞭解 Power BI 中的 DirectQuery 。

注意

如果您在要求中包含原始數據，則必須匯入 DataCacheMode。

樣本

const datasetCreateConfig: IDatasetCreateConfiguration = { 
    "modelName": "temp model", 
    "locale": "en_US", 
    "mashupDocument": "section Section1; shared Table = let Source = Csv.Document(Web.Contents(\"https://yourdomain.com/sample.csv\"),[Delimiter=\",\", QuoteStyle=QuoteStyle.None]), #\"Promoted Headers\" = Table.PromoteHeaders(Source, [PromoteAllScalars=true]) in #\"Promoted Headers\";", 
    "dataSourceConnection": { 
        "credentialType": CredentialType.Anonymous, // =1 
        "dataCacheMode": DataCacheMode.Import // =1 
    } 
}

步驟 2 - 建立數據集和自動產生報表

現在，您已設定 datasetCreateConfig，即可產生數據集並內嵌自動產生的報表。這類似於可讓您在報表內嵌中建立的 createReport 方法、採用 iframe 容器的 quickCreate 方法，以及可協助您內嵌報表的 quickCreateConfig 方法。

例

const powerbi = window.powerbi; 
const iframeContainer = document.getElementById("myIframeContainer"); 
const quickCreateConfig: IQuickCreateConfiguration = { 
    type: "quickCreate", 
    accessToken: "ey.....",  
    tokenType: TokenType.Aad, // Aad token only 
    embedUrl: "https://app.powerbi.com/quickcreate", // see below for generating the embed url 
    datasetCreateConfig: datasetCreateConfig, 
    reportCreationMode: ReportCreationMode.QuickExplore, // QuickExplore for auto-generated visual,    
    settings: { 
        localeSettings: { 
            language: "en_US" // this should match the current locale of your window/product. It will be used to localize the UI. 
        } 
    } 
}; 
const quickCreateReport = powerbi.quickCreate(iframeContainer, quickCreateConfig);

Last updated on 2024-07-17