通过

在 Fabric 中创建 API for GraphQL 并添加数据

  • 项目

创建 API，链接数据源，通过 API 公开你选择的数据，以开始使用 Fabric API for GraphQL。 Fabric 会根据数据自动生成 GraphQL 架构，应用程序可在几分钟内完成连接。

先决条件

创建 API for GraphQL

若要创建 API for GraphQL：

  1. 在 Fabric 门户主页中，从工作负载列表中选择“数据工程”。

  2. 选择 API for GraphQL（预览版）。

    API 图块的屏幕截图，你可以选择该图块来创建新的 API 项。

    或者，从数据工程中的任何工作区选择“新建”>“NewAPI for GraphQL（预览版）”。

    工作区工具栏的屏幕截图，其中显示了选择“新建”选项的位置。

  3. 输入项的名称，然后选择“创建”。

    “新建 API for GraphQL”对话框的屏幕截图，其中显示了输入名称并选择“创建”的位置。

现在，你有了一个功能齐全的 API，可以访问 Fabric 中的数据。

连接数据源并生成架构

此时，API 已准备就绪，但未公开任何数据。 API for GraphQL 是在强类型系统中按类型和字段组织的架构中定义的。 Fabric 会根据你选择向 GraphQL 客户端公开的数据自动生成必要的 GraphQL 架构。

  1. 在新的 API 中，通过“选择数据源”来选择要公开的数据源。

    “选择数据源”选项的屏幕截图。

  2. 接下来，选择 API 的连接选项：

    “选择连接”选项的截图。

    在这里，可以定义 API 客户端如何基于两个不同的选项访问 API 以执行 GraphQL 请求：

    • 单一登录 (SSO)：使用客户端凭据连接到数据源，这意味着经过身份验证的 API 用户必须有权访问基础数据源。 例如，如果要向 API 客户端公开 Lakehouse 数据，则经过身份验证的用户需要同时具有 API 和 Lakehouse 的访问权限。 更具体地说，对 GraphQL API 执行权限（添加直接访问权限时“运行查询和突变”的选项）以及相应选择数据源中所需的读取或写入权限。 另一种选择是可以将用户添加为工作区成员，并在 API 和数据源项所在的位置拥有参与者角色，这将提供从单一位置访问这两项所需的权限。 有关详细信息，请参阅授予用户对工作区的访问权限。
    • 保存的凭据：使用保存的凭据连接到数据源，这意味着经过身份验证的 API 用户不需要直接访问数据源。 共享保存的凭据以访问数据源中 API 和基础表之间的数据。 例如，如果要向 API 客户端公开 Lakehouse 数据，则经过身份验证的用户只需对 API 的直接访问权限（添加直接访问权限时的“运行查询和突变”选项），而不是 Lakehouse。 保存的凭据用于将 API 连接到数据源，并由所有经过身份验证的 API 用户共享。 如果要通过 GraphQL 公开 Azure 数据源（例如 Azure SQL 数据库），则需要此选项。 选择“确定”后，在下一步中选择数据源后，系统会提示你创建新的已保存的凭据（如果没有已保存的凭据）。

    选择后，这些选项会强加于后续添加到 API 的所有数据源。 不能在同一 API 中混合使用单一登录和保存的凭据。 此外，虽然可以使用用户主体名称 (UPN) 或服务主体名称 (SPN) 连接到 API，但服务主体目前仅支持单一登录 (SSO)。 根据安全要求，用户主体可以利用 SSO 或保存的凭据。

    注意

    API for GraphQL 要求客户端应用程序使用 Microsoft Entra 进行身份验证。 客户端应用程序必须正确注册和配置，以便对 Fabric 执行 API 调用。 在 Microsoft Entra 中注册的应用需要对 Power BI 服务的 Item.Execute.All API 权限。 可在连接应用程序中找到一个端到端教程，其中包含用户主体和服务主体的说明和示例代码。

  3. 此时会显示 OneLake 数据中心；选择要连接的数据源。 在以下示例中，我们选择链接到镜像数据库的 AdventureWorks SQL 分析终结点。 选择“筛选器”仅查看特定类型的 Fabric 数据源，或按特定关键字搜索。 准备就绪后，选择“连接”。

    OneLake 数据中心的屏幕截图，其中显示了工作区的可用数据源选项。

  4. 此时会显示“获取数据”屏幕，可在其中选择要在 GraphQL 架构中公开的对象。

    “获取数据”屏幕的屏幕截图，其中显示了“选择数据”列表。

  5. 选择要在 API 中公开的单个表或存储过程旁边的检查框。 若要选择文件夹中的所有对象，请选择顶部带有数据源名称的复选框。

    “选择数据”列表的屏幕截图，其中选中了一个文件夹，该文件夹会自动选择该文件夹中的所有项目。

  6. 选择“加载”以启动 GraphQL 架构生成过程。

  7. 架构生成后，你可以开始对 GraphQL 查询（读取、列表）或突变（创建、更新、删除）进行原型设计，以便与数据交互。

    “架构资源管理器”屏幕的屏幕截图。

API for GraphQL 现在已准备好接受连接和请求。 你可以使用 API 编辑器来测试 GraphQL 查询并进行原型设计，使用架构资源管理器来验证 API 中公开的数据类型和字段。

权限摘要

下表总结了访问 GraphQL API 的客户端支持的不同排列和最低所需权限：

API 调用方 数据源连接性 所需的 GraphQL API 权限 所需的数据源权限 Entra 应用范围
用户主体 (UPN) 单一登录 (SSO) 在 API 级别运行查询和突变 在数据源中向 UPN 授予的相应读取/写入权限 Item.Execute.All
服务主体 (SPN) 单一登录 (SSO) 在 API 级别运行查询和突变 在数据源中向 SPN 授予的相应读取/写入权限 Item.Execute.All
用户主体 (UPN) 保存的凭据 在 API 级别运行查询和突变 在数据源中向保存的凭据（连接）授予的相应读取/写入权限 Item.Execute.All
服务主体 (SPN) 保存的凭据 目前不受支持。 目前不受支持。 目前不受支持。

相关内容