管理外部位置

2025-10-24

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

注意

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

描述外部位置

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

目录资源管理器

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

SQL

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

DESCRIBE EXTERNAL LOCATION <location-name>;

显示外部位置的授予

若要查看外部位置的授予，可以使用目录资源管理器或 SQL 命令。

目录资源管理器

在边栏中，单击目录。
在“快速访问”页面上，单击“外部数据”> 按钮转到“外部位置”选项卡。
单击外部位置的名称。
单击“权限”。

SQL

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

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

替换占位符的值：

<location-name>：授权读取和写入云租户中的存储容器或存储桶的外部位置的名称。
<principal>：帐户级用户的电子邮件地址或帐户级组的名称。如果组或用户名包含空格或 @ 符号，请使用其周围的后刻度（` `），而不是撇号。

对外部位置授予权限

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

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

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

目录资源管理器

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

SQL

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

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

替换占位符的值：

<location-name>：授权读取和写入云租户中的存储容器或存储桶的外部位置的名称。
<principal>：帐户级用户的电子邮件地址或帐户级组的名称。如果组或用户名包含空格或 @ 符号，请在其周围使用反引号（不是撇号）。例如 finance team 。

将外部位置分配给特定工作区

默认情况下，外部位置可从元存储中的所有工作区访问。这意味着，如果用户已被授予该外部位置的权限（例如，READ FILES），则可以从附加到元存储的任何工作区行使该权限。如果使用工作区来隔离用户数据访问，则可能需要仅允许从特定工作区访问外部位置。此功能称为工作区绑定或外部位置隔离。

将外部位置绑定到特定工作区的典型用例包括：

确保对包含生产数据的外部位置具有CREATE EXTERNAL TABLE权限的数据工程师只能在生产工作区中创建该位置的外部表。
确保对包含敏感数据的外部位置具有READ FILES权限的数据工程师只能使用特定工作区访问该数据。

有关如何按工作区限制其他类型的数据访问的详细信息，请参阅将目录访问仅限于特定工作区。

重要

在对外部位置行使特权时，将引用工作区绑定。例如，如果用户通过从 CREATE TABLE myCat.mySch.myTable LOCATION 'abfss://my-container-name@storage-account-name.dfs.core.windows.net/finance' 工作区发出语句 myWorkspace 创建外部表，则除了常规用户特权检查之外，还会执行以下工作区绑定检查：

覆盖 'abfss://my-container-name@storage-account-name.dfs.core.windows.net/finance' 的外部位置是否绑定到 myWorkspace？
目录 myCat 是否绑定到具有 myWorkspace 访问级别的 Read & Write？

如果外部位置随后与 myWorkspace 解除绑定，则外部表将继续运行。

此功能还允许从中央工作区填充目录，并使用目录绑定将其提供给其他工作区，而无需在其他工作区中提供外部位置。

将外部位置绑定到一个或多个工作区

要将外部位置分配到特定的工作区，可以使用目录资源管理器或 Databricks CLI。

所需权限：元存储管理员、外部位置所有者或对外部位置拥有权限。MANAGE

注意

元存储管理员可以使用目录资源管理器查看元存储中的所有外部位置，外部位置所有者可以查看他们在元存储中拥有的所有外部位置，无论外部位置是否已分配到当前工作区。未分配给工作区的外部位置显示为灰色。

目录资源管理器

登录到链接到元存储的工作区。
在边栏中，单击目录。
在“快速访问”页面上，单击“外部数据”> 按钮转到“外部位置”选项卡。
选择外部位置，然后转到“工作区”选项卡。
在“工作区”选项卡上，清除“所有工作区拥有访问权限”复选框。

如果外部位置已绑定到一个或多个工作区，则此复选框已清除。
单击“分配到工作区”，然后输入或查找要分配的工作区。

若要撤销访问权限，请转到“工作区”选项卡，选择该工作区，然后单击“撤销”。若要允许从所有工作区进行访问，请选中“所有工作区都具有访问权限”复选框。

CLI

向工作区分配外部位置时需使用两个 Databricks CLI 命令组并分两个步骤完成。

在以下示例中，将 <profile-name> 替换为 Azure Databricks 身份验证配置文件的名称。它应包括个人访问令牌的值，以及生成个人访问令牌的工作区的工作区实例名称和工作区 ID。请参阅个人访问令牌身份验证（已弃用）。

使用 external-locations 命令组的 update 命令将外部位置的 isolation mode 设置为 ISOLATED：
```
databricks external-locations update <my-location> \
--isolation-mode ISOLATED \
--profile <profile-name>
```
对于附加到元存储的所有工作区，默认的 isolation-mode 设置为 OPEN。
使用 workspace-bindings 命令组的 update-bindings 命令将工作区分配到外部位置：
```
databricks workspace-bindings update-bindings external-location <my-location> \
--json '{
  "add": [{"workspace_id": <workspace-id>}...],
  "remove": [{"workspace_id": <workspace-id>}...]
}' --profile <profile-name>
```
使用 "add" 和 "remove" 属性添加或删除工作区绑定。

注意

只读绑定 (BINDING_TYPE_READ_ONLY) 不适用于外部位置。因此，没有理由为外部位置绑定设置binding_type。

若要列出某个外部位置的所有工作区分配，请使用 workspace-bindings 命令组的 get-bindings 命令：

databricks workspace-bindings get-bindings external-location <my-location> \
--profile <profile-name>

另请参阅 REST API 参考中的工作区绑定。

解除工作区对外部位置的绑定

workspace-bindings中包含有关使用目录资源管理器或 CLI 命令组撤销工作区对外部位置的访问权限的说明。

更改外部位置的所有者

外部位置的创建者是其初始所有者。若要将所有者更改为其他帐户级别的用户或组，可使用目录资源管理器或 SQL 命令。

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

目录资源管理器

在边栏中，单击目录。
在“快速访问”页面上，单击“外部数据”> 按钮转到“外部位置”选项卡。
单击外部位置的名称。
单击“所有者”Edit icon旁边的。
键入以搜索主体并将其选中。
单击“ 保存”。

SQL

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

<location-name>：凭据的名称。
<principal>：帐户级用户的电子邮件地址或帐户级组的名称。如果组或用户名包含空格或 @ 符号，请在其周围使用反引号（不是撇号）。例如 finance team 。

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

将外部位置标记为只读

如果希望用户对外部位置具有只读访问权限，可以使用目录资源管理器将外部位置标记为只读。此更改可能需要长达 60 分钟才能在所有计算资源中生效。

将外部位置标记为只读：

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

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

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

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

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

AWS 支持需要客户端设置加密标头的 S3 存储桶策略。请参阅 AWS 文档中的需要加密。如果 S3 存储桶需要请求上的加密标头，则必须在 Unity 目录中的外部位置上配置加密算法。访问 S3 存储桶中的数据时，此设置用于配置正确的标头。不支持访问通过Delta Sharing共享的外部表的此功能。

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

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

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

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

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

在您开始之前

如果希望 Azure Databricks 代表你配置 Azure Data Lake Storage 队列或 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 策略或策略，然后打开它。

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

要使用以下策略让 Databricks 自动创建通知资源（File event type 被设置为 Automatic），请遵循以下策略。它允许您的 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-*"]
    }
  ]
}

或者，若要自行设置通知资源，并为 Azure Databricks 提供队列终结点（File event type 设置为 Provided），请使用以下策略。

请将 <QUEUE_NAME> 替换为您的 SQS 队列的名称。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ManagedFileEventsReadStatement",
      "Effect": "Allow",
      "Action": ["sqs:DeleteMessage", "sqs:ReceiveMessage", "sqs:SendMessage", "sqs:PurgeQueue"],
      "Resource": ["arn:aws:sqs:*:*:<QUEUE_NAME>"]
    }
  ]
}

在使用提供的队列时，请确保提供的SQS队列已订阅该存储桶的以下S3事件通知：

s3：ObjectCreated：*
s3：ObjectRemoved：*
s3：LifecycleExpiration：*

另请参阅步骤 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>
单击“更新” 。
等待几秒钟，然后单击主外部位置编辑页面上的测试连接，以确认文件事件已成功启用。

文件事件限制

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

文件事件缓存仅保存过去 7 天内修改的文件的元数据。因此，仅当至少每 7 天运行一次自动加载程序时，它才能支持增量读取。如果您不以至少这么频繁的频率运行自动加载程序，它会执行完整的目录清单以刷新缓存和检查点。
事件吞吐量限制为每秒引入 2000 个文件。
不能使用 resourceTags 此选项标记云资源。相反，在自动加载程序服务创建队列和订阅资源后，使用云控制台标记资源。
如果没有为该存储位置定义外部位置，则无法为 Unity 目录元存储根存储位置设置文件事件。

不能在 Unity 目录中未定义外部位置对象的存储位置上设置文件事件。某些 Unity Catalog 实现包括与外部位置无关的元存储根存储位置。要确定您的元存储库根存储位置是否符合此条件：
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

对外部位置授予权限

目录资源管理器

SQL

将外部位置分配给特定工作区

将外部位置绑定到一个或多个工作区

目录资源管理器

CLI

解除工作区对外部位置的绑定

更改外部位置的所有者

目录资源管理器

SQL

将外部位置标记为只读

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

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

在您开始之前

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

对于 Azure Data Lake Storage 容器

对于 S3 存储桶

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

文件事件限制

修改外部位置

删除外部位置

反馈

其他资源