管理 OpenSharing 的数据收件人

本页介绍提供商如何在 Azure Databricks中管理现有的 OpenSharing 收件人。 收件人是一个命名对象，表示与你共享数据的用户或组的标识。

如果你是数据收件人，想要管理从凭据文件导入的提供程序对象，请改为参阅 为数据收件人管理 OpenSharing 提供程序。

若要创建收件人，请参阅创建 OpenSharing 的数据收件人（Databricks 到 Databricks 共享），使用持有者令牌（Databricks 到 Open 共享）为非 Databricks 用户创建收件人对象，或为 OpenSharing 收件人启用 Open ID Connect （OIDC） 联合身份验证。 若要管理共享，请参阅 “管理 OpenSharing 的共享”。

向接收者授予对共享的访问权限

创建收件人和 创建共享后，可以授予收件人对这些共享的访问权限。

若要向接收者授予共享访问权限，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 GRANT ON SHARE SQL 命令。

所需的权限：下列其中一项：

  • Metastore 管理员。
  • 对共享和接收者对象（(USE SHARE + SET SHARE PERMISSION) 或共享所有者）和（USE RECIPIENT 或接收者所有者）拥有委托权限或所有权。

有关说明，请参阅 管理对 OpenSharing 数据共享（对于提供程序）的访问权限。

查看接收者

若要查看接收者列表，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SHOW RECIPIENTS SQL 命令。

所需的权限：必须具有 USE RECIPIENT 查看元存储中的所有收件人的权限。 其他用户只能访问他们自己拥有的收件人。

目录资源管理器

  1. 在 Azure Databricks 工作区中，单击 Data icon.Catalog。

  2. 在“目录”窗格顶部，单击齿轮图标，然后选择OpenSharing。

    或者，在右上角，单击“ 共享 > OpenSharing”。

  3. 在“ 我共享 ”选项卡上，单击“ 收件人”。

SQL

在笔记本或 Databricks SQL 查询编辑器中运行以下命令。 （可选）将<pattern>替换为LIKE谓词。

SHOW RECIPIENTS [LIKE <pattern>];

CLI

使用 Databricks CLI 运行以下命令。

databricks recipients list

查看接收者详细信息

若要查看有关接收者的详细信息，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 DESCRIBE RECIPIENT SQL 命令。

需要的权限：元存储管理员、具有 USE RECIPIENT 特权的用户或收件人对象所有者。

详细信息包括：

  • 收件人的创建者、创建时间戳、注释和身份验证类型（DATABRICKS、 TOKEN、 OAUTH_CLIENT_CREDENTIALS或 OIDC_FEDERATION）。
  • 如果收件人将 Databricks-to-Open 共享与持有者令牌配合使用：令牌生存期、激活链接、激活状态（是否已下载凭据）和 IP 访问列表（如果已分配）。
  • 如果接收方使用 Databricks-to-Open 共享和 OIDC 联合：接收方端点、MTLS 端点、联合策略以及 IP 访问列表（如果已分配）。
  • 如果接收者使用 Databricks 到 Databricks 共享：接收者的 Unity Catalog 元存储的云、区域和元存储 ID，以及激活状态。
  • 接收者属性，包括自定义属性。 请参阅管理接收者属性。

目录资源管理器

  1. 在 Azure Databricks 工作区中，单击 Data icon.Catalog。

  2. 在“目录”窗格顶部，单击齿轮图标，然后选择OpenSharing。

    或者，在右上角，单击“ 共享 > OpenSharing”。

  3. 在“ 我共享 ”选项卡上，单击“ 收件人”，然后选择收件人。

SQL

在笔记本或 Databricks SQL 查询编辑器中运行以下命令。

DESCRIBE RECIPIENT <recipient-name>;

CLI

使用 Databricks CLI 运行以下命令。

databricks recipients get <recipient-name>

查看接收者的共享权限

若要查看收件人有权访问的共享列表，可以使用 Catalog Explorer、Databricks CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 SHOW GRANTS TO RECIPIENT SQL 命令。

需要的权限：元存储管理员、具有 USE RECIPIENT 特权的用户或收件人对象所有者。

目录资源管理器

  1. 在 Azure Databricks 工作区中，单击 Data icon.Catalog。

  2. 在“目录”窗格顶部，单击齿轮图标，然后选择OpenSharing。

    或者，在右上角，单击“ 共享 > OpenSharing”。

  3. 在“ 我共享 ”选项卡上，单击“ 收件人”，然后选择收件人。

  4. 转到“共享”选项卡，查看与接收者共享的共享列表。

SQL

在笔记本或 Databricks SQL 查询编辑器中运行以下命令。

SHOW GRANTS TO RECIPIENT <recipient-name>;

CLI

使用 Databricks CLI 运行以下命令。

databricks recipients share-permissions <recipient-name>

更新接收者

若要更新接收者，可以使用目录资源管理器、Databricks Unity Catalog CLI，或者 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 ALTER RECIPIENT SQL 命令。

可更新的属性包括收件人姓名、所有者、注释和自定义属性。

所需权限：您必须是元数据存储的管理员或接收对象的所有者，才能更新所有者。 你必须具有 CREATE RECIPIENT 权限 并且 是所有者，才能更新名称。 须是所有者才能更新注释或自定义属性。

目录资源管理器

  1. 在 Azure Databricks 工作区中，单击 Data icon.Catalog。

  2. 在“目录”窗格顶部，单击齿轮图标，然后选择OpenSharing。

    或者，在右上角，单击“ 共享 > OpenSharing”。

  3. 在“ 我共享 ”选项卡上，单击“ 收件人”，然后选择收件人。

  4. 在“收件人详细信息”页上：

    • 更新所有者。

    • 编辑或添加注释。

    • 重命名收件人。

      单击 “Kebab”菜单图标。 烤肉串菜单，然后选择“ 重命名”。

    • 编辑、删除或添加自定义接收者属性。

      单击Edit iconEdit icon“收件人”属性旁边的。 然后添加属性名称（键）和 值。 有关详细信息，请参阅 “管理收件人属性”。

    • 仅经过令牌身份验证的接收者：

    • 仅限 OIDC 联合身份接收者：

SQL

在笔记本或 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> [, ...] )

有关属性的详细信息，请参阅管理接收者属性。

CLI

创建一个 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

有关属性的详细信息，请参阅管理接收者属性。

（可选）使用访问列表限制接收者访问权限

你可以限制收件人对 Databricks 到 Open 共享收件人的受限 IP 地址集的访问。 请参阅 使用 IP 访问列表（Databricks-to-Open 共享）限制 OpenSharing 收件人访问。

管理接收者属性

接收者对象包括可用于细化数据共享访问权限的预定义属性。 例如，可以使用它们执行以下操作：

  • 与不同的接收者共享不同的表分区，以便能够与多个接收者使用相同的共享，同时在他们之间保留数据边界。
  • 共享可基于收件人属性来限制收件人对表数据的行或列级访问权限的动态视图。

还可以创建自定义属性。

预定义属性以 databricks. 开头，其中包括：

  • databricks.accountId: 数据接收者所属的 Azure Databricks 帐户（仅限 Databricks 到 Databricks 共享）。
  • databricks.metastoreId：数据接收者所属的 Unity Catalog 元存储（仅适用于 Databricks 到 Databricks 共享）。
  • databricks.name：数据接收者的名称。

例如，可能有价值的自定义属性包括 country。 例如，如果将自定义属性 'country' = 'us' 附加到接收者，则可以按国家/地区对表数据进行分区，并仅与分配了该属性的接收者共享包含 US 数据的行。 还可共享可基于收件人属性来限制行或列级访问权限的动态视图。 如需更详尽的示例，请参阅使用收件人属性执行分区筛选和在共享中添加动态视图以筛选行和列。

要求

必须使用运行 Databricks Runtime 12.2 或更高版本的 SQL 仓库或计算。

在创建或更新接收者时添加属性

可以在创建接收者时添加属性，或更新现有接收者的属性。 可以使用 Catalog Explorer、Databricks Unity Catalog CLI，或者在 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中使用 SQL 命令。

所需的权限：Metastore 管理员，或者对 Unity Catalog Metastore 拥有 特权的用户。

目录资源管理器

使用目录资源管理器创建或更新接收者时，请通过以下操作添加或更新自定义属性：

  1. 转到“接收者详细信息”页。

    如果你正在创建新的接收者，在单击“创建”后会进入此页。 如果您要更新现有收件人，请点击 齿轮图标齿轮图标>OpenSharing > 我共享的 > 收件人，然后选择该收件人以进入此页面。

  2. 在页面右下角的 “收件人”属性下，单击 “铅笔”图标：如果是 Azure Databricks 收件人，则在 databricks.metastoreID 旁边；如果是开放的收件人，则在 databricks.name 旁边。

  3. 输入属性名称（“键”）和“值”。

    例如，如果要按国家/地区筛选共享数据，并且只与此收件人共享中国数据，则可以创建名为“country”且值为“CN”的密钥。

  4. 单击“ 保存”。

SQL

若要在创建接收者时添加自定义属性，请在笔记本或 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>' );

CLI

若要在创建接收者时添加自定义属性，请使用 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 命令。 必须是接收者对象所有者才能删除接收者。

删除某个接收者时，该接收者所代表的用户将不再可以访问共享数据。 收件人在 Databricks 到 Open 共享方案中使用的令牌失效。

所需的权限：收件人对象所有者。

目录资源管理器

  1. 在 Azure Databricks 工作区中，单击 Data icon.Catalog。

  2. 在“目录”窗格顶部，单击齿轮图标，然后选择OpenSharing。

    或者，在右上角，单击“ 共享 > OpenSharing”。

  3. 在“ 我共享 ”选项卡上，单击“ 收件人”，然后选择收件人。

  4. 在“接收者”选项卡上，查找并选择接收者。

  5. 单击 “Kebab”菜单图标。 烤肉串菜单，然后选择“ 删除”。

  6. 在确认对话框中，单击“删除”。

SQL

在笔记本或 Databricks SQL 查询编辑器中运行以下命令。

DROP RECIPIENT [IF EXISTS] <recipient-name>;

CLI

使用 Databricks CLI 运行以下命令。

databricks recipients delete <recipient-name>
  • Last updated on