为 OneLake REST 配置目录集成¶

先决条件¶

• 在开始之前，您必须找到 Fabric 中用于工作区的工作区 ID，以及 Fabric 中用于 Lakehouse 的数据项 ID。在为 OneLake REST 创建目录集成时，您将在后续步骤中指定工作区 ID 和数据项 ID。

  • 要查找工作区 ID (<workspaceID>)，请参阅工作区中某项的 Fabric 站点的 URL。有关更多信息，请参阅 Microsoft Fabric 文档中的 `确定工作区 ID<https://learn.microsoft.com/en-us/fabric/admin/portal-workspace#identify-your-workspace-id>`_。将工作区 ID 复制到文本编辑器。

  • 要查找数据项 ID (<dataItemID>), open your lakehouse, and then refer to the value after )，打开 Lakehouse，然后参阅 URL 中 lakehouses 之后的值。有关更多信息，请参阅 Microsoft Fabric 文档中的 Lakehouse 源配置 (https://learn.microsoft.com/en-us/fabric/data-factory/connector-lakehouse-copy-activity#source)，并查看连接要点。将数据项 ID 复制到文本编辑器。

• 在 Fabric 工作区中，确保任何数据项（例如 Lakehouse 中）都有 Iceberg 表。

第 1 步：配置 OneLake 的访问权限¶

要配置 OneLake 的访问权限，您需要在 Microsoft Azure 中创建应用程序注册，为应用程序注册添加 user_impersonation 权限，并为应用程序注册创建新的客户端密钥。

1. 在 Azure 中，创建应用程序注册。

   有关详细信息，请参阅 Microsoft Entra 文档中的 `在 Microsoft Entra 中注册应用程序 ID<https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app>`_。

2. 在应用程序注册中，添加 user_impersonation 权限。

   要开始使用，请按照 使用 Microsoft Entra 管理中心中的前四个步骤操作，以在 Microsoft Graph 文档中查找您组织使用的 APIs (https://learn.microsoft.com/en-us/graph/migrate-azure-ad-graph-configure-permissions?tabs=http&pivots=entra-portal-api-permissions#use-the-microsoft-entra-admin-center-to-find-the-apis-your-organization-uses)。

   重要

   切勿切换到步骤中所述的 APIs my organization uses 选项卡。相反，请切换到 Microsoft APIs 选项卡，选择 Azure Storage，然后添加 user_impersonation 权限。

3. 为应用程序注册创建一个新的客户端密钥，然后将密钥复制到文本编辑器中。

   有关说明，请参阅 Microsoft Entra 文档中的 创建新的客户端密钥 (https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal#option-3-create-a-new-client-secret)。您可以在创建目录集成时指定此密钥。

   重要

   请记住将密钥复制到文本编辑器，因为以后将无法对其进行检索。

4. 从应用程序注册的 Overview 页面中，将 Display name、Application (client) ID 和 Directory (tenant) ID 复制到文本编辑器。

   您可以在创建目录集成和外部卷时指定这些值。

第 2 步：授予应用程序注册对 Fabric 工作区的访问权限¶

在此步骤中，您将授予应用程序注册对 Fabric 中工作区的访问权限。

1. 导航到 Microsoft Fabric (https://app.fabric.microsoft.com/)，然后登录。

2. 打开 Microsoft Fabric 工作区。

3. 选择 Manage access。

4. 选择 + Add people or groups。

5. 在 Enter name or email 字段中，粘贴应用程序注册的名称。

   此名称是您在 为 OneLake 配置访问权限 时复制的 Display name。

6. 从下拉菜单中，选择 Contributor 访问权限或更高版本，以允许应用程序创建必要的 Fabric 项目。

7. 选择 Add。

第 3 步：在 Snowflake 中创建目录集成¶

通过使用 CREATE CATALOG INTEGRATION (Apache Iceberg™ REST) 命令为 REST API 端点创建目录集成。

例如：

CREATE OR REPLACE CATALOG INTEGRATION my_onelake_catalog_int
   CATALOG_SOURCE = ICEBERG_REST
   TABLE_FORMAT = ICEBERG
   REST_CONFIG = (
      CATALOG_URI = 'https://onelake.table.fabric.microsoft.com/iceberg'
      CATALOG_NAME = '<fabric_data_item_scope>'
   )
   REST_AUTHENTICATION = (
      TYPE = OAUTH
      OAUTH_TOKEN_URI = '<azure_active_directory_token_endpoint>'
      OAUTH_CLIENT_ID = '<entra_application_client_id>'
      OAUTH_CLIENT_SECRET = '<entra_application_client_secret>'
      OAUTH_ALLOWED_SCOPES = ('https://storage.azure.com/.default')
   )
   ENABLED = TRUE;

其中：

• https://onelake.table.fabric.microsoft.com/iceberg 是位于 OneLake 表端点的基本 URL。

• <fabric_data_item_scope> is the Fabric data item scope, in the form <workspaceID>/<dataItemID>, such as 12345678-abcd-1abc-1a11-111111ab1111/11111111-abcd-1111-1ab1-1111a1a1ab91. To find your <workspaceID> and <dataItemID>，请参阅 先决条件。

• <azure_active_directory_token_endpoint_> is your Azure Active Directory OAuth 2.0 token endpoint URL, in the form of https://login.microsoftonline.com/<entra_tenant_id>/oauth2/v2.0/token. For <entra_tenant_id> 您指定 Entra 租户 ID，该 ID 为您在 为 OneLake 配置的访问权限 时所复制的内容。

• <entra_application_client_id> 是您的 Entra 应用程序客户端 ID，该 ID 为您在 为 OneLake 配置访问权限 时所复制的内容，例如 11111111-aabb-1a11-abc1-ab11111a11a1。

• <entra_application_client_secret> 是您的应用程序客户端密钥，该密钥为您在 为 OneLake 配置访问权限 时所复制的内容。

• https://storage.azure.com/.default 是存储令牌受众。

第 4 步：配置外部卷¶

在此步骤中，您将使用 OneLake URL 和 Entra 租户 ID 为 Azure 配置外部卷。

1. 使用 CREATE EXTERNAL VOLUME 命令创建外部卷。

   例如：

   CREATE OR REPLACE EXTERNAL VOLUME my_onelake_extvol
      STORAGE_LOCATIONS =
      (
         (
               NAME = 'my_onelake_extvol'
               STORAGE_PROVIDER = 'AZURE'
               STORAGE_BASE_URL = '<azure_onelake_url>'
               AZURE_TENANT_ID='<entra_tenant_id>'
         )
      )
      ALLOW_WRITES = FALSE;
   

   Copy

   其中：

   • <azure_onelake_url> is your Azure OneLake URL, in the form of azure://onelake.dfs.fabric.microsoft.com/<workspaceID>/<dataItemID>, such as azure://onelake.dfs.fabric.microsoft.com/12345678-abcd-1abc-1a11-111111ab1111/11111111-abcd-1111-1ab1-1111a1a1ab91. To find your <workspaceID> and <dataItemID>，请参阅 先决条件。

   • <entra_tenant_id> is your Entra tenant ID, such as, 11111111-aabb-1a11-abc1-ab11111a11a1。您在 为 OneLake 配置访问权限 时复制了 Entra 租户 ID。

2. 要检索 Microsoft 权限请求页面的 URL，请使用 DESCRIBE EXTERNAL VOLUME 命令。指定先前创建的外部卷的名称。

   DESC EXTERNAL VOLUME my_onelake_extvol;
   

   Copy

   记录以下属性的值：

   属性	描述
   AZURE_CONSENT_URL	Microsoft 权限请求页面的 URL。
   AZURE_MULTI_TENANT_APP_NAME	为账户创建的 Snowflake 客户端应用程序的名称。在本部分后面的步骤中，您会授予此应用程序在允许的存储位置获取访问令牌的权限。

   您可在以下步骤中使用这些值。

3. 在 Web 浏览器中，导航到 Microsoft 权限请求页面 (AZURE_CONSENT_URL)。

4. 选择 Accept。此操作允许为 Snowflake 账户创建的 Azure 服务主体获取租户内指定资源的访问令牌。仅当您在存储账户级授予服务主体适当的权限时，才能成功获取访问令牌（请参阅下一步）。

5. 授予多租户应用程序权限，以获取 Fabric 中允许的存储位置的访问令牌。

   1. 导航到 Microsoft Fabric (https://app.fabric.microsoft.com/)，然后登录。

   2. 打开 Microsoft Fabric 工作区。

   3. 选择 Manage access。

   4. 选择 + Add people or groups。

   5. 在 Enter name or email 字段中，粘贴您为 AZURE_MULTI_TENANT_APP_NAME 记录的值。

   6. 从下拉菜单中，选择 Contributor 访问权限或更高版本，以允许应用程序创建必要的 Fabric 项目。

   7. 选择 Add。

有关更多信息，请参阅 Microsoft Fabric 文档中的 Snowflake 目录集成和 Microsoft Fabric 中的外部卷代码示例 REST 端点 (https://learn.microsoft.com/en-us/fabric/onelake/table-apis/iceberg-table-apis-get-started#snowflake)。

后续步骤¶

配置 OneLake REST 和外部卷的目录集成后，您可以使用 CREATE DATABASE（目录链接） 命令创建目录链接数据库，然后在 Snowflake 中的 OneLake 读取表。

创建目录链接数据库时，您需要指定创建的目录集成和外部卷。

例如：

CREATE OR REPLACE DATABASE my_linked_db
   LINKED_CATALOG = (
      CATALOG = 'my_onelake_catalog_int'
   )
   EXTERNAL_VOLUME = 'my_onelake_extvol';

SELECT SYSTEM$CATALOG_LINK_STATUS('IRC_CATALOG_LINKED');

SELECT * FROM my_linked_db."dbo"."sentiment";