配置具有出站私有连接功能的 Apache Iceberg™ REST 目录集成¶

本主题介绍如何为符合开源 Apache Iceberg™ REST OpenAPI 规范 (https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml) 的远程目录中托管的 Apache Iceberg™ 表配置目录集成。

通过此配置，您可使用目录集成通过私有 IP 地址（而非公共互联网）连接到远程 Iceberg REST 目录。

下图显示了 Iceberg 表如何使用与外部 Iceberg 目录的目录集成。

有关 Snowflake 中出站专用连接的一般信息，包括出站专用连接成本，请参阅出站网络流量的专用连接。

本主题介绍以下目录类型的配置步骤：

通用 Iceberg REST 目录
AWS Glue Data Catalog
Databricks Unity 目录

备注

专用连接仅适用于使用 AWS PrivateLink 的 AWS 目录集成，以及使用 Azure 专用链接的 Azure 目录集成。
专用连接仅在相同云提供商内部可用；目录与 Snowflake 部署必须运行于同一云提供商环境中。
配置具有出站专用连接的目录集成时，不支持目录提供的凭证。

第 1 步：收集目录的专用连接信息¶

您需先收集专用连接信息，以便后续在 Snowflake VPC 或 VNet 中配置相应专用连接端点时进行指定。配置相应私有连接端点时，若您的 Snowflake 账户托管在 AWS 上，需在 Snowflake 中创建 AWS PrivateLink 端点；若托管在 Azure 上，则需创建 Azure 专用端点。

要收集目录的专用连接信息，请参阅远程 REST Iceberg 目录的文档。

以下示例是 AWS 中的 AWS VPC 端点服务 ID：com.amazonaws.vpce.us-west-2.vpce-svc-0123456789abcdef。

您必须找到您的 AWS Glue Data Catalog 的提供商服务名称和主机名：

获取您的 提供商服务名称 (<provider_service_name>), copy com.amazonaws.<region>.glue into your text editor where <region> 是存储 Iceberg 表的 AWS 区域。

提供商服务名称的示例如下：com.amazonaws.us-west-2.glue。有关更多信息，请参阅 AWS 文档中的为 AWS Glue 创建界面 VPC 端点 (https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html#vpc-endpoint-create)。
获取您的 主机名 (<host_name>), copy glue.<region>.amazonaws.com into your text editor where <region> 是存储 Iceberg 表的 AWS 区域。

主机名示例如下：glue.us-west-2.amazonaws.com。有关更多信息，请参阅 AWS 文档中的使用 AWS Glue Iceberg REST 端点连接到 Data Catalog (https://docs.aws.amazon.com/glue/latest/dg/connect-glu-iceberg-rest.html)。

备注

或者，您可通过 AWS 命令行使用 describe-vpc-endpoint-services 子命令来获取这些值。有关更多信息，请参阅提供专用连接端点。

您需要查找 Databricks Unity Catalog 的 PrivateLink VPC 端点服务 ID 及其工作区主机名：

要查找您的 PrivateLink VPC 端点服务 ID (<vpc_endpoint_service_id>)，请参阅 Databricks 文档中的 PrivateLink VPC 端点服务 (https://docs.databricks.com/aws/en/resources/ip-domain-region#privatelink)。

本主题包含每个 AWS 区域的 VPC 端点服务 IDs 的列表。
将托管您表格所在区域的端点服务 ID（即工作区 （含 REST API） 对应的值）复制到文本编辑器中。

VPC 端点服务 ID 的示例为 com.amazonaws.vpce.us-west-2.vpce-svc-0129f463fcfbc46c5。

有关 Databricks PrivateLink 的更多信息，请参阅 Databricks 文档中的配置前端 PrivateLink (https://docs.databricks.com/aws/security/network/front-end/front-end-private-connect)。
要查找 Databricks 工作区主机名 (<databricks_workspace_host_name>)，请按照以下步骤操作：
1. 检索 Databricks 工作区 URL。
  
  有关说明，请参阅 Databricks 文档中的获取工作区对象的标识符 (https://docs.databricks.com/aws/en/workspace/workspace-details)。
  
  本主题包括示例 Databricks 工作区 URL。
2. 将 Databricks 工作区 URL 复制到文本编辑器。
3. 从 Databricks 工作区 URL 移除 https://。
  
  生成的值是 Databricks 工作区主机名。
  
  例如，如果每个 Databricks 工作区 URL 是 https://dbc-a1a11111-1a11.cloud.databricks.com，您的 Databricks 工作区主机名是 dbc-a1a11111-1a11.cloud.databricks.com。

您需要在 Azure 门户中查找 Databricks 工作区的资源 ID 及其主机名：

要 在 Azure 门户 (``<databricks_workspace_resource_id>``) 中找到 Databricks 工作区的资源 ID，请按以下步骤操作：
1. 在 Azure 门户中，导航到 Databricks 工作区。
2. 在 Overview 页面的 Essentials 部分中，选择 JSON View 链接。
  
  Databricks 工作区的资源 ID 显示在 Resource ID 字段中。此资源 ID 的示例是 /subscriptions/1111-22-333-4444-55555/resourceGroups/my-rg/providers/Microsoft.Databricks/workspaces/my-databricks-workspace。
3. 将资源 ID 复制到文本编辑器。
要查找 Databricks 工作区主机名 (<databricks_workspace_host_name>)，请按照以下步骤操作：
1. 检索您每个 Databricks 工作区的 URL。
  
  有关说明，请参阅 Azure Databricks 文档中的确定每个工作区 URL (https://learn.microsoft.com/en-us/azure/databricks/workspace/workspace-details#determine-per-workspace-url)。
2. 将每个 Databricks 工作区的 URL 复制到文本编辑器。
3. 从每个 Databricks 工作区 URL 中移除 https://。
  
  生成的值是 Databricks 工作区主机名。
  
  例如，如果每个 Databricks 工作区 URL 是 https://adb-1234567890123456.12.azuredatabricks.net，您的 Databricks 工作区主机名是 adb-1234567890123456.12.azuredatabricks.net。

第 2 步：提供专用连接端点¶

在此步骤中，您需要在 Snowflake VPC 或 VNet 中配置私有连接端点，使 Snowflake 能够通过私有连接访问远程 Iceberg REST 目录。

要预置专用连接端点，请调用 SYSTEM$PROVISION_PRIVATELINK_ENDPOINT 系统函数。

关于该系统函数实参的设置说明，请参阅您要通过私有连接访问的远程 REST Iceberg 目录的相关文档。

以下代码块展示了配置 AWS PrivateLink 端点的示例：
```
SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT(
  'com.amazonaws.vpce.us-west-2.vpce-svc-0123456789abcdef',
  'my.catalog.com'
  );
```
Copy

要预置专用连接端点，请调用 SYSTEM$PROVISION_PRIVATELINK_ENDPOINT 系统函数：
```
USE ROLE ACCOUNTADMIN;
SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT(
  '<provider_service_name>',
  '<host_name>'
);
```
Copy
其中：
- <provider_service_name> 是您在收集目录专用连接信息时复制的提供商服务名称。
- <host_name> 是您在收集目录专用连接信息时复制的主机名。
例如：
```
SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT(
  'com.amazonaws.<region>.glue',
  'glue.<region>.amazonaws.com'
  );
```
Copy
备注

您只需要在 Snowflake VPC 中预置一个专用连接端点。这是因为，通过 AWS Glue 专用连接端点，您可以访问同一区域中 AWS Glue Data Catalog 管理的所有资源。有关更多信息，请参阅 AWS 文档中的为 AWS Glue 创建界面 VPC 端点 (https://docs.aws.amazon.com/glue/latest/dg/vpc-interface-endpoints.html#vpc-endpoint-create)。

您只需要预置一个专用连接端点。Unity 只需要一个专用连接端点即可访问同一区域中由 Unity Data Catalog 管理的所有内容。

要预置专用连接端点，请调用 SYSTEM$PROVISION_PRIVATELINK_ENDPOINT 系统函数：
USE ROLE ACCOUNTADMIN; SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT( '<vpc_endpoint_service_id>', '<databricks_workspace_host_name>' );
Copy
其中：
- <vpc_endpoint_service_id> 是您在收集目录专用连接信息时复制的 PrivateLink VPC 端点服务 ID
- <databricks_workspace_host_name> 是您在收集目录私有连接信息时获取的 Databricks 工作区主机名
  
  备注
  
  若您在同一个 AWS 区域中有多个 Databricks 工作区，可在 Databricks 工作区 URL 中使用通配符。
例如：
SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT( 'com.amazonaws.vpce.us-west-2.vpce-svc-0129f463fcfbc46c5', 'dbc-a1a11111-1a11.cloud.databricks.com' );
Copy

要预置专用连接端点，请调用 SYSTEM$PROVISION_PRIVATELINK_ENDPOINT 系统函数：

USE ROLE ACCOUNTADMIN;

SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT(
  '<databricks_workspace_resource_id>',
  '<databricks_workspace_host_name>',
  'databricks_ui_api'
);
Copy
其中：

<<databricks_workspace_resource_id>> 是您在收集目录专用连接信息时复制的 Azure 门户中 Databricks 工作区的资源 ID。

<databricks_workspace_host_name> 是您在收集目录专用连接信息时获取的 Databricks 工作区主机名。

databricks_ui_ap 是 Azure Databricks 工作区的子资源值。

例如：
SELECT SYSTEM$PROVISION_PRIVATELINK_ENDPOINT(
  '/subscriptions/1111-22-333-4444-55555/resourceGroups/my-rg/providers/Microsoft.Databricks/workspaces/my-databricks-workspace',
  'adb-1234567890123456.12.azuredatabricks.net',
  'databricks_ui_api'
);
Copy

第 3 步：验证端点状态¶

在此步骤中，您需验证上一步在 Snowflake VPC 或 VNet 中配置的专用连接端点的状态。

要验证端点状态，请调用 SYSTEM$GET_PRIVATELINK_ENDPOINTS_INFO 系统函数：
```
SELECT SYSTEM$GET_PRIVATELINK_ENDPOINTS_INFO();
```
Copy
当 status 从 pending 变为 available 时，表示该端点已准备就绪可供使用。

第 4 步：其他特定于目录的配置¶

完成目录类型的其他配置步骤。

备注

对于某些目录或特定类型的专用连接端点，您还需在目录服务器端批准连接或将专用连接端点加入允许列表。

要完成额外的配置步骤，请参阅远程 REST Iceberg 目录的文档，然后继续下一步。

在此步骤中，您需在 Databricks 中注册 Snowflake 端点，以接收来自 VPC 端点的流量。

在 Databricks 中完成配置步骤

在注册 Snowflake VPC 端点前，请确保已在 Databricks 中完成以下配置：

您的工作区必须位于客户管理的 VPC。
您的 Databricks 账户必须在企业订阅中。
您必须设置专用访问配置。

有关更多信息，请参阅 Databricks 文档中的 Azure Databricks：配置前端 PrivateLink (https://docs.databricks.com/aws/en/security/network/front-end/front-end-private-connect)。

注册 Snowflake VPC 端点

要注册 VPC 端点，请完成以下步骤：

在 Snowflake 中，调用 SYSTEM$GET_PRIVATELINK_ENDPOINTS_INFO 系统函数，然后复制响应中的 snowflake_endpoint_name：
```
SELECT SYSTEM$GET_PRIVATELINK_ENDPOINTS_INFO();
```
Copy
例如，要复制的输出应类似 vpce-11111aaaa11aaaa11。该值是 Snowflake 账户中的 VPC 端点 ID。
在 Databricks 中，通过指定上一步复制的 VPC 端点 ID 值来注册 Snowflake VPC 端点 ID。

有关说明，请参阅 Databricks 文档中的管理 VPC 端点注册 (https://docs.databricks.com/aws/en/security/network/classic/vpc-endpoints)。
在 Databricks 中，添加私有访问设置，然后指定您上一步注册的 VPC 端点。

有关说明，请参阅 Databricks 文档中的管理专用访问设置 (https://docs.databricks.com/aws/en/security/network/classic/private-access-settings)。

第 5 步：创建目录集成¶

在此步骤中，要启用专用连接，请为目录 REST 端点配置目录集成。

要配置此目录集成，请运行 CREATE CATALOG INTEGRATION 命令。

例如：

CREATE OR REPLACE CATALOG INTEGRATION iceberg_rest_catalog_cat_int_private
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = '<rest_api_endpoint_url>'
    CATALOG_API_TYPE = PRIVATE
    CATALOG_NAME = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = '<token_server_uri>'
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
)
ENABLED = true;

Copy

重要

要使用出站专用连接，您必须在创建集成时指定 CATALOG_API_TYPE=PRIVATE。

有关更多信息，包括支持的身份验证方法，请参阅 CREATE CATALOG INTEGRATION (Apache Iceberg™ REST)。

要配置此目录集成，请按照为 AWS Glue Iceberg REST 配置目录集成中的步骤操作。

重要

要使用出站专用连接，您必须在创建集成时指定 CATALOG_API_TYPE = AWS_PRIVATE_GLUE，而不是 CATALOG_API_TYPE = AWS_GLUE。

例如：

CREATE CATALOG INTEGRATION glue_rest_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'
    CATALOG_API_TYPE = AWS_PRIVATE_GLUE
    CATALOG_NAME = '123456789012'
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my-role'
    SIGV4_SIGNING_REGION = 'us-west-2'
  )
  ENABLED = TRUE;

Copy

要创建用于连接 Databricks Unity Catalog 的 REST 目录集成，请使用 CREATE CATALOG INTEGRATION (Apache Iceberg™ REST) 命令。
重要
- 要使用出站私有连接，您必须在创建集成时将 CATALOG_API_TYPE = PRIVATE 指定为 REST_CONFIG 参数之一。
- 对于 CATALOG_URI 和 OAUTH_TOKEN_URI，您必须使用标准公共主机名，即您的 Databricks 工作区 URL，而不是专用端点的名称。当 CATALOG_API_TYPE 设置为 PRIVATE 时，Snowflake 会自动通过已配置的专用端点路由流量。要查找 Databricks 工作区 URL，请参阅 Databricks 文档中的获取工作区对象的标识符 (https://docs.databricks.com/aws/en/workspace/workspace-details)。
示例：持有者令牌身份验证

要创建持有者令牌（在 Databricks 中称为个人访问令牌 (PAT)），请参阅 Databricks 文档中的 AWS 上的 Databricks：为工作区用户创建个人访问令牌 (https://docs.databricks.com/aws/en/dev-tools/auth/pat#create-personal-access-tokens-for-workspace-users)。
```
CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_private_pat
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://dbc-a1a11111-1a11.cloud.databricks.com/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<catalog_name>'
    CATALOG_API_TYPE = PRIVATE
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = 'eyAbCD...eyDeF...'
  )
  ENABLED = TRUE;
```
Copy
示例：使用服务主体进行 OAuth 身份验证

以下示例使用 Databricks 服务主体进行 OAuth 身份验证。您必须在 Databricks 中配置具有必要凭据的服务主体，即 client_id 和 client_secret。有关添加服务主体的说明，请参阅 Databricks 文档中的 AWS 上的 Databricks：将服务主体添加到您的账户 (https://docs.databricks.com/aws/en/admin/users-groups/manage-service-principals#-add-service-principals-to-your-account)。
```
USE ROLE ACCOUNTADMIN;

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_private_oauth
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_API_TYPE = PRIVATE
    CATALOG_URI = '<databricks_workspace_url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = '<databricks_workspace_url>/oidc/v1/token'
    OAUTH_CLIENT_ID = '<your_databricks_client_id>''
    OAUTH_CLIENT_SECRET = '<your_databricks_client_secret>'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;
```
Copy
其中：
- <databricks_workspace_url> 是您的 Databricks 工作区 URL，您在收集目录专用连接信息时已获取该值。例如，https://dbc-a1a11111-1a11.cloud.databricks.com 是 Databricks 工作区 URL。

要创建用于连接 Databricks Unity Catalog 的 REST 目录集成，请使用 CREATE CATALOG INTEGRATION (Apache Iceberg™ REST) 命令。
重要
- 要使用出站私有连接，您必须在创建集成时将 CATALOG_API_TYPE = PRIVATE 指定为 REST_CONFIG 参数之一。
- 对于 CATALOG_URI 和 OAUTH_TOKEN_URI，您必须使用标准公共主机名，即您的 Databricks 工作区 URL，而不是专用端点的名称。当 CATALOG_API_TYPE 设置为 PRIVATE 时，Snowflake 会自动通过已配置的专用端点路由流量。要查找 Databricks 工作区 URL，请参阅 Azure Databricks 文档中的确定每个工作区 URL (https://learn.microsoft.com/en-us/azure/databricks/workspace/workspace-details#determine-per-workspace-url)。
示例：持有者令牌身份验证

要创建持有者令牌（在 Databricks 中称为个人访问令牌 (PAT)），请参阅 Azure Databricks 文档中的 Azure Databricks：为工作区用户创建个人访问令牌 (https://learn.microsoft.com/en-us/azure/databricks/dev-tools/auth/pat#create-personal-access-tokens-for-workspace-users)。
```
CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_private_pat
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://my-workspace.azuredatabricks.net/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<catalog_name>'
    CATALOG_API_TYPE = PRIVATE
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = 'eyAbCD...eyDeF...'
  )
  ENABLED = TRUE;
```
Copy
示例：使用服务主体进行 OAuth 身份验证

以下示例使用 Databricks 服务主体进行 OAuth 身份验证。您必须在 Databricks 中配置具有必要凭据的服务主体，即 client_id 和 client_secret。有关添加服务主体的说明，请参阅 Databricks 文档中的 Azure Databricks：将服务主体添加到您的账户 (https://learn.microsoft.com/en-us/azure/databricks/admin/users-groups/manage-service-principals#-add-service-principals-to-your-account)。
```
USE ROLE ACCOUNTADMIN;

CREATE OR REPLACE CATALOG INTEGRATION unity_catalog_int_private_oauth
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_API_TYPE = PRIVATE
    CATALOG_URI = '<databricks_per_workspace_url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<catalog_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = '<databricks_per_workspace_url>/oidc/v1/token'
    OAUTH_CLIENT_ID = '<your_databricks_client_id>'
    OAUTH_CLIENT_SECRET = '<your_databricks_client_secret>'
    OAUTH_ALLOWED_SCOPES = ('all-apis', 'sql')
  )
  ENABLED = TRUE;
```
Copy
其中：
- <databricks_per_workspace_url> 是您的每个 Databricks 工作区 URL，您在收集目录专用连接信息时已获取该值。例如，https://adb-1234567890123456.12.azuredatabricks.net 是每个 Databricks 工作区 URL。

第 6 步：验证目录集成¶

要验证目录集成配置，请调用 SYSTEM$VERIFY_CATALOG_INTEGRATION 函数。

For more information, including an example, see Use SYSTEM$VERIFY_CATALOG_INTEGRATION to check your catalog integration configuration.

（可选）第 7 步：更新目录配置¶

我们建议您更新远程目录的配置，以便只能通过专用连接访问。

要禁用目录的公共访问权限，请参阅您要通过专用连接访问的远程目录的相关文档。

后续步骤¶

本部分含配置目录集成后可以执行的一些任务：

监控您的专用连接端点¶

要监控专用连接端点，请参阅 ACCOUNT_USAGE 架构中的 OUTBOUND_PRIVATELINK_ENDPOINTS 视图。
要了解专用连接端点的成本，请参阅出站专用连接成本。

配置具有出站专用连接的外部卷¶

要在 Snowflake 和存储桶之间启用专用连接，请配置具有出站专用连接外部卷。

有关外部卷的更多信息，请参阅配置外部卷。

备注

配置具有出站专用连接的目录集成时，不支持目录提供的凭证。

要配置具有出站专用连接的外部卷，请按照云提供商的说明进行操作：
- AWS：Private connectivity to external volumes for Amazon Web Services
- Azure：Microsoft Azure 外部存储卷的专用连接

创建目录链接数据库¶

要创建连接到外部 Iceberg REST 目录的 Snowflake 数据库，请创建一个目录链接数据库。

有关更多信息，请参阅创建目录链接数据库。

备注

创建目录链接数据库时，请指定配置了出站专用连接的目录集成。

写入远程目录¶

为 Apache Iceberg™ REST 配置目录集成并创建目录链接数据库后，您即可向远程目录写入数据。