为 Apache Iceberg™ 表使用由目录分发的凭据

通过支持 Iceberg 表分发的凭据，您可以允许 Snowflake 访问云存储中的表数据和元数据，而无需使用 外部卷。

反之，您可以通过第三方 Iceberg REST 目录（如 Snowflake Open Catalog）配置和委托访问控制，然后在为分发的凭据配置的 Snowflake 中创建目录集成。对于与目录集成相关的任何 Iceberg 表，Snowflake 会使用由目录提供商分发的凭据安全地连接到您的外部云存储。

备注

对于使用 REST 目录集成 并在 Amazon S3 中存储文件的 外部管理的 Iceberg 表，支持使用由目录分发的凭据。要使用此功能，您的外部目录还必须支持凭据分发功能。

注意事项

在为 Iceberg 表使用由目录分发的凭据时，请考虑以下几点：

  • 只有在 Amazon S3 中存储数据和元数据的表才支持此功能。

  • 表文件必须存储在一个桶中，不能分散在多个桶中。

  • 使用 REST 目录配置的服务主体必须有权从包含桶中表文件的 所有 位置读取。

  • Snowflake 希望您的目录能为分发的凭据提供过期时间，并查找键值对，其中键是 expiration-time，值是以毫秒为单位指定过期时间的时间戳（例如，1730234407000）。

    如果您的目录没有提供过期时间，Snowflake 假定在收到后 60 分钟过期。

  • 如果目录提供的凭据无效，则表创建失败。

  • 不支持数据共享。

为分发的凭据创建目录集成

要为分发的凭据创建目录集成，请使用 CREATE CATALOG INTEGRATION (Apache Iceberg™ REST) 命令，并将 ACCESS_DELEGATION_MODE 参数设置为 VENDED_CREDENTIALS。

其中：

ACCESS_DELEGATION_MODE = {VENDED_CREDENTIALS | EXTERNAL_VOLUME_CREDENTIALS}

指定用于访问外部云存储中 Iceberg 表文件的访问授权模式。

  • VENDED_CREDENTIALS 指定 Snowflake 应使用分发的凭据。

  • EXTERNAL_VOLUME_CREDENTIALS 指定 Snowflake 应使用外部卷。

默认：EXTERNAL_VOLUME_CREDENTIALS

有关创建 REST 目录集成的更多信息，请参阅 为 Apache Iceberg™ REST 目录配置目录集成 或 为 Snowflake Open Catalog 配置目录集成。

示例：Snowflake Open Catalog

下面的示例使用分发的凭据为 Snowflake Open Catalog 创建目录集成：

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int_vended_credentials
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my-namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://myrestapi.com/polaris/api/catalog'
    CATALOG_NAME = 'my_catalog_name'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;
Copy

示例：SigV4 和 Amazon API Gateway

此示例创建了一个目录集成，使用 SigV4 身份验证和分发的凭据：

CREATE OR REPLACE CATALOG INTEGRATION my_rest_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://asdlkfjwoalk-execute-api.us-west-2-amazonaws.com/MyApiStage'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my_api_permissions_role'
  )
  ENABLED = TRUE;
Copy

示例：Amazon S3 表

此示例使用 Lake Formation 为 Amazon S3 表 (https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-tables.html) 创建目录集成，并启用了基于 SigV4 的凭据分发功能。

CREATE OR REPLACE CATALOG INTEGRATION my_s3_tables_catalog_integration
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'
    CATALOG_API_TYPE = AWS_GLUE
    CATALOG_NAME = '123456789012:S3tablescatalog/my_table_bucket'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my_api_permissions_role'
  )
  ENABLED = TRUE;
Copy

其中：

CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'

指定 AWS Glue Iceberg REST 端点 (https://docs.aws.amazon.com/glue/latest/dg/access_catalog.html#connect-glu-iceberg-rest)。

CATALOG_NAME = 'aws_account_id:s3tablescatalog/s3_table_bucket

在 AWS 账户中指定 S3 表桶。

创建一个使用分发的凭据的 Iceberg 表

使用第三方 Iceberg REST 目录设置访问控制，并为分发的凭据创建目录集成后，即可创建 Iceberg 表。

创建使用分发的凭据的 Iceberg 表时，您必须指定使用 ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS 配置的目录集成，并从 CREATE ICEBERG TABLE（Iceberg REST 目录） 语句中省略 EXTERNAL_VOLUME 参数。

例如：

CREATE ICEBERG TABLE my_iceberg_table
  CATALOG = open_catalog_int_vended_credentials
  CATALOG_TABLE_NAME = 'my_table';
Copy

备注

如果您在账户、数据库或架构级别设置默认外部卷，则只要您指定了配置为使用分发的凭据的目录集成，Snowflake 就会在表创建过程中忽略默认外部卷。

语言: 中文