本页介绍如何创建和管理 Delta Sharing 中的收件人，条件是这些收件人位于已启用 Unity Catalog 的 Databricks 工作区中。
接收方是表示使用共享数据的用户或用户组身份的具有名称的实体。 创建收件人的方式取决于收件人是否能够访问启用了 Unity Catalog 的 Databricks 工作区。
可以访问启用 Unity Catalog 的 Databricks 工作区的用户：
可以使用 Databricks 管理的安全连接创建收件人对象。 这种共享模式称为“Databricks 到 Databricks 共享”，本页对其进行了介绍。
无法访问启用 Unity Catalog 的 Databricks 工作区的收件人：
必须使用 开放共享，并使用基于令牌的身份验证（持有者令牌或 OAuth 联合身份验证）管理的安全连接。 有关创建开放共享接收者的信息，请参阅使用 Open ID Connect (OIDC) 联合身份验证启用对 Delta Sharing 共享（开放共享）的身份验证、使用持有者令牌（开放共享）为非 Databricks 用户创建接收者对象。
有关这两种共享模式以及何时选择哪种模式的详细信息，请参阅开放共享与 Databricks 到 Databricks 共享。
若要创建接收者：
- 你需是元存储管理员，或者对要共享的数据所要注册到的 Unity Catalog 元存储拥有
CREATE_RECIPIENT特权。 - 必须使用附加了 Unity Catalog 元存储的 Azure Databricks 工作区创建接收者。
- 如果使用 Databricks 笔记本创建收件人，则计算必须使用 Databricks Runtime 11.3 LTS 或更高版本以及标准或专用访问模式（以前共享和单用户访问模式）。
对于其他接收者管理操作（例如查看、删除、更新和授予接收者对共享的访问权限），请参阅本文的特定操作部分中列出的权限要求。
如果数据接收者有权访问启用了 Unity Catalog 的 Databricks 工作区，则你可以创建身份验证类型为 DATABRICKS 的接收者对象。
身份验证类型为 DATABRICKS 的接收者对象表示特定 Unity Catalog 元存储中的数据接收者，该接收者在接收者对象定义中由包含元存储的云、区域和 UUID 的共享标识符字符串标识。 只能在该元存储中访问与该接收者共享的数据。
要求接收者用户向你发送 Unity Catalog 元存储的共享标识符，该元存储已附加到接收者用户或用户组将在其中处理共享数据的工作区。
共享标识符是由元存储的云、区域和 UUID（元存储的唯一标识符）组成的字符串，格式为 <cloud>:<region>:<uuid>。
例如，在以下屏幕截图中，完整的共享标识符字符串是 aws:cn-north-2:19a84bee-54bc-43a2-87de-023d0ec16016。
收件人可以使用目录浏览器、Databricks Unity Catalog CLI，或者在他们计划使用的工作区内支持 Unity Catalog 的计算上运行的 Databricks 笔记本或 Databricks SQL 查询中的默认 SQL 函数 CURRENT_METASTORE 来查找标识符。
若要使用目录资源管理器获取共享标识符，请执行以下操作：
在 Azure Databricks 工作区中，单击
“目录”。在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”
。或者，在“快速访问”页中，单击“Delta Sharing”按钮>。
在“与我共享的内容”选项卡上，单击右上角的 Databricks 共享组织名称，然后选择“复制共享标识符”。
在笔记本或 Databricks SQL 查询编辑器中运行以下命令：
SELECT CURRENT_METASTORE();
使用 Databricks CLI 运行以下命令。 共享标识符将作为 global_metastore_id 返回。
databricks metastores summary
可以向你的接收者发送此步骤中包含的信息，也可以引导他们在 Databricks 到 Databricks 模型中获取访问权限。
若要为 Databricks 到 Databricks 共享创建接收者，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 CREATE RECIPIENT SQL 命令。
所需的权限：元存储管理员，或者对要共享的数据所要注册到的 Unity Catalog 元存储拥有 特权的用户。
在 Azure Databricks 工作区中，单击
“目录”。在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”
。或者，在“快速访问”页中，单击“Delta Sharing”按钮>。
在“由我共享的内容”选项卡上，单击“新建收件人”。
输入 收件人姓名。
对于 收件人类型，请选择 Databricks。
输入收件人的 共享标识符。
使用格式为
<cloud>:<region>:<uuid>的完整共享标识符字符串。 例如aws:cn-north-2:19a84bee-54bc-43a2-87de-023d0ec16016。（可选）输入注释。
单击“创建”。
（可选）创建自定义接收者属性。
在“收件人概述”选项卡上，单击
“收件人”属性旁边的。 然后添加属性名称（“键”）和“值”。 有关详细信息，请参阅管理接收者属性。
在笔记本或 Databricks SQL 查询编辑器中运行以下命令：
CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
USING ID '<sharing-identifier>'
[COMMENT "<comment>"];
使用格式为 <cloud>:<region>:<uuid> 的完整共享标识符字符串。 例如 aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef。
还可为接收者添加自定义属性。 有关详细信息，请参阅管理接收者属性。
使用 Databricks CLI 运行以下命令。 替换占位符值替：
-
<recipient-name>：接收者的名称。 -
<sharing-identifier>：格式为<cloud>:<region>:<uuid>的完整共享标识符字符串。 例如aws:eu-west-1:g0c979c8-3e68-4cdf-94af-d05c120ed1ef。 -
<authentication-type>：当为DATABRICKS提供格式为<cloud>:<region>:<uuid>的共享标识符字符串时设置为<sharing-identifier>。
databricks recipients create <recipient-name> <authentication-type> --sharing-code <sharing-identifier>
还可为接收者添加自定义属性。 有关详细信息，请参阅管理接收者属性。
将使用 authentication_type 值 DATABRICKS 创建接收者。
创建接收者并创建共享后，可以向接收者授予对这些共享的访问权限。
若要向接收者授予共享访问权限，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 GRANT ON SHARE SQL 命令。
所需的权限：下列其中一项：
- 元存储管理员。
- 对共享和接收者对象（(
USE SHARE+SET SHARE PERMISSION) 或共享所有者）和（USE RECIPIENT或接收者所有者）拥有委托权限或所有权。
有关说明，请参阅管理对 Delta Sharing 数据共享的访问权限（适用于提供者）。
若要查看接收者列表，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SHOW RECIPIENTS SQL 命令。
所需的权限：必须是元存储管理员或拥有 特权才能查看元存储中的所有接收者。 其他用户只能访问其拥有的接收者。
在 Azure Databricks 工作区中，单击
“目录”。在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”
。或者，在“快速访问”页中，单击“Delta Sharing”按钮>。
在“由我共享的内容”选项卡上，单击“收件人”。
在笔记本或 Databricks SQL 查询编辑器中运行以下命令。 （可选）将 <pattern> 替换为 LIKE 谓词。
SHOW RECIPIENTS [LIKE <pattern>];
使用 Databricks CLI 运行以下命令。
databricks recipients list
若要查看有关接收者的详细信息，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 DESCRIBE RECIPIENT SQL 命令。
所需的权限：元存储管理员、拥有 特权的用户，或接收者对象所有者。
详细信息包括：
- 接收者的创建者、创建时间戳、注释和身份验证类型（
TOKEN或DATABRICKS）。 - 如果接收者使用开放共享：令牌生存期、激活链接、激活状态（凭据是否已下载）和 IP 访问列表（如果已分配）。
- 如果接收者使用 Databricks 到 Databricks 共享：接收者的 Unity Catalog 元存储的云、区域和元存储 ID，以及激活状态。
- 接收者属性，包括自定义属性。 请参阅管理接收者属性。
在 Azure Databricks 工作区中，单击
“目录”。在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”
。或者，在“快速访问”页中，单击“Delta Sharing”按钮>。
在“由我共享的内容”选项卡上，单击“收件人”并选择收件人。
在笔记本或 Databricks SQL 查询编辑器中运行以下命令。
DESCRIBE RECIPIENT <recipient-name>;
使用 Databricks CLI 运行以下命令。
databricks recipients get <recipient-name>
若要查看收件人有权访问的共享列表，可以使用 Catalog Explorer、Databricks CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SHOW GRANTS TO RECIPIENT SQL 命令。
所需的权限：元存储管理员、拥有 特权的用户，或接收者对象所有者。
在 Azure Databricks 工作区中，单击
“目录”。在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”
。或者，在“快速访问”页中，单击“Delta Sharing”按钮>。
在“由我共享的内容”选项卡上，单击“收件人”并选择收件人。
转到“共享”选项卡，查看与接收者共享的共享列表。
在笔记本或 Databricks SQL 查询编辑器中运行以下命令。
SHOW GRANTS TO RECIPIENT <recipient-name>;
使用 Databricks CLI 运行以下命令。
databricks recipients share-permissions <recipient-name>
若要更新接收者，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 ALTER RECIPIENT SQL 命令。
可更新的属性包括收件人姓名、所有者、注释和自定义属性。
所需的权限：必须是元存储管理员或接收者对象的所有者才能更新所有者。 必须是元存储管理员（或拥有 CREATE_RECIPIENT 特权的用户）和所有者才能更新姓名。 须是所有者才能更新注释或自定义属性。
在 Azure Databricks 工作区中，单击
“目录”。在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”
。或者，在“快速访问”页中，单击“Delta Sharing”按钮>。
在“由我共享的内容”选项卡上，单击“收件人”并选择收件人。
在“收件人详细信息”页上：
在笔记本或 Databricks SQL 查询编辑器中运行以下一个或多个命令。
ALTER RECIPIENT <recipient-name> RENAME TO <new-recipient-name>;
ALTER RECIPIENT <recipient-name> OWNER TO <new-owner>;
COMMENT ON RECIPIENT <recipient-name> IS "<new-comment>";
ALTER RECIPIENT <recipient-name> SET PROPERTIES ( <property-key> = property_value [, ...] )
ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( <property-key> [, ...] )
有关属性的详细信息，请参阅管理接收者属性。
创建一个 JSON 文件，其中包含对接收者名称、注释、所有者、IP 访问列表或自定义属性的更新。
{
"name": "new-recipient-name",
"owner": "someone-else@example.com",
"comment": "something new",
"ip_access_list": {
"allowed_ip_addresses": ["8.8.8.8", "8.8.8.4/10"]
},
"property": {
"country": "us",
"id": "001"
}
}
然后使用 Databricks CLI 运行以下命令。 请将 <recipient-name> 替换为当前接收者姓名，并将 update-recipient-settings.json 替换为 JSON 文件的文件名。
databricks recipients update --json-file update-recipient-settings.json
有关属性的详细信息，请参阅管理接收者属性。
配置接收者对象时，可以仅限接收者访问受限的一组 IP 地址。 请参阅使用 IP 访问列表限制 Delta Sharing 接收者访问权限（开放共享）。
接收者对象包括可用于细化数据共享访问权限的预定义属性。 例如，可以使用它们执行以下操作：
- 与不同的接收者共享不同的表分区，以便能够与多个接收者使用相同的共享，同时在他们之间保留数据边界。
- 共享可基于收件人属性来限制收件人对表数据的行或列级访问权限的动态视图。
还可以创建自定义属性。
预定义属性以 databricks. 开头，其中包括：
-
databricks.accountId：数据接收者所属的 Azure Databricks 帐户（仅适用于 Databricks 到 Databricks 共享）。 -
databricks.metastoreId：数据接收者所属的 Unity Catalog 元存储（仅适用于 Databricks 到 Databricks 共享）。 -
databricks.name：数据接收者的名称。
例如，可能有价值的自定义属性包括 country。 例如，如果将自定义属性 'country' = 'us' 附加到接收者，则可以按国家/地区对表数据进行分区，并仅与分配了该属性的接收者共享包含 US 数据的行。 还可共享可基于收件人属性来限制行或列级访问权限的动态视图。 如需更详尽的示例，请参阅使用收件人属性执行分区筛选和在共享中添加动态视图以筛选行和列。
Databricks Runtime 12.2 及更高版本支持接收者属性。
可以在创建接收者时添加属性，或更新现有接收者的属性。 可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SQL 命令。
所需的权限：元存储管理员，或者对 Unity Catalog 元存储拥有 特权的用户。
使用目录资源管理器创建或更新接收者时，请通过以下操作添加或更新自定义属性：
转到“接收者详细信息”页。
如果你正在创建新的接收者，在单击“创建”后会进入此页。 如果要更新某个现有收件人，可以通过单击
齿轮图标 >“Delta Sharing”>“由我共享的内容”>“收件人”并选择该收件人来转到此页。单击“编辑属性”>“+添加属性”。
输入属性名称（“键”）和“值”。
例如，如果你要按国家/地区筛选共享数据并仅与此接收者共享 US 数据，可以创建一个名为“country”且值为“US”的键。
单击“ 保存”。
若要在创建接收者时添加自定义属性，请在笔记本或 Databricks SQL 查询编辑器中运行以下命令：
CREATE RECIPIENT [IF NOT EXISTS] <recipient-name>
[USING ID '<sharing-identifier>'] /* Skip this if you are using open sharing */
[COMMENT "<comment>"]
PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );
<property-key> 可以是字符串字面量或标识符。
<property-value> 必须是字符串字面量。
例如：
CREATE RECIPIENT acme PROPERTIES ('country' = 'us', 'partner_id' = '001');
若要添加、编辑或删除现有接收者的自定义属性，请运行以下命令之一：
ALTER RECIPIENT <recipient-name> SET PROPERTIES ( '<property-key>' = '<property-value>' [, ...] );
ALTER RECIPIENT <recipient-name> UNSET PROPERTIES ( '<property-key>' );
若要在创建接收者时添加自定义属性，请使用 Databricks CLI 运行以下命令。 替换占位符值替：
-
<recipient-name>：接收者的名称。 -
<property-key>可以是字符串字面量或标识符。 -
<property-value>必须是字符串字面量。
databricks recipients create \
--json='{
"name": "<recipient-name>",
"properties_kvpairs": {
"properties": {
"<property-key>": "<property-value>",
}
}
}'
例如：
databricks recipients create \
--json='{
"name": "<recipient-name>",
"properties_kvpairs": {
"properties": {
"country": "us",
"partner_id":"001"
}
}
}'
若要添加或编辑现有接收者的自定义属性，请使用 update 而不是 create：
databricks recipients update \
--json='{
"name": "<recipient-name>",
"properties_kvpairs": {
"properties": {
"country": "us",
"partner_id":"001"
}
}
}'
若要查看接收者属性，请按照查看接收者详细信息中的说明操作。
若要删除接收者，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 DROP RECIPIENT SQL 命令。 必须是接收者对象所有者才能删除接收者。
删除某个接收者时，该接收者所代表的用户将不再可以访问共享数据。 该接收者在开放共享方案中使用的令牌将会失效。
所需的权限：接收者对象所有者。
在 Azure Databricks 工作区中，单击
“目录”。在“目录”窗格顶部，单击 齿轮图标，然后选择“Delta Sharing”
。或者，在“快速访问”页中，单击“Delta Sharing”按钮>。
在“由我共享的内容”选项卡上，单击“收件人”并选择收件人。
在“接收者”选项卡上，查找并选择接收者。
单击
kebab 菜单并选择“删除”。在确认对话框中，单击“删除”。
在笔记本或 Databricks SQL 查询编辑器中运行以下命令。
DROP RECIPIENT [IF EXISTS] <recipient-name>;
使用 Databricks CLI 运行以下命令。
databricks recipients delete <recipient-name>