管理外部位置

2025-06-11

本文介绍如何列出、查看、更新、授予权限、启用文件事件以及删除外部位置。

注意

Databricks 建议使用卷管理文件访问。请参阅什么是 Unity Catalog 卷？。

描述外部位置

若要查看外部位置的属性（包括权限和工作区访问权限），可以使用目录资源管理器或 SQL 命令。

目录资源管理器

在边栏中，单击目录。
在“快速访问”页中，单击“外部数据>”按钮，然后转到“外部位置”选项卡。
单击外部位置的名称以查看其属性。

SQL

在笔记本或 Databricks SQL 编辑器中运行以下命令。将 <___location-name> 替换为外部位置的名称。

DESCRIBE EXTERNAL LOCATION <___location-name>;

显示外部位置的授予

若要在外部位置显示授予，请使用如下命令。你可以选择筛选结果以只显示指定主体的授权。

SHOW GRANTS [<principal>] ON EXTERNAL LOCATION <___location-name>;

替换占位符的值：

<___location-name>：允许在您的云租户中读取和写入存储容器或存储桶的外部位置的名称。
<principal>：帐户级用户的电子邮件地址或帐户级组的名称。

注意

如果组或用户名包含空格或 @ 符号，请使用其周围的后刻度（` `），而不是撇号。

对外部位置授予权限

本部分介绍如何使用目录资源管理器和笔记本或 SQL 查询中的 SQL 命令授予和撤销对外部位置的权限。有关改用 Databricks CLI 或 Terraform 的信息，请参阅 Databricks Terraform 文档和什么是 Databricks CLI？。

你可以在外部位置授予以下权限：

CREATE EXTERNAL TABLE
CREATE EXTERNAL VOLUME
CREATE MANAGED STORAGE

所需权限：对外部位置中引用的元存储和存储凭据具有 CREATE EXTERNAL LOCATION 权限，或对外部位置具有 MANAGE 权限。默认情况下，元存储管理员对元存储具有 CREATE EXTERNAL LOCATION。

授予使用外部位置的权限：

目录资源管理器

在边栏中，单击目录。
在“快速访问”页中，单击“外部数据>”按钮，然后转到“外部位置”选项卡。
单击外部位置的名称以打开其属性。
单击“权限”。
若要向用户或组授予权限，请选择每个标识，然后单击“授予”。
若要撤销用户或组的权限，请选择每个标识，然后单击“撤销”。

SQL

在笔记本或 SQL 查询编辑器中运行以下 SQL 命令。此示例授予创建引用外部位置的外部表的能力：

GRANT CREATE EXTERNAL TABLE ON EXTERNAL LOCATION <___location-name> TO <principal>;

替换占位符的值：

<___location-name>：允许在您的云租户中读取和写入存储容器或存储桶的外部位置的名称。
<principal>：帐户级用户的电子邮件地址或帐户级组的名称。

注意

如果组或用户名包含空格或 @ 符号，请在其周围使用反勾（而不是撇号）。例如，财务团队。

更改外部位置的所有者

外部位置的创建者是其初始所有者。若要将所有者更改为其他帐户级别的用户或组，请在笔记本或 Databricks SQL 编辑器中运行以下命令，或使用目录资源管理器。

所需权限：外部位置所有者或具有 MANAGE 权限的用户。

替换占位符的值：

<___location-name>：该凭据的名称。
<principal>：帐户级用户的电子邮件地址或帐户级组的名称。

ALTER EXTERNAL LOCATION <___location-name> OWNER TO <principal>

将外部位置标记为只读

如果希望用户对外部位置具有只读访问权限，可以使用目录资源管理器将外部位置标记为只读。

将外部位置标记为只读：

阻止用户写入这些外部位置中的文件，而不考虑存储凭据的 Azure 托管标识授予的任何写入权限，也不管对该外部位置授予的 Unity Catalog 权限如何。
阻止用户在这些外部位置创建托管表或卷。
使系统能够在创建时正确验证外部位置。

创建外部位置时，可以将外部位置标记为只读。

还可使用目录资源管理器在创建外部位置后更改只读状态：

在边栏中，单击目录。
在“快速访问”页中，单击“外部数据>”按钮，然后转到“外部位置”选项卡。
选择外部位置，单击 “ 测试连接 ”按钮旁边的菜单，然后选择“ 编辑”。
在“编辑”对话框中，单击“高级选项”并选择“限制为只读使用”选项。
单击“更新” 。

在外部位置配置加密算法（仅 AWS S3）

AWS 支持使用 Amazon S3 托管密钥（SSE-S3）或 AWS KMS 密钥（SSE-KMS）进行服务器端加密（SSE），以保护 S3 中的数据。如果 S3 存储桶需要 SSE 加密，则可以在外部位置配置加密算法，以允许 Unity 目录中的外部表和卷访问 S3 存储桶中的数据。 SSE 不支持通过增量共享共享的外部表。有关详细信息，请参阅使用 KMS 为 S3 配置加密。

在边栏中，单击目录。
在 “目录” 窗格顶部，单击并选择“外部位置”。
选择外部位置。外部位置必须为存储凭据使用 IAM 角色。
单击“测试Kebab menu icon.连接”按钮旁边的，然后选择“编辑”。
在“编辑”对话框中，单击“ 高级选项”。
在 “加密算法 ”下，根据加密密钥选择 SSE-SE 或 SSE-KMS 。

对于 SSE-KMS，在 “加密 KMS 密钥 arn” 下粘贴客户端访问 S3 位置时引用的 KMS 密钥的 ARN。
单击“更新” 。

（推荐）为外部位置启用文件事件

重要

此功能目前以公共预览版提供。

如果要引入云提供商推送的更改通知，为外部位置启用文件事件具有以下优势：

更轻松地为自动加载程序设置文件通知。具体而言，通过将cloudFiles.useManagedFileEvents设置为true，可以在自动加载程序中实现类似通知性能的增量文件发现。请参阅在文件通知模式下配置自动加载程序流。
提高了用于作业的文件到达触发器的效率和容量。请参阅在新文件到达时触发作业。

在您开始之前

如果要让 Azure Databricks 代表您配置 Azure 数据湖存储队列或 SQS 队列，您的外部位置必须引用能提供足够权限的存储凭据以进行配置。有关说明，请参阅下一步。

如果要创建自己的 Azure Data Lake 存储队列，则存储凭据所表示的标识必须对这些 Azure Data Lake 存储队列具有以下权限：

存储队列数据贡献者

如果要创建自己的 SQS 队列，存储凭据所表示的标识必须对这些 SQS 队列具有以下权限：

sqs:ReceiveMessage
sqs:DeleteMessage
sqs:PurgeQueue

步骤 1：确认 Azure Databricks 有权访问 Azure Data Lake Storage 或 AWS S3 中的文件事件

在可以为外部位置安全对象启用文件事件之前，必须确保已将 Azure Data Lake Storage 或 AWS S3 帐户配置为向 Azure Databricks 授予对它发出的文件事件的访问权限。如果希望 Azure Databricks 为你配置 Azure Data Lake Storage 或 AWS S3 中的文件事件，还必须确保 Azure Databricks 具有适当的访问权限。

配置存储凭据时，建议分配此访问权限。

对于 Azure Data Lake Storage 容器

若要确认授予对外部位置访问权限的托管身份已正确配置，请执行以下操作：

获取 Azure 托管标识 ID。
1. 在边栏中，单击目录。
2. 在“快速访问”页中，单击“外部数据>”按钮，然后转到“外部位置”选项卡。
3. 选择外部位置。
4. 在“ 概述 ”选项卡上，单击 “凭据 名称”。
5. 在“存储凭据概述 ”选项卡上，复制 连接器 ID 或 用户分配的托管标识 ID。
  
  你将下一步骤中使用此内容。
登录到 Azure Data Lake Storage 帐户。
转到 访问控制（IAM）， 然后单击 “检查访问 ”按钮。
在 托管标识中，根据托管标识类型选择 用户分配的托管标识 或 Azure Databricks 的访问连接器。
搜索你在步骤 1 中复制的托管标识。
确认托管标识具有以下角色：
- 存储 blob 数据参与者
- EventGrid EventSubscription 参与者
- 存储队列数据参与者：只有在希望 Azure Databricks 为你在 Azure Data Lake Storage 中创建订阅和事件时才需要。如果未启用此角色，则必须自行创建 Azure 存储队列。
如果缺少这些角色中的任何一个，请转到 “符合条件的分配 ”选项卡并添加这些角色。

有关分配这些角色的详细信息，请参阅步骤 3：授予托管标识对文件事件的访问权限，步骤 4：授予 Azure Databricks 代表你配置文件事件的访问权限。

对于 S3 存储桶

验证 Databricks 是否可以配置和订阅存储桶的事件通知：

获取 IAM 角色。
1. 在边栏中，单击目录。
2. 在“快速访问”页中，单击“外部数据>”按钮，然后转到“外部位置”选项卡。
3. 选择外部位置。
4. 在“ 概述 ”选项卡上，单击 “凭据 名称”。
5. 在“存储凭据概述”选项卡上，复制IAM 角色（ARN）。
  
  你将下一步骤中使用此内容。
登录到 AWS 帐户。
转到 IAM 并搜索在步骤 1 中复制的角色。
在 “权限”策略下，找到与 IAM 角色关联的 IAM 策略或策略，然后打开它。

打开策略或策略，并确认有一个包含以下属性。

此策略允许 Azure Databricks 帐户更新存储桶的事件通知配置、创建 SNS 主题、创建 SQS 队列，并将 SQS 队列订阅到 SNS 主题。

替换为 <BUCKET> S3 存储桶的名称。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ManagedFileEventsSetupStatement",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketNotification",
        "s3:PutBucketNotification",
        "sns:ListSubscriptionsByTopic",
        "sns:GetTopicAttributes",
        "sns:SetTopicAttributes",
        "sns:CreateTopic",
        "sns:TagResource",
        "sns:Publish",
        "sns:Subscribe",
        "sqs:CreateQueue",
        "sqs:DeleteMessage",
        "sqs:ReceiveMessage",
        "sqs:SendMessage",
        "sqs:GetQueueUrl",
        "sqs:GetQueueAttributes",
        "sqs:SetQueueAttributes",
        "sqs:TagQueue",
        "sqs:ChangeMessageVisibility",
        "sqs:PurgeQueue"
      ],
      "Resource": ["arn:aws:s3:::<BUCKET>", "arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    },
    {
      "Sid": "ManagedFileEventsListStatement",
      "Effect": "Allow",
      "Action": ["sqs:ListQueues", "sqs:ListQueueTags", "sns:ListTopics"],
      "Resource": ["arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    },
    {
      "Sid": "ManagedFileEventsTeardownStatement",
      "Effect": "Allow",
      "Action": ["sns:Unsubscribe", "sns:DeleteTopic", "sqs:DeleteQueue"],
      "Resource": ["arn:aws:sqs:*:*:csms-*", "arn:aws:sns:*:*:csms-*"]
    }
  ]
}

另请参阅步骤 1：创建 IAM 角色。

如果缺少此策略，请将其配置到 IAM 角色中。

步骤 2：使用目录资源管理器为外部位置启用文件事件

若要启用文件事件，请执行以下步骤。

在边栏中，单击目录。
在“快速访问”页中，单击“外部数据>”按钮，然后转到“外部位置”选项卡。
选择外部位置。
单击“测试Kebab menu icon.连接”按钮旁边的，然后选择“编辑”。
在“编辑”对话框中，单击“ 高级选项”。
选择“ 启用文件事件”。
选择 “文件”事件类型：

自动：（建议）如果希望 Azure Databricks 为你设置订阅和事件，请选择此选项。

提供：如果已自行配置 Azure 存储队列或 SQS 队列，请选择此选项。
如果选择了提供的文件事件类型，请输入现有存储队列的队列 URL。
- Azure 存储队列： https://<storage account>.queue.core.windows.net/<queue>
- AWS SQS 队列： https://sqs.<region>.amazonaws.com/<account-ID>/<queue-name>
单击“更新” 。
等待几秒钟，然后单击主外部位置编辑页面上的测试连接，以确认文件事件已成功启用。

文件事件限制

外部位置上的文件事件具有以下限制：

事件吞吐量限制为每秒引入 2000 个文件。
不能使用 resourceTags 此选项标记云资源。相反，在自动加载程序服务创建队列和订阅资源后，使用云控制台标记资源。
如果没有为该存储位置定义外部位置，则无法为 Unity 目录元存储根存储位置设置文件事件。

不能在 Unity 目录中未定义外部位置对象的存储位置上设置文件事件。 Unity 目录的某些实现包括与外部位置不关联的元存储根存储位置。要确定您的元存储库根存储位置是否符合此条件：
1. 作为帐户管理员，登录到帐户控制台。
2. 单击目录。
3. 单击元存储名称。
4. 转到 “配置 ”选项卡。
5. 如果有 ADLS Gen 2 路径 值，则元存储根没有为其定义外部位置对象。
  
  若要更新元存储根存储以使用外部位置，请单击“ 删除 ”按钮。将为你创建一个外部场所。有关详细信息，请参阅 “删除元存储级别存储”。

不支持 Azure Blob 存储。

修改外部位置

外部位置的所有者或具有 MANAGE 特权的用户可以更改外部位置的名称、URI 和存储凭证。

若要重命名外部位置，请执行以下操作：

在笔记本或 Databricks SQL 编辑器中运行以下命令。替换占位符的值：

<___location-name>：位置的名称。
<new-___location-name>：位置的新名称。

ALTER EXTERNAL LOCATION <___location-name> RENAME TO <new-___location-name>;

若要更改云租户中外部位置指向的 URI，请执行以下操作：

在笔记本或 Databricks SQL 编辑器中运行以下命令。替换占位符的值：

<___location-name>：外部位置的名称。
<url>：该位置应该授权你的云租户访问的新存储 URL。

ALTER EXTERNAL LOCATION location_name SET URL '<url>' [FORCE];

即使外部表依赖于外部位置，FORCE 选项也会更改 URL。

若要更改外部位置使用的存储凭据，请执行以下操作：

在笔记本或 Databricks SQL 编辑器中运行以下命令。替换占位符的值：

<___location-name>：外部位置的名称。
<credential-name>：用来访问云租户中位置 URL 的存储凭据的名称。

ALTER EXTERNAL LOCATION <___location-name> SET STORAGE CREDENTIAL <credential-name>;

删除外部位置

若要删除（丢弃）外部位置，你必须是其所有者，或者对外部位置具有 MANAGE 特权。若要删除外部位置，请执行以下操作：

在笔记本或 Databricks SQL 编辑器中运行以下命令。括号中的项是可选的。将 <___location-name> 替换为外部位置的名称。

DROP EXTERNAL LOCATION [IF EXISTS] <___location-name>;

通过

管理外部位置

描述外部位置

目录资源管理器

SQL

显示外部位置的授予

对外部位置授予权限

目录资源管理器

SQL

更改外部位置的所有者

将外部位置标记为只读

在外部位置配置加密算法（仅 AWS S3）

（推荐）为外部位置启用文件事件

在您开始之前

步骤 1：确认 Azure Databricks 有权访问 Azure Data Lake Storage 或 AWS S3 中的文件事件

对于 Azure Data Lake Storage 容器

对于 S3 存储桶

步骤 2：使用目录资源管理器为外部位置启用文件事件

文件事件限制

修改外部位置

删除外部位置

反馈

其他资源