在组织的 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
  - Premium Per User （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 如何连接到数据源的连接信息。

Mashup 文档

mashup 文档或 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 = 表达式;
其中表达式将是你的混搭查询，
和 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 BIDirectQuery 的详细信息。

注意

如果在请求中包含原始数据，则必须导入 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

通过