# 使用 Amazon S3 表类数据存储服务 Iceberg REST 端点访问表
您可以将 Iceberg REST 客户端连接到 Amazon S3 表类数据存储服务 Iceberg REST 端点，然后进行 REST API 调用来创建、更新或查询 S3 表存储桶中的表。该端点实现了 [Apache Iceberg REST Catalog Open API specification](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml) 中指定的一组标准化 Iceberg REST API。该端点的工作原理是将 Iceberg REST API 操作转换为相应的 S3 表类数据存储服务操作。
**注意**
Amazon S3 表类数据存储服务 Iceberg REST 端点可用于访问 AWS Partner Network（APN）目录实现或自定义目录实现中的表。如果您只需要对单个表存储桶具有基本的读/写访问权限，也可以使用它。对于其它访问场景，我们建议使用 AWS Glue Iceberg REST 端点来连接表，这可以提供统一的表管理、集中化的治理和精细的访问控制。有关更多信息，请参阅 [使用 AWS Glue Iceberg REST 端点访问 Amazon S3 表](s3-tables-integrating-glue-endpoint.md)。
## 配置端点
您可以使用服务端点连接到 Amazon S3 表类数据存储服务 Iceberg REST 端点。S3 表类数据存储服务 Iceberg REST 端点具有以下格式：
```
https://s3tables..amazonaws.com/iceberg
```
有关区域特定的端点，请参阅 [S3 表类数据存储服务 AWS 区域和端点](s3-tables-regions-quotas.md#s3-tables-regions)。
**目录配置属性**
当使用 Iceberg 客户端将分析引擎连接到服务端点时，必须在初始化目录时指定以下配置属性。将*占位符值*替换为您的区域和表存储桶的信息。
+ 作为端点 URI 的区域特定的端点：`https://s3tables..amazonaws.com/iceberg`
+ 作为仓库位置的表存储桶 ARN：`arn:aws:s3tables:::bucket/`
+ 用于身份验证的 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:::bucket/",
"uri": "https://s3tables..amazonaws.com/iceberg",
"rest.sigv4-enabled": "true",
"rest.signing-name": "s3tables",
"rest.signing-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..amazonaws.com/iceberg" \
--conf "spark.sql.catalog.spark_catalog.warehouse=arn:aws:s3tables:::bucket/" \
--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=" \
--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](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv.html)，以了解有关 AWS SigV4 的更多信息。
Amazon S3 表类数据存储服务 Iceberg REST 端点请求的 SigV4 签名名称为：`s3tables`
对 Amazon S3 表类数据存储服务 Iceberg REST 端点的请求使用与 REST API 操作对应 `s3tables` IAM 操作进行授权。这些权限可以在附加到表和表存储桶的基于 IAM 身份的策略或基于资源的策略中定义。有关更多信息，请参阅 [S3 表类数据存储服务的访问管理](s3-tables-setting-up.md)。
您可以使用 AWS CloudTrail 跟踪通过 REST 端点向表发出的请求。请求将记录为其相应的 S3 IAM 操作。例如，`LoadTable` API 将为 `GetTableMetadataLocation` 操作生成一个管理事件，并为 `GetTableData` 操作生成一个数据事件。有关更多信息，请参阅 [使用 AWS CloudTrail 对 S3 表类数据存储服务进行日志记录](s3-tables-logging.md)。
## 前缀和路径参数
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](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html) 操作来删除表。
+ 该端点仅支持标准的表元数据操作。要进行表维护，例如快照管理和压缩，请使用 S3 表类数据存储服务维护 API 操作。有关更多信息，请参阅 [S3 表类数据存储服务维护](s3-tables-maintenance-overview.md)。
****限制****
+ 不支持多级命名空间。
+ 不支持基于 OAuth 的身份验证。
+ 命名空间仅支持 `owner` 属性。
+ 不支持 [Apache Iceberg REST Open API specification](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml) 中定义的与视图相关的 API。
+ 不支持对 `metadata.json` 文件超过 50 MB 的表运行操作，否则将返回 `400 Bad Request` 错误。要控制 `metadata.json` 文件的大小，请使用表维护操作。有关更多信息，请参阅 [S3 表类数据存储服务维护](s3-tables-maintenance-overview.md)。