使用 Amazon S3 表类数据存储服务 Iceberg REST 端点访问表

您可以将 Iceberg REST 客户端连接到 Amazon S3 表类数据存储服务 Iceberg REST 端点，然后进行 REST API 调用来创建、更新或查询 S3 表存储桶中的表。该端点实现了 Apache Iceberg REST Catalog Open API specification 中指定的一组标准化 Iceberg REST API。该端点的工作原理是将 Iceberg REST API 操作转换为相应的 S3 表类数据存储服务操作。

注意

Amazon S3 表类数据存储服务 Iceberg REST 端点可用于访问 AWS Partner Network（APN）目录实现或自定义目录实现中的表。如果您只需要对单个表存储桶具有基本的读/写访问权限，也可以使用它。对于其它访问场景，我们建议使用 AWS Glue Iceberg REST 端点来连接表，这可以提供统一的表管理、集中化的治理和精细的访问控制。有关更多信息，请参阅 使用 AWS GlueIceberg REST 端点访问 Amazon S3 表

配置端点

您可以使用服务端点连接到 Amazon S3 表类数据存储服务 Iceberg REST 端点。S3 表类数据存储服务 Iceberg REST 端点具有以下格式：

https://s3tables.<REGION>.amazonaws.com/iceberg

有关区域特定的端点，请参阅 S3 表类数据存储服务 AWS 区域和端点。

目录配置属性

当使用 Iceberg 客户端将分析引擎连接到服务端点时，必须在初始化目录时指定以下配置属性。将占位符值替换为您的区域和表存储桶的信息。

• 作为端点 URI 的区域特定的端点：https://s3tables.<REGION>.amazonaws.com/iceberg

• 作为仓库位置的表存储桶 ARN：arn:aws:s3tables:<region>:<accountID>:bucket/<bucketname>

• 用于身份验证的 Sigv4 属性。服务端点请求的 SigV4 签名名称为：s3tables

以下示例演示如何配置不同的客户端以使用 Amazon S3 表类数据存储服务 Iceberg REST 端点。

PyIceberg

要将 Amazon S3 表类数据存储服务 Iceberg REST 端点与 PyIceberg 结合使用，请指定以下应用程序配置属性：

rest_catalog = load_catalog(
  catalog_name,
  **{
    "type": "rest",    
    "warehouse":"arn:aws:s3tables:<Region>:<accountID>:bucket/<bucketname>",
    "uri": "https://s3tables.<Region>.amazonaws.com/iceberg",
    "rest.sigv4-enabled": "true",
    "rest.signing-name": "s3tables",
    "rest.signing-region": "<Region>"
  }
)                

Apache Spark

要将 Amazon S3 表类数据存储服务 Iceberg REST 端点与 Spark 结合使用，请指定以下应用程序配置属性，同时将占位符值替换为您的区域和表存储桶的信息。

spark-shell \
  --packages "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.4.1,software.amazon.awssdk:bundle:2.20.160,software.amazon.awssdk:url-connection-client:2.20.160" \
  --master "local[*]" \
  --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
  --conf "spark.sql.defaultCatalog=spark_catalog" \
   --conf "spark.sql.catalog.spark_catalog=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.spark_catalog.type=rest" \
  --conf "spark.sql.catalog.spark_catalog.uri=https://s3tables.<Region>.amazonaws.com/iceberg" \
  --conf "spark.sql.catalog.spark_catalog.warehouse=arn:aws:s3tables:<Region>:<accountID>:bucket/<bucketname>" \
  --conf "spark.sql.catalog.spark_catalog.rest.sigv4-enabled=true" \
  --conf "spark.sql.catalog.spark_catalog.rest.signing-name=s3tables" \
  --conf "spark.sql.catalog.spark_catalog.rest.signing-region=<Region>" \
  --conf "spark.sql.catalog.spark_catalog.io-impl=org.apache.iceberg.aws.s3.S3FileIO" \
  --conf "spark.hadoop.fs.s3a.aws.credentials.provider=org.apache.hadoop.fs.s3a.SimpleAWSCredentialProvider" \
  --conf "spark.sql.catalog.spark_catalog.rest-metrics-reporting-enabled=false"               

对访问端点进行身份验证和授权

对 S3 表类数据存储服务的服务端点的 API 请求使用 AWS 签名版本 4（SigV4）进行身份验证。请参阅适用于 API 请求的 AWS 签名版本 4，以了解有关 AWS SigV4 的更多信息。

Amazon S3 表类数据存储服务 Iceberg REST 端点请求的 SigV4 签名名称为：s3tables

对 Amazon S3 表类数据存储服务 Iceberg REST 端点的请求使用与 REST API 操作对应 s3tables IAM 操作进行授权。这些权限可以在附加到表和表存储桶的基于 IAM 身份的策略或基于资源的策略中定义。有关更多信息，请参阅 S3 表类数据存储服务的访问管理。

您可以使用 AWS CloudTrail 跟踪通过 REST 端点向表发出的请求。请求将记录为其相应的 S3 IAM 操作。例如，LoadTable API 将为 GetTableMetadataLocation 操作生成一个管理事件，并为 GetTableData 操作生成一个数据事件。有关更多信息，请参阅 使用 AWS CloudTrail 对 S3 表类数据存储服务进行日志记录。

前缀和路径参数

Iceberg REST 目录 API 在其请求 URL 中有一个自由格式前缀。例如，ListNamespaces API 调用使用 GET/v1/{prefix}/namespaces URL 格式。对于 S3 表类数据存储服务，REST 路径 {prefix} 始终是 url 编码的表存储桶 ARN。

例如，对于以下表存储桶 ARN：arn:aws:s3tables:us-east-1:111122223333:bucket/bucketname，前缀应为：arn%3Aaws%3As3tables%3Aus-east-1%3A111122223333%3Abucket%2Fbucketname

命名空间路径参数

Iceberg REST 目录 API 路径中的命名空间可以有多级。但是，S3 表类数据存储服务仅支持单级命名空间。要访问多级目录层次结构中的命名空间，您可以在引用命名空间时连接到命名空间之上的多级目录。与使用多级命名空间相比，这可让任何支持 catalog.namespace.table 三部分表示法的查询引擎访问 S3 表类数据存储服务的目录层次结构中的对象，而不会出现兼容性问题。

支持的 Iceberg REST API 操作

下表包含支持的 Iceberg REST API 以及它们与 S3 表类数据存储服务操作的对应关系。

Iceberg REST 操作	REST 路径	S3 表类数据存储服务 IAM 操作	CloudTrail EventName
getConfig	GET /v1/config	s3tables:GetTableBucket	s3tables:GetTableBucket
listNamespaces	GET /v1/{prefix}/namespaces	s3tables:ListNamespaces	s3tables:ListNamespaces
createNamespace	POST /v1/{prefix}/namespaces	s3tables:CreateNamespace	s3tables:CreateNamespace
loadNamespaceMetadata	GET /v1/{prefix}/namespaces/{namespace}	s3tables:GetNamespace	s3tables:GetNamespace
dropNamespace	DELETE /v1/{prefix}/namespaces/{namespace}	s3tables:DeleteNamespace	s3tables:DeleteNamespace
listTables	GET /v1/{prefix}/namespaces/{namespace}/tables	s3tables:ListTables	s3tables:ListTables
createTable	POST /v1/{prefix}/namespaces/{namespace}/tables	s3tables:CreateTable, s3tables:PutTableData	s3tables:CreateTable, s3tables:PutObject
loadTable	GET /v1/{prefix}/namespaces/{namespace}/tables/{table}	s3tables:GetTableMetadataLocation, s3tables:GetTableData	s3tables:GetTableMetadataLocation, s3tables:GetObject
updateTable	POST /v1/{prefix}/namespaces/{namespace}/tables/{table}	s3tables:UpdateTableMetadataLocation, s3tables:PutTableData, s3tables:GetTableData	s3tables:UpdateTableMetadataLocation, s3tables:PutObject, s3tables:GetObject
dropTable	DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}	s3tables:DeleteTable	s3tables:DeleteTable
renameTable	POST /v1/{prefix}/tables/rename	s3tables:RenameTable	s3tables:RenameTable
tableExists	HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}	s3tables:GetTable	s3tables:GetTable
namespaceExists	HEAD /v1/{prefix}/namespaces/{namespace}	s3tables:GetNamespace	s3tables:GetNamespace

注意事项和限制

以下是使用 Amazon S3 表类数据存储服务 Iceberg REST 端点时的注意事项和限制。

注意事项

• CreateTable API 行为：此操作不支持 stage-create 选项，此选项会导致 400 Bad Request 错误。这意味着无法使用 CREATE TABLE AS SELECT（CTAS）从查询结果创建表。

• DeleteTable API 行为：您只能删除启用了清除功能的表。不支持使用 purge=false 删除表，这会导致 400 Bad Request 错误。某些版本的 Spark 即使在运行 DROP TABLE PURGE 命令时也始终将此标志设置为 false。可以尝试使用 DROP TABLE PURGE 或使用 S3 表类数据存储服务 DeleteTable 操作来删除表。

• 该端点仅支持标准的表元数据操作。要进行表维护，例如快照管理和压缩，请使用 S3 表类数据存储服务维护 API 操作。有关更多信息，请参阅 S3 表类数据存储服务维护。

限制

• 不支持多级命名空间。

• 不支持基于 OAuth 的身份验证。

• 命名空间仅支持 owner 属性。

• 不支持 Apache Iceberg REST Open API specification 中定义的与视图相关的 API。

• 不支持对 metadata.json 文件超过 5 MB 的表运行操作，否则将返回 400 Bad Request 错误。要控制 metadata.json 文件的大小，请使用表维护操作。有关更多信息，请参阅 S3 表类数据存储服务维护。