使用 Delta Sharing（预览版）共享数据

  • 项目

重要

Delta Sharing 目前为公共预览版。 要使用预览版，必须在 Azure Databricks 帐户控制台中启用外部数据共享功能组。 请参阅为帐户启用外部数据共享功能组。

Delta Sharing 受适用条款约束。 启用外部数据共享功能组即表示接受这些条款。

本文介绍如何在 Unity Catalog 中与组织外部的数据接收者共享数据。 如果你是数据接收者，请参阅使用 Delta Sharing 访问与你共享的数据。

增量共享的工作原理是什么？

Delta Sharing（预览版）是由 Databricks 开发的开放协议，用于与其他组织进行安全的数据共享，无论他们使用哪个计算平台。 Databricks 用户也称为“数据提供者”，可以使用 Delta Sharing 与其组织外部的人员或组（称为“数据接收者”）共享数据。 数据接收者可以立即开始使用最新版本的共享数据。 有关连接器的完整列表以及如何使用它们的信息，请参阅 Delta Sharing 文档。 如果对元存储启用了 Delta Sharing，则 Unity Catalog 将运行 Delta Sharing 服务器。

Delta Sharing 体系结构概述

共享数据不由 Databricks 直接提供，而是由 Databricks 上运行的数据提供者提供。

注意

通过作为数据接收者访问数据提供者的共享数据，数据接收者表示其已被授权访问数据提供者提供给其的数据共享，并承认 (1) Databricks 对此类数据或数据接收者对此类共享数据的使用不承担任何责任，以及 (2) Databricks 可收集关于数据接收者使用和访问共享数据的信息（包括识别使用与此类信息相关的凭证文件访问数据的任何个人或公司），并可与适用的数据提供者共享。

要求

  • 必须启用 Unity Catalog，并且必须至少存在一个元存储。
  • 只有帐户管理员才能为元存储启用 Delta Sharing。
  • 只有元存储管理员或帐户管理员才能使用 Delta Sharing 共享数据。 请参阅元存储管理员。
  • 若要轮换接收者的凭据，必须使用 Unity Catalog CLI。 请参阅（可选）安装 Unity Catalog CLI。
  • 若要管理共享和接收者，可使用数据科学与工程笔记本或 Databricks SQL 查询。

关键概念

在 Delta Sharing 中，共享是要与一个或多个接收者共享的表和表分区的只读集合。 一个元存储可以有多个共享，你可以控制哪些接收者有权访问每个共享。 单个元存储可以包含多个共享，但每个共享只能属于一个元存储。 如果删除某个共享，则该共享的所有接收者都将无法访问该共享。

接收者是将组织与允许组织访问一个或多个共享的凭据相关联的对象。 创建接收者时，将为该接收者生成可下载凭据。 每个元存储可以有多个接收者，但每个接收者只能属于一个元存储。 一个接收者可以访问多个共享。 如果删除接收者，则该接收者将失去对其以前可以访问的所有共享的访问权限。

共享和接收者彼此独立存在。

Delta Sharing 中的共享和收件人

若要授予接收者对共享的访问权限，请执行以下操作：

  1. 通过为 Azure Databricks 帐户启用外部数据共享功能组，开始使用 Delta Sharing 公共预览版。
  2. 为每个 Unity Catalog 元存储启用 Delta Sharing。
  3. 创建与元存储中的一个或多个表关联的共享。
  4. 创建接收者。 为该接收者生成一组凭据。
  5. 向接收者授予一个或多个共享的权限。
  6. 使用安全通道向接收者发送允许他们下载凭据的激活链接。
  7. 接收者使用该凭据来访问共享。

以下部分介绍如何为 Azure Databricks 帐户启用 Delta Sharing、对元存储启用 Delta Sharing、管理共享和收件人以及审核 Delta Sharing 活动。

为帐户启用外部数据共享功能组

要使用 Delta Sharing 公共预览版，帐户管理员必须为 Azure Databricks 帐户启用外部数据共享功能组。

  1. 以 Azure Databricks 帐户管理员身份登录到帐户控制台。

  2. 在边栏中，单击设置图标“设置”。

  3. 转到“功能启用”选项卡。

  4. 在“外部数据共享功能组”行上，单击“启用”按钮。

    单击“条款”链接，查看 Delta Sharing 的适用条款。 单击“启用”即表示接受这些条款。

对元存储启用 Delta Sharing

对于你计划使用 Delta Sharing 来共享数据的每个元存储，请执行以下步骤。

  1. 登录到帐户控制台。

    1. 在工作区中，单击设置图标“设置”。
    2. 单击“管理帐户”。

  2. 在边栏中单击 数据图标“数据”。

  3. 单击元存储的名称以打开其详细信息。

  4. 单击“启用 Delta Sharing 并允许 Databricks 用户在组织外部共享数据”旁边的复选框。

  5. Databricks 建议配置默认接收者令牌生存期。 即接收者令牌过期且必须重新生成的时间。 如果未配置此设置，接收者令牌将不会过期。

    更改默认接收者生存期时，现有接收者的接收者令牌生存期不会自动更新。 要更新给定接收者的接收者令牌生存期，请参阅轮换接收者的凭据。

    若要配置默认接收者令牌生存期，请执行以下步骤：

    1. 启用“设置有效期限”。
    2. 输入秒数、分钟数、小时数或天数，然后选择度量单位。
    3. 单击 “启用” 。

    有关详细信息，请参阅关于接收者的安全建议。

（可选）安装 Unity Catalog CLI

若要管理共享和接收者，可使用 SQL 命令或 Unity Catalog CLI。 CLI 在本地环境中运行，不需要 Azure Databricks 计算资源。

若要安装 CLI，请参阅 Unity Catalog 文档中的（可选）安装 Unity Catalog CLI。

修改接收者令牌生存期

启用 Delta Sharing 后，请按照这些步骤修改默认接收者令牌生存期。

注意

更改元存储的默认接收者令牌生存期时，现有接收者的接收者令牌生存期不会自动更新。 要更新给定接收者的接收者令牌生存期，请参阅轮换接收者的凭据。

  1. 登录到帐户控制台。

    1. 在工作区中，单击设置图标“设置”。
    2. 单击“管理帐户”。

  2. 在边栏中单击 数据图标“数据”。

  3. 单击元存储的名称以打开其详细信息。

  4. 启用“设置有效期限”。

  5. 输入秒数、分钟数、小时数或天数，然后选择度量单位。

  6. 单击 “启用” 。

如果禁用“设置有效期限”，接收者令牌将不会过期。 有关详细信息，请参阅关于接收者的安全建议。

管理共享

在 Delta Sharing 中，共享是一个命名对象，其中包含元存储中要以组形式共享的表的集合。 一个共享只能包含一个元存储中的表。 可随时在共享中添加或删除表。

以下部分说明如何创建、描述、更新和删除共享。

创建共享

若要创建共享，请在笔记本或 Databricks SQL 编辑器中运行以下命令。 替换占位符值：

  • <share_name>：共享的描述性名称。
  • <comment>：描述共享的注释。
CREATE SHARE [IF NOT EXISTS] <share_name> [COMMENT <comment>];

创建共享后，可向其添加表，并将其与一个或多个接收者关联。

列出共享

若要列出所有共享，请使用 SHOW SHARES 命令。

SHOW SHARES;

描述共享

若要列出某个共享的元数据以及与共享关联的所有表，请使用 DESCRIBE SHARE 命令。 将 <share_name> 替换为共享的名称：

DESCRIBE SHARE <share_name>;

若要列出共享中的所有表，请使用 SHOW ALL IN SHARES 命令。

SHOW ALL IN SHARE <share_name>;

在共享中添加或删除表

在以下命令中，替换占位符值：

  • <share_name>：共享的名称。
  • <catalog_name>：元存储中目录的名称。
  • <schema_name>：元存储中架构的名称。
  • <table_name>：要添加的表的名称。
  • AS <new_schema_name.<new_table_name>：（可选）使用新名称共享表。
  • <comment>：描述共享的注释。

若要将表与共享关联，请使用 ALTER SHARE ADD TABLE 命令。

ALTER SHARE <share_name>
ADD TABLE <catalog_name>.<schema_name>.<table_name> [deltaSharingPartitionListSpec]
[AS <new_schema_name.<new_table_name>]
[COMMENT <comment>];

有关共享分区的详细信息，请参阅分区规范。

若要从共享中删除表，请使用 ALTER SHARE REMOVE TABLE 命令。

ALTER SHARE <share_name> REMOVE TABLE <catalog_name>.<schema_name>.<table_name>;

注意

可提供元存储中的原始架构和表名称，也可提供共享中定义的名称。

在共享中添加或删除表时，所做的更改将在接收者下次访问共享时生效。

分区规范

若要在将表添加到共享时仅共享表的一部分，可提供分区规范。 以下示例共享 inventoryyear 表中的部分数据，假定该表按 month 和 date 列分区。

  • 2021 年的数据。
  • 2020 年 12 月的数据。
  • 2019 年 12 月 25 日的数据。
ALTER SHARE share_name
ADD TABLE inventory
PARTITION (year = "2021"),
          (year = "2020", month = "Dec"),
          (year = "2019", month = "Dec", date = "2019-12-25");

删除共享

若要删除共享，请使用 DROP SHARE 命令。 接收者无法再访问以前共享的数据。 将 <share_name> 替换为共享的名称。

DROP SHARE [IF EXISTS] <share_name>;

管理接收者

接收者是一个命名凭据集，表示要与之共享数据的组织。 本部分演示如何在 Delta Sharing 中管理接收者。

创建接收者

使用 CREATE RECIPIENT 命令创建接收者。 替换占位符值：

  • <recipient_>：接收者的描述性名称。
  • <comment>：包含详细信息的注释。
CREATE RECIPIENT [IF NOT EXISTS] <recipient_name> COMMENT <comment>

接收者的令牌将在接收者令牌生存期期满后过期。 有关详细信息，请参阅关于接收者的安全建议。

创建接收者后：

  1. 使用 DESCRIBE 命令获取激活链接。
  2. 使用安全通道与他们共享激活链接以及演示如何访问共享数据的文章。 激活链接只能访问一次。 接收者应将下载的凭据视为机密，不得在组织外部共享。 如有必要，可轮换接收者的凭据。
  3. 授予他们对共享的访问权限。

列出接收者

SHOW RECIPIENTS 命令可列出所有接收者。 （可选）将 <pattern> 替换为 LIKE 谓词。

SHOW RECIPIENTS [LIKE <pattern>];

描述接收者

若要查看有关接收者的详细信息，包括其创建者、创建时间戳、令牌生存期、激活链接以及凭据是否已下载，请使用 DESCRIBE RECIPIENT 命令。 将 <recipient_name> 替换为接收者的名称。

DESCRIBE RECIPIENT <recipient_name>;

若要显示对接收者的授权，请参阅管理接收者的权限。

删除接收者

若要删除接收者，请使用 DROP RECIPIENT 命令。 将 <recipient_name> 替换为要删除的接收者的名称。 删除接收者时，凭据将失效，他们不能再查看共享。

DROP RECIPIENT [IF EXISTS] <recipient_name>

轮换接收者的凭据

出现以下情况时，应轮换接收者的凭据并生成新的激活链接：

  • 现有接收者令牌即将过期。
  • 接收者丢失其激活 URL，或者该 URL 遭到入侵。
  • 凭据在接收者下载后损坏、丢失或泄露。
  • 在修改元存储的接收者令牌生存期后，需要更新接收者的令牌生存期。

  1. 如果尚未这样做，请安装 Unity Catalog CLI。

  2. 使用 Unity Catalog CLI 运行以下命令。 括号中的参数是可选的。 替换占位符值：

    • <recipient_name>：接收者的名称。

    • <expiration_seconds>：可选。 现有接收者令牌过期之前的秒数。 在此期间，现有令牌将继续有效。 值为 0 表示现有令牌立即过期。

      databricks unity-catalog rotate-recipient-token \
  --name <recipient_name> \
  [--existing-token-expire-in-seconds <expiration_seconds>]

  3. 使用 DESCRIBE RECIPIENT <recipient_name> 命令查看激活 URL，然后通过安全通道将其共享给接收者。

管理接收者的权限

创建共享和接收者后，使用 GRANT 和 REVOKE 语句授予接收者对共享的访问权限。 在以下示例中，替换占位符值：

  • <share_name>：共享的名称。
  • <recipient_name>：接收者的名称

若要显示针对共享的所有授权，请执行以下操作：

SHOW GRANTS ON SHARE <share_name>;

若要查看向接收者授予的所有权限，请执行以下操作：

SHOW GRANTS TO RECIPIENT <recipient_name>;

若要授予访问权限，请执行以下操作：

GRANT SELECT
ON SHARE <share_name>
TO RECIPIENT <recipient_name>;

若要撤销访问权限，请执行以下操作：

REVOKE SELECT
ON SHARE <share_name>
FROM RECIPIENT <recipient_name>;

注意

SELECT 是可针对共享授予的唯一权限。

关于接收者的安全建议

启用 Delta Sharing 时，为接收者凭据配置令牌生存期。 如果将令牌生存期设置为 0，接收者令牌将永不过期。 Databricks 建议为令牌配置有效期限。

在下列情况下，应轮换接收者的凭据：

在任何给定时间，接收者最多只能有两个令牌：一个有效令牌和一个轮换令牌。 在轮换令牌过期之前，尝试再次轮换令牌会导致错误。

轮换接收者的凭据时，可选择将 --existing-token-expire-in-seconds 设置为现有接收者令牌过期前的秒数。 如果将值设置为 0，现有接收者令牌将立即过期。

Databricks 建议将 --existing-token-expire-in-seconds 设置为相对较短的时间段，让接收者组织有时间访问新激活 URL，同时尽量缩短接收者具有两个有效令牌的时间。 如果怀疑接收者令牌已泄露，Databricks 建议强制使现有接收者令牌立即过期。

如果接收者的现有激活 URL 从未被访问过，并且接收者尚未被轮换，则轮换接收者会使现有激活 URL 失效，并用新的激活 URL 替换。

如果所有接收者令牌都已过期，轮换接收者会使用新的激活 URL 替换现有激活 URL。 Databricks 建议立即轮换或删除令牌已过期的接收者。

如果接收者激活链接无意中发送给了错误的人，或者通过不安全的通道发送，Databricks 建议执行以下操作：

  1. 撤消接收者对共享的访问权限。
  2. 轮换接收者，并将 --existing-token-expire-in-seconds 设置为 0。
  3. 通过安全通道将新的激活链接共享给目标接收者。
  4. 激活 URL 被访问后，授予接收者再次访问共享的权限。

在极端情况下，Databricks 建议删除并重新创建接收者。

审核 Delta Sharing 资源的访问和活动

在配置诊断日志记录后，Delta Sharing 会保存活动的审核日志，例如某人何时创建、修改、更新或删除共享或接收者，接收者何时访问激活链接并下载凭据，或者接收者的凭据何时轮换或过期。 Delta Sharing 活动在帐户级别记录。

  1. 为帐户启用诊断日志。

    重要

    Delta Sharing 活动在帐户级别记录。 请勿在 workspace_ids_filter 中输入值。

    审核日志针对帐户的每个工作区以及帐户级活动提供。 日志将传送到配置的存储容器。

  2. Delta Sharing 事件在 serviceName 设置为 unityCatalog 的情况下记录。 每个事件的 requestParams 部分都包含 delta_sharing 前缀。

    例如，以下审核事件显示对接收者令牌生存期的更新。 在本示例中，修订后的值替换为 <redacted>。

    {
   "version":"2.0",
   "auditLevel":"ACCOUNT_LEVEL",
   "timestamp":1629775584891,
   "orgId":"3049059095686970",
   "shardName":"example-workspace",
   "accountId":"<redacted>",
   "sourceIPAddress":"<redacted>",
   "userAgent":"curl/7.64.1",
   "sessionId":"<redacted>",
   "userIdentity":{
      "email":"<redacted>",
      "subjectName":null
   },
   "serviceName":"unityCatalog",
   "actionName":"updateMetastore",
   "requestId":"<redacted>",
   "requestParams":{
       "id":"<redacted>",
       "delta_sharing_enabled":"true"
       "delta_sharing_recipient_token_lifetime_in_seconds": 31536000
    },
   "response":{
      "statusCode":200,
      "errorMessage":null,
      "result":null
   },
   "MAX_LOG_MESSAGE_LENGTH":16384
}

下表从数据提供者的角度列出了 Delta Sharing 的审核事件。

注意

以下重要字段始终出现在审核日志中：

  • userIdentity.email：发起活动的用户的 ID。
  • requestParams.id：Unity Catalog 元存储。
actionName requestParams
updateMetastore delta_sharing_enabled：如果存在，则表示 Delta Sharing 已启用。

delta_sharing_recipient_token_lifetime_in_seconds：如果存在，则表示接收者令牌生存期已更新。
createRecipient name：接收者的名称。

comment：接收者的注释。
deleteRecipient name：接收者的名称。
getRecipient name：接收者的名称。
listRecipients 无
rotateRecipientToken name：接收者的名称。

comment：轮换命令中给定的注释。
createShare name：共享的名称。

comment：共享的注释。
deleteShare name：共享的名称。
getShare name：共享的名称。

include_shared_objects：请求中是否包含共享的表名。
updateShare name：共享的名称。

updates：已在共享中添加或删除的表的 JSON 表示形式。 每一项都包含 action（添加或删除）、name（表的实际名称）、shared_as（架构和表共享时的名称，是否不同于 name）以及partition_specification（是否提供分区规范）。
listShares 无
getSharePermissions name：共享的名称。
updateSharePermissions name：共享的名称。
changes 更新的权限的 JSON 表示形式。 每项更改都包含 principal（向其授予或撤消权限的用户或组）、add（已授予的权限列表）、remove（已撤消的权限列表）。
getRecipientSharePermissions name：共享的名称。
getActivationUrlInfo recipient_name：打开激活 URL 的接收者的名称。
retrieveRecipientToken recipient_name：下载令牌的接收者的名称。

从数据接收者的角度来看，记录以下 Delta Sharing 错误。 < 和 > 字符之间的项表示占位符文本。

  • 未对所选元存储启用 Delta Sharing。

      DatabricksServiceException: FEATURE_DISABLED:
  Delta Sharing is not enabled`

  • 尝试对不存在的目录执行操作。

    DatabricksServiceException: CATALOG_DOES_NOT_EXIST:
Catalog ‘xxx’ does not exist.`

  • 不是帐户管理员或元存储管理员的用户尝试执行特权操作。

    DatabricksServiceException: PERMISSION_DENIED:
Only administrators can <operation_name> <operation_target>

  • 尝试从未向其分配元存储的工作区对元存储执行操作。

    DatabricksServiceException: INVALID_STATE:
Workspace <workspace_name> is no longer assigned to this metastore

  • 请求缺少接收者名称或共享名称。

    DatabricksServiceException: INVALID_PARAMETER_VALUE: CreateRecipient/CreateShare Missing required field: <recipient_name>/<share_name>

  • 请求包含无效的接收者名称或共享名称。

    DatabricksServiceException: INVALID_PARAMETER_VALUE: CreateRecipient/CreateShare <recipient_name>/<share_name> is not a valid name

  • DatabricksServiceException: INVALID_PARAMETER_VALUE: Only managed or external table on Unity Catalog can be added to a share.

    用户尝试共享不在 Unity Catalog 元存储中的表。

  • DatabricksServiceException: INVALID_PARAMETER_VALUE: There are already two active tokens for recipient <recipient_name>.

    用户尝试轮换已处于轮换状态以及以前的令牌尚未过期的接收者。

  • DatabricksServiceException: RECIPIENT_ALREADY_EXISTS/SHARE_ALREADY_EXISTS: Recipient/Share <name> already exists

    用户尝试创建与现有接受者或共享同名的新接收者或共享。

  • DatabricksServiceException: RECIPIENT_DOES_NOT_EXIST/SHARE_DOES_NOT_EXIST: Recipient/Share '<name>' does not exist.

    用户尝试对不存在的接收者或共享执行操作。

  • DatabricksServiceException: RESOURCE_ALREADY_EXISTS: Shared Table '<name>' already exists.

    用户尝试向共享添加表，但该表已添加。

  • DatabricksServiceException: TABLE_DOES_NOT_EXIST: Table '<name>' does not exist.

    用户尝试执行引用了不存在的表的操作。

  • DatabricksServiceException: SCHEMA_DOES_NOT_EXIST: Schema '<name>' does not exist.

    用户尝试执行引用了不存在的架构的操作。

有关数据接收者的可审核事件和错误，请参阅审核 Delta Sharing 资源的访问和活动。

限制

  • 只有存储在 Unity Catalog 元存储中的表才能使用 Delta Sharing 共享。
  • 仅支持 Delta 格式的托管表和外部表。
  • 此预览版不支持共享视图。

后续步骤