为 Unity Catalog 配置目录集成¶

第 1 步：查找您的 Databricks 工作区 URL¶

您的 Databricks 工作区 URL 即为您用于访问该工作区的 URL。您需要找到此 URL，因为稍后在创建目录集成时需要指定它。

1. 查找您的 Databricks 工作区 URL。

   有关如何查找此 URL 的说明，请参阅与您的 Databricks 账户托管环境相对应的主题：

   • AWS 上的 Databricks：` AWS 上的 Databricks：工作区实例名称、URLs 和 IDs <https://docs.databricks.com/aws/workspace/workspace-details#workspace-instance-names-urls-and-ids (https://docs.databricks.com/aws/workspace/workspace-details#workspace-instance-names-urls-and-ids)>`_

   • Azure Databricks：Azure Databricks：确定每个工作区的 URL (https://learn.microsoft.com/azure/databricks/workspace/workspace-details#determine-per-workspace-url)

   • Google Cloud 上的 Databricks：`Google Cloud 上的 Databricks：工作区实例名称、<https://docs.databricks.com/gcp/workspace/workspace-details#workspace-instance-names-urls-and-ids (https://docs.databricks.com/gcp/workspace/workspace-details#workspace-instance-names-urls-and-ids)> 和 `_

2. 将 Databricks 工作区 URL 复制到文本编辑器。

第 2 步：在 Databricks 中添加服务主体¶

1. 要添加服务主体，请参阅与您的 Databricks 账户托管环境相对应的主题：

   • AWS 上的 Databricks：` AWS 上的 Databricks：将服务主体添加到您的账户 <https://docs.databricks.com/aws/admin/users-groups/manage-service-principals?language=Account%C2%A0console#-add-service-principals-to-your-account (https://docs.databricks.com/aws/admin/users-groups/manage-service-principals?language=Account%C2%A0console#-add-service-principals-to-your-account)>`_

   • Azure Databricks：Azure Databricks：将服务主体添加到您的账户 (https://learn.microsoft.com/azure/databricks/admin/users-groups/manage-service-principals#-add-service-principals-to-your-account)

   • Google Cloud 上的 Databricks：Google Cloud 上的 Databricks：将服务主体添加到您的账户 (https://docs.databricks.com/gcp/admin/users-groups/manage-service-principals#-add-service-principals-to-your-account)

2. 将服务主体的 Application ID 值复制到文本编辑器中并安全存储。稍后在 Snowflake 中创建目录集成时需要指定此值。

第 3 步：为您的服务主体创建 OAuth 密钥¶

1. 要为您的服务主体创建 OAuth 密钥，请参阅与您的 Databricks 账户托管环境相对应的主题：

   • AWS 上的 Databricks：` AWS 上的 Databricks：创建 OAuth 密钥 <https://docs.databricks.com/aws/dev-tools/auth/oauth-m2m#-step-1-create-an-oauth-secret (https://docs.databricks.com/aws/dev-tools/auth/oauth-m2m#-step-1-create-an-oauth-secret)>`_

   • Azure Databricks：`Azure Databricks：创建 `_ 密钥 <https://learn.microsoft.com/azure/databricks/dev-tools/auth/oauth-m2m#-step-1-create-an-oauth-secret (https://learn.microsoft.com/azure/databricks/dev-tools/auth/oauth-m2m#-step-1-create-an-oauth-secret)>

   • Google Cloud 上的 Databricks：`Google Cloud 上的 Databricks：创建 `_ 密钥 <https://docs.databricks.com/gcp/dev-tools/auth/oauth-m2m#-step-1-create-an-oauth-secret (https://docs.databricks.com/gcp/dev-tools/auth/oauth-m2m#-step-1-create-an-oauth-secret)>

2. 将生成的 密钥 值复制到文本编辑器中并安全存储。稍后在 Snowflake 中创建目录集成时需要指定此值。

   重要

   客户端密钥仅显示一次。请务必在关闭对话框之前复制它。

第 4 步：在 Unity Catalog 中允许 Snowflake 访问您的目录¶

在此步骤中，您将使用 Databricks 授权 Snowflake 访问 Unity Catalog 中的目录。

要允许 Snowflake 通过分发凭据访问 Unity Catalog 中的目录，首先必须在元存储级别启用外部数据访问。接下来，您需要向服务主体授予针对该目录的 Unity Catalog 权限。

GRANT EXTERNAL USE SCHEMA ON CATALOG example_sales_catalog TO `1aaa1a1a-11a1-1111-1111-1a11111aaa1a`;
GRANT MODIFY ON CATALOG example_sales_catalog TO `1aaa1a1a-11a1-1111-1111-1a11111aaa1a`;
GRANT SELECT ON CATALOG example_sales_catalog TO `1aaa1a1a-11a1-1111-1111-1a11111aaa1a`;
GRANT USE CATALOG ON CATALOG example_sales_catalog TO `1aaa1a1a-11a1-1111-1111-1a11111aaa1a`;
GRANT USE SCHEMA ON CATALOG example_sales_catalog TO `1aaa1a1a-11a1-1111-1111-1a11111aaa1a`;

第 5 步：创建目录集成¶

以下示例创建了使用 OAuth 的 REST 目录集成：

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_oauth_vended_credentials
CATALOG_SOURCE = ICEBERG_REST
TABLE_FORMAT = ICEBERG
REST_CONFIG = (
  CATALOG_URI = '<databricks_workspace_url>/api/2.1/unity-catalog/iceberg-rest'
  CATALOG_NAME = '<catalog_name>'
  ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
)
REST_AUTHENTICATION = (
  TYPE = OAUTH
  OAUTH_TOKEN_URI = '<databricks_workspace_url>/oidc/v1/token'
  OAUTH_CLIENT_ID = '<client_id>'
  OAUTH_CLIENT_SECRET = '<oauth_secret>'
  OAUTH_ALLOWED_SCOPES = ('all-apis')
)
ENABLED = TRUE;

其中：

• <databricks_workspace_url> 指定了 Databricks 工作区的 URL。要查找此 URL，请参阅 第 1 步：查找您的 Databricks 工作区 URL。

  以下是各云平台 Databricks 工作区 URL 的示例：

  • AWS 上的 Databricks：https://dbc-a1a1a1a1-a1a1.cloud.databricks.com

  • Azure Databricks：https://adb-1111111111111111.1.azuredatabricks.net

  • Google Cloud 上的 Databricks：https://1111111111111111.1.gcp.databricks.com

• <catalog_name> 指定了您希望 Snowflake 连接到的 Unity Catalog 目录名称。您可以在 Databricks 工作区的 Data > Catalogs 下找到此名称。

• ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS 将目录集成配置为使用来自 Unity Catalog 的分发凭据。

  备注

  如果您要创建使用外部卷的目录集成，则必须排除 ACCESS_DELEGATION_MODE 参数。

• <client_id> 指定了 Databricks 服务主体的 OAuth 客户端 ID。该值是您在 Databricks 中添加服务主体 时复制的。

  备注

  在 Databricks 中，此值被称为 Application ID，而不是 Client ID。

• <oauth_secret> 指定了 Databricks 服务主体的 OAuth 密钥。该值是您在 为服务主体创建 OAuth 密钥 时复制的。

第 6 步：验证目录集成¶

• 若要验证目录集成的配置，请调用 SYSTEM$VERIFY_CATALOG_INTEGRATION 函数。

  有关更多信息（包括示例），请参阅 使用 SYSTEM$VERIFY_CATALOG_INTEGRATION 检查目录集成配置。

后续步骤¶

在 Unity Catalog 中为目录配置目录集成后，请使用 CREATE DATABASE（目录链接） 命令并指定该目录集成，以创建与目录关联的数据库。随后，Snowflake 会自动与 Unity Catalog 中的目录同步，以检测架构和 Iceberg 表，并将远程表注册到与目录关联的数据库中。

创建与目录关联的数据库时，需要指定目录集成。

For example:

CREATE OR REPLACE DATABASE my_linked_db
   LINKED_CATALOG = (
      CATALOG = 'unity_catalog_int_oauth_vended_credentials'
   );

第 1 步：查找您的 Databricks 工作区 URL¶

您的 Databricks 工作区 URL 即为您用于访问该工作区的 URL。您需要找到此 URL，因为稍后在创建目录集成时需要指定它。

1. 查找您的 Databricks 工作区 URL。

   有关如何查找此 URL 的说明，请参阅与您的 Databricks 账户托管环境相对应的主题：

   • AWS 上的 Databricks：` AWS 上的 Databricks：工作区实例名称、URLs 和 IDs <https://docs.databricks.com/aws/workspace/workspace-details#workspace-instance-names-urls-and-ids (https://docs.databricks.com/aws/workspace/workspace-details#workspace-instance-names-urls-and-ids)>`_

   • Azure Databricks：Azure Databricks：确定每个工作区的 URL (https://learn.microsoft.com/azure/databricks/workspace/workspace-details#determine-per-workspace-url)

   • Google Cloud 上的 Databricks：`Google Cloud 上的 Databricks：工作区实例名称、<https://docs.databricks.com/gcp/workspace/workspace-details#workspace-instance-names-urls-and-ids (https://docs.databricks.com/gcp/workspace/workspace-details#workspace-instance-names-urls-and-ids)> 和 `_

2. 将 Databricks 工作区 URL 复制到文本编辑器。

第 2 步：在 Databricks 中添加个人访问令牌 (PAT)¶

您需要添加个人访问令牌 (PAT)，因为在创建使用持有者令牌进行身份验证的目录集成时必须指定该令牌。

1. 要在 Databricks 中添加 PAT，请参阅与您的 Databricks 账户托管环境相对应的主题：

   • AWS 上的 Databricks：` AWS 上的 Databricks：使用 Databricks 个人访问令牌（旧版）进行身份验证 <https://docs.databricks.com/aws/en/dev-tools/auth/pat (https://docs.databricks.com/aws/en/dev-tools/auth/pat)>`_

   • Azure Databricks：Azure Databricks：使用 Azure Databricks 个人访问令牌（旧版）进行身份验证 (https://learn.microsoft.com/en-us/azure/databricks/dev-tools/auth/pat)

   • Google Cloud 上的 Databricks：Google Cloud 上的 Databricks：使用 Databricks 个人访问令牌（旧版）进行身份验证 (https://docs.databricks.com/gcp/en/dev-tools/auth/pat)

2. 将您的 PAT 值复制到文本编辑器中并安全存储。稍后在 Snowflake 中创建目录集成时需要指定此值。

第 3 步：在 Unity Catalog 中允许 Snowflake 访问您的目录¶

在此步骤中，您将使用 Databricks 授权 Snowflake 访问 Unity Catalog 中的目录。

要允许 Snowflake 通过分发凭据访问 Unity Catalog 中的目录，首先必须在元存储级别启用外部数据访问。接下来，您需要授予 Databricks 用户对目录的 Unity Catalog 权限，您的 PAT 将继承这些权限。

GRANT EXTERNAL USE SCHEMA ON CATALOG example_sales_catalog TO `j.smith@example.com`;
GRANT MODIFY ON CATALOG example_sales_catalog TO `j.smith@example.com`;
GRANT SELECT ON CATALOG example_sales_catalog TO `j.smith@example.com`;
GRANT USE CATALOG ON CATALOG example_sales_catalog TO `j.smith@example.com`;
GRANT USE SCHEMA ON CATALOG example_sales_catalog TO `j.smith@example.com`;

第 4 步：创建目录集成¶

The following example creates a REST catalog integration that uses a bearer token with vended credentials:

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_bearer_vended_credentials
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = '<databricks_workspace_url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<catalog_name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<personal_access_token>'
  )
  ENABLED = TRUE;

其中：

• <databricks_workspace_url> 指定了 Databricks 工作区的 URL。要查找此 URL，请参阅 第 1 步：查找您的 Databricks 工作区 URL。

  以下是各云平台 Databricks 工作区 URL 的示例：

  • AWS 上的 Databricks：https://dbc-a1a1a1a1-a1a1.cloud.databricks.com

  • Azure Databricks：https://adb-1111111111111111.1.azuredatabricks.net

  • Google Cloud 上的 Databricks：https://1111111111111111.1.gcp.databricks.com

• <catalog_name> 指定了您希望 Snowflake 连接到的 Unity Catalog 目录名称。您可以在 Databricks 工作区的 Data > Catalogs 下找到此名称。

• ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS 将目录集成配置为使用来自 Unity Catalog 的分发凭据。

  备注

  如果您要创建使用外部卷的目录集成，则必须排除 ACCESS_DELEGATION_MODE 参数。

• <personal_access_token> specifies your Databricks personal access token (PAT). An example of a PAT is aaaa111aaaa111a1a1a1a111111a111a1111。

第 5 步：验证目录集成¶

• 若要验证目录集成的配置，请调用 SYSTEM$VERIFY_CATALOG_INTEGRATION 函数。

  有关更多信息，请参阅 使用 SYSTEM$VERIFY_CATALOG_INTEGRATION 检查目录集成配置。

后续步骤¶

在 Unity Catalog 中为目录配置目录集成后，请使用 CREATE DATABASE（目录链接） 命令并指定该目录集成，以创建与目录关联的数据库。随后，Snowflake 会自动与 Unity Catalog 中的目录同步，以检测架构和 Iceberg 表，并将远程表注册到与目录关联的数据库中。

创建与目录关联的数据库时，需要指定目录集成。

For example:

CREATE OR REPLACE DATABASE my_linked_db
   LINKED_CATALOG = (
      CATALOG = 'unity_catalog_int_bearer_vended_credentials'
   );