# 使用 Amazon S3 表类数据存储服务和表存储桶
Amazon S3 表类数据存储服务提供针对分析工作负载进行优化的 S3 存储，其功能旨在持续提高查询性能并降低表的存储成本。S3 表类数据存储服务专为存储表数据而设计，例如每日购买交易、流传感器数据或广告展示次数。表数据以列和行表示数据，就像在数据库表中一样。
S3 表类数据存储服务中的数据存储在新的存储桶类型中：*表存储桶*，它将表存储为子资源。表存储桶支持以 Apache Iceberg 格式存储表。使用标准 SQL 语句，您可以通过支持 Iceberg 的查询引擎来查询表，例如 Amazon Athena、Amazon Redshift 和 Apache Spark。
**Topics**
+ [S3 表类数据存储服务的功能](#s3-tables-features)
+ [相关服务](#s3-tables-services)
+ [教程：S3 表类数据存储服务入门](s3-tables-getting-started.md)
+ [表存储桶](s3-tables-buckets.md)
+ [S3 表类数据存储服务维护](s3-tables-maintenance-overview.md)
+ [使用智能分层优化表成本](tables-intelligent-tiering.md)
+ [表命名空间](s3-tables-namespace.md)
+ [S3 表存储桶中的表](s3-tables-tables.md)
+ [访问表数据](s3-tables-access.md)
+ [使用 Apache Iceberg V3](working-with-apache-iceberg-v3.md)
+ [复制 S3 表](s3-tables-replication-tables.md)
+ [S3 表类数据存储服务 AWS 区域、端点和服务配额](s3-tables-regions-quotas.md)
+ [通过 IPv6 向 S3 表类数据存储服务发出请求](s3-tables-ipv6.md)
+ [S3 表类数据存储服务的安全性](s3-tables-security-overview.md)
+ [S3 表类数据存储服务的日志记录和监控](s3-tables-monitoring-overview.md)
## S3 表类数据存储服务的功能
**专为表设计的存储**
S3 表存储桶是专门为表设计的。与 S3 通用存储桶中的自行管理的表相比，表存储桶可提供更高的每秒事务数（TPS）和更好的查询吞吐量。表存储桶具有与其它 Amazon S3 存储桶类型相同的耐久性、可用性和可扩展性。
**对 Apache Iceberg 的内置支持**
表存储桶中的表以 [https://aws.amazon.com//what-is/apache-iceberg/](https://aws.amazon.com//what-is/apache-iceberg/) 格式存储。您可以在支持 Iceberg 的查询引擎中使用标准 SQL 查询这些表。Iceberg 具有多种优化查询性能的功能，包括架构演变和分区演进。
借助 Iceberg，您可以更改数据的组织方式，使其能够随着时间推移而演变，而无需重写查询或重建数据结构。Iceberg 旨在通过其对事务的支持来协助确保数据一致性和可靠性。为了有助于更正问题或执行时空旅行查询，您可以跟踪数据如何随时间变化和回滚到历史版本。
**自动表优化**
为了优化您的表以进行查询，S3 会持续执行自动维护操作，例如压缩、快照管理和未引用文件移除。这些操作通过将较小的对象压缩成更少、更大的文件来提高表性能。维护操作还可以通过清理未使用的对象来降低存储成本。这种自动维护通过减少对手动表维护的需求，大规模简化了数据湖的运营。对于每个表和表存储桶，您可以自定义维护配置。
**访问管理和安全性**
您可以在 AWS Organizations 中使用 AWS Identity and Access Management（IAM）和 [Service Control Policies](https://docs.aws.amazon.com//organizations/latest/userguide/orgs_manage_policies_scps.html) 来管理对表存储桶和单个表的访问权限。S3 表类数据存储服务使用的服务命名空间与 Amazon S3 不同：*s3tables* 命名空间。因此，可以专门为 S3 表类数据存储服务及其资源设计策略。可以设计策略来授予对单个表、表命名空间内的所有表或整个表存储桶的访问权限。所有 Amazon S3 屏蔽公共访问权限设置均始终为表存储桶启用，无法禁用。
**与 AWS 分析服务集成**
可以通过 S3 控制台自动将 Amazon S3 表存储桶与 Amazon SageMaker 智能湖仓集成。这种集成支持 AWS 分析服务通过 AWS Glue Data Catalog 自动发现和访问表数据。集成后，可以使用诸如 Amazon Athena、Amazon Redshift、Quick 等分析服务来处理您的表。有关集成工作原理的更多信息，请参阅[将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
## 相关服务
可以将以下 AWS 服务 与 S3 表类数据存储服务结合使用，来支持您的特定分析应用程序。
+ [https://docs.aws.amazon.com//athena/latest/ug/what-is.html](https://docs.aws.amazon.com//athena/latest/ug/what-is.html)：Athena 是一种交互式查询服务，可用于通过使用标准 SQL 直接分析 Amazon S3 中的数据。还可以使用 Athena，通过 Apache Spark 以交互方式运行数据分析，而无需规划、配置或管理资源。在 Athena 上运行 Apache Spark 应用程序时，您需要提交 Spark 代码以供处理并直接接收结果。
+ [https://docs.aws.amazon.com//glue/latest/dg/what-is-glue.html](https://docs.aws.amazon.com//glue/latest/dg/what-is-glue.html)：AWS Glue 是一项无服务器数据集成服务，可让您轻松发现、准备、移动和集成来自多个来源的数据。可以使用 AWS Glue 进行分析、机器学习（ML）和应用程序开发。AWS Glue 还包括用于编写、运行任务和实施业务工作流程的额外生产率和数据操作工具。
+ [https://docs.aws.amazon.com//sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html](https://docs.aws.amazon.com//sagemaker-unified-studio/latest/userguide/what-is-sagemaker-unified-studio.html)：SageMaker 融通式合作开发工作室提供了集成的分析和 AI 体验，并支持统一访问您的所有数据。使用熟悉的 AWS 工具（用于 SQL 分析、数据处理、模型开发和生成式人工智能）在 SageMaker 融通式合作开发工作室中进行协作和构建，并通过 [Amazon Q 开发者版](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/what-is.html)提高效率。
+ [https://docs.aws.amazon.com//emr/latest/ManagementGuide/emr-what-is-emr.html](https://docs.aws.amazon.com//emr/latest/ManagementGuide/emr-what-is-emr.html)：Amazon EMR 是一个托管式集群平台，可简化在 AWS 上运行大数据框架（如 Apache Hadoop 和 Apache Spark）来处理和分析海量数据的过程。
+ [https://docs.aws.amazon.com//redshift/latest/mgmt/welcome.html](https://docs.aws.amazon.com//redshift/latest/mgmt/welcome.html)：Amazon Redshift 是一项 PB 级云中数据仓库服务。可以使用 Amazon Redshift Serverless 来访问和分析数据，而无需对预置数据仓库执行所有配置操作。系统将自动预置资源，数据仓库的容量会智能扩展，即使面对要求最为苛刻且不可预测的工作负载也能提供高速性能。数据仓库空闲时不会产生费用，您只需为实际使用的资源付费。您可以在 Amazon Redshift 查询编辑器 v2 或您最喜欢的商业智能（BI，Business Intelligence）工具中，直接加载数据并开始查询。
+ [https://docs.aws.amazon.com//quicksight/latest/user/welcome.html](https://docs.aws.amazon.com//quicksight/latest/user/welcome.html)：Quick 是一项业务分析服务，可用于构建可视化内容，执行临时分析，并快速从您的数据中获得业务见解。Quick 无缝地发现 AWS 数据来源，并通过使用 Quick 超快、并行、内存、计算引擎（SPICE）提供快速的响应式查询性能。
+ [https://docs.aws.amazon.com//lake-formation/latest/dg/what-is-lake-formation.html.html](https://docs.aws.amazon.com//lake-formation/latest/dg/what-is-lake-formation.html.html)：Lake Formation 是一项托管式服务，可简化设置、保护和管理数据湖的流程。Lake Formation 可帮助您探索数据来源，然后对数据进行编目、清理和转换。借助 Lake Formation，可以对 Amazon S3 上的数据湖数据及其在 AWS Glue Data Catalog 中的元数据进行精细访问控制。
# 教程：S3 表类数据存储服务入门
在本教程中，您将创建一个表存储桶，并将您区域中的表存储桶与 AWS 分析服务集成。接下来，您将使用 AWS CLI 在表存储桶中创建第一个命名空间和表。然后，您可以使用 AWS Lake Formation 授予对表的权限，这样您就可以开始使用 Athena 查询表了。
**提示**
如果您要将表格数据从通用存储桶迁移到表存储桶，AWS 解决方案库提供了指导性解决方案来为您提供助力。此解决方案通过将 AWS Step Functions 和 Amazon EMR 与 Apache Spark 结合使用，自动将在 AWS Glue Data Catalog 中注册并存储在通用存储桶中的 Apache Iceberg 和 Apache Hive 表移到表存储桶。有关更多信息，请参阅 AWS 解决方案库中的[将表格数据从 Amazon S3 迁移到 S3 表的指南](https://aws.amazon.com/solutions/guidance/migrating-tabular-data-from-amazon-s3-to-s3-tables/)。
**Topics**
+ [步骤 1：创建表存储桶并将其与 AWS 分析服务集成](#s1-tables-tutorial-create-bucket)
+ [步骤 2：创建表命名空间和表](#s2-tables-tutorial-create-namespace-and-table)
+ [（可选）步骤 3：授予对表的 Lake Formation 权限](#s3-tables-tutorial-create-table)
+ [步骤 4：在 Athena 中使用 SQL 查询数据](#s4-query-tables)
## 步骤 1：创建表存储桶并将其与 AWS 分析服务集成
在此步骤中，您使用 Amazon S3 控制台来创建第一个表存储桶。有关创建表存储桶的其它方法，请参阅 [Creating a table bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-buckets-create.html)。
**注意**
默认情况下，Amazon S3 控制台会自动将表存储桶与 Amazon SageMaker 智能湖仓集成，从而支持 AWS 分析服务自动发现和访问您的 S3 表类数据存储服务数据。如果您使用 AWS Command Line Interface（AWS CLI）、AWS SDK 或 REST API 以编程方式创建第一个表存储桶，则必须手动完成 AWS 分析服务集成。有关更多信息，请参阅 [将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在页面顶部的导航栏中，选择当前所显示 AWS 区域的名称。接下来，选择要在其中创建表存储桶的区域。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择**创建表存储桶**。
1. 在**常规配置**下，输入表存储桶的名称。
表存储桶名称必须满足以下要求：
+ 在当前区域中对于您的 AWS 账户是唯一的。
+ 长度必须介于 3 到 63 个字符之间。
+ 只能由小写字母、数字和连字符 (`-`) 组成。
+ 以字母或数字开头和结尾。
创建表存储桶后，便无法更改其名称。创建表存储桶的 AWS 账户拥有该存储桶。有关命名表存储桶的更多信息，请参阅[表存储桶命名规则](s3-tables-buckets-naming.md#table-buckets-naming-rules)。
1. 在**与 AWS 分析服务集成**部分中，确保选中**启用集成**复选框。
如果在使用控制台创建第一个表存储桶时选择了**启用集成**，则 Amazon S3 会尝试将表存储桶与 AWS 分析服务集成。这种集成可让您使用 AWS 分析服务来访问当前区域中的所有表。有关更多信息，请参阅 [将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
1. 选择 **创建存储桶 **。
## 步骤 2：创建表命名空间和表
对于此步骤，可以在表存储桶中创建一个命名空间，然后在该命名空间下创建一个新表。可以使用控制台或 AWS CLI 创建表命名空间和表。
**重要**
创建表时，请确保在表名称和表定义中全部使用小写字母。例如，请确保列名称全部为小写。如果表名称或表定义包含大写字母，则 AWS Lake Formation 或 AWS Glue Data Catalog 不支持该表。在这种情况下，Amazon Athena 等 AWS 分析服务将无法看到您的表，即使表存储桶与 AWS 分析服务集成，也不例外。
如果表定义包含大写字母，则在 Athena 中运行 `SELECT` 查询时会收到以下错误消息：“GENERIC\$1INTERNAL\$1ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names.”
### 使用 S3 控制台和 Amazon Athena
以下过程使用 Amazon S3 控制台通过 Amazon Athena 来创建命名空间和表。
**创建表命名空间和表**
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在**表存储桶**页面上，选择要在其中创建表的表存储桶。
1. 在表存储桶详细信息页面上，选择**使用 Athena 创建表**。
1. 在**使用 Athena 创建表**对话框中，选择**创建命名空间**，然后在**命名空间名称**字段中输入名称。命名空间名称必须为 1 到 255 个字符，并且在表存储桶中是唯一的。有效字符为 a–z、0–9 和下划线 (`_`)。命名空间名称的开头不支持使用下划线。
1. 选择**创建命名空间**。
1. 选择**使用 Athena 创建表**。
1. Amazon Athena 控制台将打开，并出现 Athena 查询编辑器。查询编辑器中填充了一个可用于创建表的示例查询。修改此查询，以指定您希望表具有的表名称和列。
1. 修改完查询后，选择**运行**来创建表。
如果表创建取得成功，则新表的名称将显示在 Athena 中的表列表中。当您导航回 Amazon S3 控制台时，刷新列表后，新表将出现在表存储桶的详细信息页面上的**表**列表中。
### 使用 AWS CLI
要使用以下 AWS CLI 示例命令在表存储桶中创建命名空间，然后在该命名空间下使用架构创建新表，请将 `user input placeholder` 值替换为您自己的值。
**先决条件**
+ 将 [https://docs.aws.amazon.com//aws-managed-policy/latest/reference/AmazonS3TablesFullAccess.html](https://docs.aws.amazon.com//aws-managed-policy/latest/reference/AmazonS3TablesFullAccess.html) 策略附加到您的 IAM 身份。
+ 安装 AWS CLI 版本 2.23.10 或更高版本。有关更多信息，请参阅《AWS Command Line Interface 用户指南》**中的[安装或更新最新版本的 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
1. 通过运行以下命令，在表存储桶中创建新的命名空间：
```
aws s3tables create-namespace \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--namespace my_namespace
```
1. 通过运行以下命令，确认您的命名空间已成功创建：
```
aws s3tables list-namespaces \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket
```
1. 通过运行以下命令，使用表架构创建新表：
```
aws s3tables create-table --cli-input-json file://mytabledefinition.json
```
对于 `mytabledefinition.json` 文件，请使用以下示例表定义：
```
{
"tableBucketARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket",
"namespace": "my_namespace",
"name": "my_table",
"format": "ICEBERG",
"metadata": {
"iceberg": {
"schema": {
"fields": [
{"name": "id", "type": "int","required": true},
{"name": "name", "type": "string"},
{"name": "value", "type": "int"}
]
}
}
}
}
```
## （可选）步骤 3：授予对表的 Lake Formation 权限
对于此步骤，请向其它 IAM 主体授予对新表的 Lake Formation 权限。这些权限可让除您之外的其它主体使用 Athena 和其它 AWS 分析服务来访问表存储桶资源。有关更多信息，请参阅 [授予对表或数据库的 Lake Formation 权限](grant-permissions-tables.md#grant-lf-table)。如果您是唯一将访问表的用户，则可以跳过此步骤。
1. 打开 AWS Lake Formation 控制台（网址为 [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/)），并以数据湖管理员身份登录。有关如何创建数据湖管理员的更多信息，请参阅 [Create a data lake administrator](https://docs.aws.amazon.com/lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)。
1. 在导航窗格中，选择**数据权限**，然后选择**授予**。
1. 在**授予权限**页面的**主体**下，选择 **IAM 用户和角色**，然后选择您要支持对表运行查询的 IAM 用户或角色。
1. 在 **LF 标签或目录资源**下，选择**命名 Data Catalog 资源**。
1. 根据您是要授予对账户中所有表的访问权限，还是只想授予对您创建的表存储桶中资源的访问权限，执行以下操作之一：
+ 对于**目录**，选择您在集成表存储桶时创建的账户级目录。例如 `111122223333:s3tablescatalog`。
+ 对于**目录**，为表存储桶选择子目录。例如 `111122223333:s3tablescatalog/amzn-s3-demo-table-bucket`。
1. （可选）如果您为表存储桶选择了子目录，请执行以下一项或两项操作：
+ 对于**数据库**，选择您创建的表存储桶命名空间。
+ 对于**表**，请选择您在表存储桶中创建的表，或选择**所有表**。
1. 根据您选择的是目录还是子目录，以及随后选择的是数据库还是表，您可以在目录级别、数据库级别或表级别设置权限。有关 Lake Formation 权限的更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Managing Lake Formation permissions](https://docs.aws.amazon.com/lake-formation/latest/dg/managing-permissions.html)。
请执行以下操作之一：
+ 对于**目录权限**，请选择 **Super** 来向另一个主体授予对目录的所有权限，或者选择更精细的权限，例如**描述**。
+ 对于**数据库权限**，您不能选择 **Super** 来向另一个主体授予对数据库的所有权限。而是应选择更精细的权限，例如**描述**。
+ 对于**表权限**，请选择 **Super** 来向另一个主体授予对表的所有权限，或者选择更精细的权限，例如**选择**或**描述**。
**注意**
当您将对数据目录资源的 Lake Formation 权限授予外部账户或直接授予其他账户中的 IAM 主体时，Lake Formation 会使用 AWS Resource Access Manager (AWS RAM) 服务共享该资源。如果被授权者账户与授予者账户在同一个组织中，则被授权者立即可以使用共享资源。如果被授权者账户不在同一个组织中，则 AWS RAM 会向被授权者账户发送邀请，以便其接受或拒绝资源授权。然后，要使共享资源可用，被授权者账户中的数据湖管理员必须使用 AWS RAM 控制台或 AWS CLI 接受邀请。有关跨账户数据共享的更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Cross-account data sharing in Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/cross-account-permissions.html)。
1. 选择**授权**。
## 步骤 4：在 Athena 中使用 SQL 查询数据
可以在 Athena 中使用 SQL 查询表。Athena 对于 S3 表类数据存储服务支持数据定义语言（DDL）、数据操作语言（DML）和数据查询语言（DQL）查询。
您可以从 Amazon S3 控制台或通过 Amazon Athena 控制台访问 Athena 查询。
### 使用 S3 控制台和 Amazon Athena
以下过程使用 Amazon S3 控制台访问 Athena 查询编辑器，以便您可以使用 Amazon Athena 查询表。
**查询表**
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在**表存储桶**页面上，选择包含要查询的表的表存储桶。
1. 在表存储桶详细信息页面上，选择要查询的表名称旁边的选项按钮。
1. 选择**使用 Athena 查询表**。
1. Amazon Athena 控制台打开，Athena 查询编辑器随即出现，其中包含为您加载的示例 `SELECT` 查询。根据您的用例需要修改此查询。
1. 要运行查询，请选择 **Run**（运行）。
### 使用 Amazon Athena 控制台
**查询表**
1. 从 [https://console.aws.amazon.com/athena/](https://console.aws.amazon.com/athena/home) 打开 Athena 控制台。
1. 查询表。下面是您可以修改的示例查询。确保将 `user input placeholders` 替换为您自己的信息。
```
SELECT * FROM "s3tablescatalog/amzn-s3-demo-table-bucket"."my_namespace"."my_table" LIMIT 10
```
1. 要运行查询，请选择 **Run**（运行）。
# 表存储桶
Amazon S3 表存储桶是一种 S3 存储桶类型，可用于创建表并将其存储为 S3 资源。表存储桶用于将表数据和元数据存储为对象，以便在分析工作负载中使用。S3 会自动在表存储桶中执行维护，有助于降低表存储成本。有关更多信息，请参阅 [S3 表类数据存储服务维护](s3-tables-maintenance-overview.md)。
要与存储在表存储桶中的表进行交互，可以将表存储桶与支持 [Apache Iceberg](https://iceberg.apache.org/docs/latest/) 的分析应用程序集成。表存储桶通过 AWS Glue Data Catalog 与 AWS 分析服务集成。有关更多信息，请参阅 [将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。还可以使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录，通过开源查询引擎与表进行交互。有关更多信息，请参阅 [使用 Amazon S3 表类数据存储服务 Iceberg REST 端点访问表](s3-tables-integrating-open-source.md)。
每个表存储桶都有一个唯一的 Amazon 资源名称（ARN）和附加到它的资源策略。表存储桶 ARN 采用以下格式：
```
arn:aws:s3tables:Region:OwnerAccountID:bucket/bucket-name
```
所有表存储桶和表都是私有的，不能使之成为公有的。只有被明确授予访问权限的用户才可以访问这些资源。要授予访问权限，您可以对表存储桶和表使用基于 IAM 资源的策略，并对用户和角色使用基于 IAM 身份的策略。
默认情况下，您可以在 AWS 账户中为每个 AWS 区域创建最多 10 个表存储桶。要请求增加表存储桶或表的配额，请联系 [支持](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)。
## 表存储桶的类型
Amazon S3 支持以下类型的表存储桶：
**客户管理的表存储桶**
客户管理的表存储桶是用于存储客户创建和管理的 Amazon S3 表的资源。可以显式创建这些存储桶，选择其名称，并保持对其中的表和命名空间的完全控制权。对于客户管理的表存储桶，可以根据需要创建、删除、设置自定义默认加密或配置维护选项。
**AWS 托管式表存储桶**
AWS 托管式表存储桶是自动存储由 AWS 服务创建的表的 AWS 托管式资源，例如 S3 元数据创建的实时清单表和日记表。这些存储桶为所有系统生成的表提供了一个集中位置。这些存储桶遵循标准命名约定，对所有表使用标准命名空间，并具有预设的维护和默认加密配置，S3 会代表您修改这些配置。您拥有查询数据的只读权限，而 AWS 处理所有表创建、更新和维护操作。有关更多信息，请参阅 [使用 AWS 托管式表存储桶](s3-tables-aws-managed-buckets.md)。
Amazon S3 存储桶有几种类型。在创建存储桶之前，请确保选择最适合应用程序和性能要求的存储桶类型。有关各种存储桶类型以及每种类型的相应用例的更多信息，请参阅[桶](Welcome.md#BasicsBucket)。
**Topics**
+ [表存储桶的类型](#s3-tables-buckets-types)
+ [Amazon S3 表存储桶、表和命名空间命名规则](s3-tables-buckets-naming.md)
+ [创建表存储桶](s3-tables-buckets-create.md)
+ [删除表存储桶](s3-tables-buckets-delete.md)
+ [查看有关 Amazon S3 表存储桶的详细信息](s3-tables-buckets-details.md)
+ [管理表存储桶策略](s3-tables-bucket-policy.md)
+ [使用 AWS 托管式表存储桶](s3-tables-aws-managed-buckets.md)
+ [将标签与 S3 表存储桶结合使用](table-bucket-tagging.md)
# Amazon S3 表存储桶、表和命名空间命名规则
创建表存储桶时，您选择存储桶名称和 AWS 区域，该名称在所选区域中对于您的账户必须是唯一的。创建表存储桶后，无法更改存储桶名称或区域。表存储桶名称必须遵循特定的命名规则。有关表存储桶及其中的表和命名空间的命名规则的更多信息，请参阅以下主题。
**Topics**
+ [表存储桶命名规则](#table-buckets-naming-rules)
+ [表和命名空间的命名规则](#naming-rules-table)
## 表存储桶命名规则
创建 Amazon S3 表存储桶时，需要指定表存储桶名称。与其它存储桶类型一样，无法重命名表存储桶。与其它存储桶类型不同，表存储桶不在全局命名空间中，因此，您账户中的每个存储桶名称只需要在当前 AWS 区域内保持唯一即可。
有关通用存储桶命名规则，请参阅[通用存储桶命名规则](bucketnamingrules.md)。有关目录存储桶命名规则的信息，请参阅[目录存储桶命名规则](directory-bucket-naming-rules.md)。
以下命名规则适用于表存储桶。
+ 存储桶名称必须介于 3 到 63 个字符之间。
+ 存储桶名称只能由小写字母、数字和连字符 (`-`) 组成。
+ 存储桶名称必须以字母或数字开头和结尾。
+ 存储桶名称不得包含任何下划线 (`_`) 或句点 (`.`)。
+ 存储桶名称不得以下面的任何保留前缀开头：
+ `xn--`
+ `sthree-`
+ `amzn-s3-demo-`
+ `aws`
+ 存储桶名称不得以下面的任何保留后缀结尾：
+ `-s3alias`
+ `--ol-s3`
+ `--x-s3`
+ `--table-s3`
## 表和命名空间的命名规则
以下命名规则适用于表存储桶中的表和命名空间：
+ 名称长度必须介于 1 到 255 个字符之间。
+ 名称只能由小写字母、数字和下划线 (`_`) 组成。
+ 名称必须以字母或数字开头。
+ 名称不得包含连字符 (`-`) 或句点 (`.`)。
+ 表名称在命名空间内必须是唯一的。
+ 命名空间在表存储桶中必须是唯一的。
+ 命名空间名称不得以保留前缀 `aws` 开头。
**重要**
创建表时，请确保在表名称和表定义中全部使用小写字母。例如，请确保列名称全部为小写。如果表名称或表定义包含大写字母，则 AWS Lake Formation 或 AWS Glue Data Catalog 不支持该表。在这种情况下，Amazon Athena 等 AWS 分析服务将无法看到您的表，即使表存储桶与 AWS 分析服务集成，也不例外。
如果表定义包含大写字母，则在 Athena 中运行 `SELECT` 查询时会收到以下错误消息：“GENERIC\$1INTERNAL\$1ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names.”
# 创建表存储桶
Amazon S3 表存储桶是一种 S3 存储桶类型，可用于创建表并将其存储为 S3 资源。要开始使用 S3 表类数据存储服务，您需要创建一个用于存储和管理表的表存储桶。创建表存储桶时，请选择存储桶名称和 AWS 区域。表存储桶名称在所选区域中对于您的账户必须是唯一的。创建表存储桶后，无法更改存储桶名称或区域。有关命名表存储桶的信息，请参阅 [Amazon S3 表存储桶、表和命名空间命名规则](s3-tables-buckets-naming.md)。
表存储桶具有以下 Amazon 资源名称（ARN）格式：
```
arn:aws:s3tables:region:owner-account-id:bucket/bucket-name
```
默认情况下，可以在 AWS 账户中为每个区域创建最多 10 个表存储桶。要请求增加表存储桶或表的配额，请联系 [支持](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)。
创建表存储桶时，可以为其指定加密类型，该加密类型将用于加密您在该存储桶中创建的表。有关存储桶加密选项的更多信息，请参阅[使用加密保护 S3 表数据](s3-tables-encryption.md)。
**创建表存储桶的先决条件**
要创建表存储桶，首先必须执行以下操作：
+ 确保您对 `s3tables:CreateTableBucket` 拥有 AWS Identity and Access Management（IAM）权限。
**注意**
如果您选择 SSE-KMS 作为默认加密类型，则必须对 `s3tables:PutTableBucketEncryption` 拥有权限，并且对所选 AWS KMS 密钥具有 `DescribeKey` 权限。此外，您使用的 AWS KMS 密钥需要向 S3 表类数据存储服务授予执行自动表维护的权限。有关更多信息，请参阅 [S3 表类数据存储服务 SSE-KMS 加密的权限要求](s3-tables-kms-permissions.md)。
要创建表存储桶，可以使用 Amazon S3 控制台、Amazon S3 REST API、AWS Command Line Interface（AWS CLI）或 AWS SDK。
## 使用 S3 控制台
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在页面顶部的导航栏中，选择当前所显示 AWS 区域的名称。接下来，选择要在其中创建存储桶的区域。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择**创建表存储桶**以打开**创建表存储桶**页面。
1. 在**属性**下，输入表存储桶的名称。
表存储桶名称必须满足以下要求：
+ 在当前区域中对于您的账户是唯一的。
+ 长度介于 3 到 63 个字符之间。
+ 只能由小写字母、数字和连字符（-）组成。
+ 以字母或数字开头和结尾。
创建存储桶后，便无法更改其名称。创建存储桶的 AWS 账户 拥有该存储桶。有关命名表存储桶的信息，请参阅 [Amazon S3 表存储桶、表和命名空间命名规则](s3-tables-buckets-naming.md)。
1. 如果要将表存储桶与 AWS 分析服务集成，请确保在**与 AWS 分析服务集成**下选择**启用集成**。
**注意**
当您使用控制台并且选择了**启用集成**选项来创建第一个表存储桶时，Amazon S3 会尝试自动将您的表存储桶与 AWS 分析服务集成。这种集成可让您使用 AWS 分析服务来查询当前区域中的所有表。有关更多信息，请参阅 [将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
1. 要配置默认加密，请在**加密类型**下，选择以下选项之一：
+ **具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3）**
+ **具有 AWS Key Management Service 密钥的服务器端加密（SSE-KMS）**
有关表数据的加密选项的更多信息，请参阅[使用加密保护 S3 表数据](s3-tables-encryption.md)。
1. 选择**创建存储桶**。
## 使用 AWS CLI
此示例说明如何使用 AWS CLI 创建表存储桶。要使用此示例，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables create-table-bucket \
--region us-east-2 \
--name amzn-s3-demo-bucket1
```
默认情况下，S3 表存储桶使用 SSE-S3 作为其默认加密设置，但是，您可以使用可选的 `--encryption-configuration` 参数来指定不同的加密类型。以下示例说明如何创建使用 SSE-KMS 加密的存储桶。有关表存储桶的加密设置的更多信息，请参阅[使用加密保护 S3 表数据](s3-tables-encryption.md)。
```
aws s3tables create-table-bucket \
--region us-east-2 \
--name amzn-s3-demo-bucket1
--encryption-configuration '{
"sseAlgorithm": "aws:kms",
"kmsKeyArn": "arn:aws:kms:Region:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" }'
```
# 删除表存储桶
您可以使用 Amazon S3 API、AWS Command Line Interface 或 AWS SDK 来删除表存储桶。在删除表存储桶之前，必须首先删除该存储桶中的所有命名空间和表。
**重要**
删除表存储桶时，您需要了解以下事项：
存储桶删除是永久性的，无法撤消。
与存储桶关联的所有数据和配置都将永久丢失。
## 使用 AWS CLI
此示例说明如何使用 AWS CLI 删除表存储桶。要使用此示例，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables delete-table-bucket \
--region us-east-2 \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1
```
# 查看有关 Amazon S3 表存储桶的详细信息
您可以在控制台中或以编程方式查看 Amazon S3 表存储桶的一般详细信息，例如存储桶拥有者和类型。您可以使用 S3 表类数据存储服务 REST API、AWS CLI 或 AWS SDK，以编程方式查看默认加密设置和维护设置。
## 查看表存储桶详细信息
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 获取有关表存储桶的详细信息。要使用此示例，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables get-table-bucket --table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket
```
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择表存储桶。
1. 选择**属性**选项卡。
## 查看表存储桶加密设置
有关表存储桶加密的更多信息，请参阅[在表存储桶中使用具有 AWS KMS 密钥的服务器端加密（SSE-KMS）](s3-tables-kms-encryption.md)。
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 来获取有关表存储桶的加密设置的详细信息。要使用此示例，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables get-table-bucket-encryption --table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket
```
## 查看表存储桶维护配置
有关维护设置的信息，请参阅[表存储桶的维护](s3-table-buckets-maintenance.md)
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 获取有关表存储桶的维护配置设置的详细信息。要使用此示例，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables get-table-bucket-maintenance-configuration --table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket
```
# 管理表存储桶策略
可以使用 Amazon S3 REST API、AWS SDK 和 AWS Command Line Interface（AWS CLI）来添加、删除、更新和查看 Amazon S3 表存储桶的存储桶策略。有关更多信息，请参阅以下主题。
有关更多信息，请参阅以下主题。有关 Amazon S3 表类数据存储服务支持的 AWS Identity and Access Management（IAM）操作和条件键的更多信息，请参阅 [S3 表类数据存储服务的访问管理](s3-tables-setting-up.md)。有关表存储桶的存储桶策略示例，请参阅 [S3 表类数据存储服务的基于资源的策略](s3-tables-resource-based-policies.md)。
**注意**
表存储桶策略提供对存储在存储桶中的表的访问权限。表存储桶策略不适用于由其它账户拥有的表。
## 添加表存储桶策略
要向表存储桶添加存储桶策略，请使用以下 AWS CLI 示例。
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 创建表存储桶策略。要使用此命令，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables put-table-bucket-policy \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1 \
--resource-policy your-policy-JSON
```
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择 **Amazon S3**。
1. 选择**表存储桶**，并选择您要向其添加策略的表存储桶名称。
1. 选择 **Permissions（权限）**选项卡。
1. 在**表存储桶策略**下，选择**编辑**。
1. 在策略编辑器中，输入策略 JSON。
1. （可选）选择**策略示例**以查看可以根据需要调整的示例策略。
1. 输入您的策略后，选择**保存更改**。
## 查看表存储桶策略
要查看附加到表存储桶的存储桶策略，请使用以下 AWS CLI 示例。
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 查看附加到表存储桶的策略。要使用此命令，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables get-table-bucket-policy --table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1
```
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择 **Amazon S3**。
1. 选择**表存储桶**，并选择您要查看其策略的表存储桶名称。
1. 选择 **Permissions（权限）**选项卡。
## 删除表存储桶策略
要删除附加到表存储桶的存储桶策略，请使用以下 AWS CLI 示例。
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 删除表存储桶策略。要使用此命令，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables delete-table-bucket-policy --table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1
```
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择 **Amazon S3**。
1. 选择**表存储桶**，并选择要为其删除策略的表存储桶名称。
1. 选择 **Permissions（权限）**选项卡。
1. 在**表存储桶策略**下，选择**删除**。
# 使用 AWS 托管式表存储桶
AWS 托管式表存储桶是专用的 Amazon S3 表存储桶，旨在存储 AWS 托管式表，例如 [S3 元数据](metadata-tables-overview.md)日记表和实时清单表。与您直接创建和管理的客户管理的表存储桶不同，AWS 托管式表存储桶是在您配置需要 AWS 托管式表的功能时由 AWS 自动预置的。创建托管式表时，它们属于基于源存储桶名称的预定义命名空间。无法修改此预定义命名空间。
每个 AWS 账户在每个区域都有一个 AWS 托管式表存储桶，并遵循命名约定 `aws-s3`。该存储桶用作与该区域中账户的资源相关联的所有托管式表的集中位置。
下表将 AWS 托管式表存储桶与客户管理的表存储桶进行比较。
| **功能** | **AWS 托管式表存储桶** | **客户管理的表存储桶** |
| --- | --- | --- |
| 创建 | 由 AWS 服务自动创建 | 可以手动创建这些存储桶 |
| 命名 | 使用标准命名约定 (aws-s3) | 您自行定义名称 |
| 表创建 | 只有 AWS 服务可以创建表 | 您可以创建表 |
| 命名空间控制 | 您无法创建或删除命名空间（所有表均属于固定的命名空间） | 您可以创建和删除命名空间 |
| 访问 | 只读访问权限 | 完全访问 |
| 加密 | 仅当使用客户自主管理型 AWS Key Management Service（AWS KMS）密钥加密初始表时，您才能更改默认加密（SSE-S3）设置。 | 可以设置存储桶级别的默认加密并随时进行修改 |
| 维护。 | 由 AWS 服务管理 | 可以在存储桶级别自定义自动维护 |
## 使用 AWS 托管式表存储桶和查询表的权限
要使用 AWS 托管式表存储桶，您需要具有创建 AWS 托管式表存储桶和表以及为 AWS 托管式表指定加密设置的权限。您还需要具有查询 AWS 托管式表存储桶中的表的权限。
以下示例策略支持您通过 S3 元数据配置创建 AWS 托管式表存储桶：
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"PermissionsToWorkWithMetadataTables",
"Effect":"Allow",
"Action":[
"s3:CreateBucketMetadataTableConfiguration",
"s3tables:CreateTableBucket",
"s3tables:CreateNamespace",
"s3tables:CreateTable",
"s3tables:GetTable",
"s3tables:PutTablePolicy"
"s3tables:PutTableEncryption",
"kms:DescribeKey"
],
"Resource":[
"arn:aws:s3:::bucket/amzn-s3-demo-source-bucket",
"arn:aws:s3tables:us-east-1:111122223333:bucket/aws-s3",
"arn:aws:s3tables:us-east-1:111122223333:bucket/aws-s3/table/*",
"arn:aws:kms:us-east-1:111122223333:key/01234567-89ab-cdef-0123-456789abcdef"
]
}
]
}
```
以下示例策略支持您查询 AWS 托管式表存储桶中的表：
```
{
"Version":"2012-10-17",
"Statement":[
{
"Sid":"PermissionsToQueryMetadataTables",
"Effect":"Allow",
"Action":[
"s3tables:GetTable",
"s3tables:GetTableData",
"s3tables:GetTableMetadataLocation",
"kms:Decrypt"
],
"Resource":[
"arn:aws:s3tables:us-east-1:111122223333:bucket/aws-s3",
"arn:aws:s3tables:us-east-1:111122223333:bucket/aws-s3/table/*",
"arn:aws:kms:us-east-1:111122223333:key/01234567-89ab-cdef-0123-456789abcdef"
]
}
]
}
```
## 查询 AWS 托管式表存储桶中的表
可以使用 S3 表支持的访问方法和引擎来查询 AWS 托管式表存储桶中的 AWS 托管式表。下面是一些示例查询。
------
#### [ Using standard SQL ]
以下示例说明如何使用标准 SQL 语法查询 AWS 托管式表：
```
SELECT *
FROM "s3tablescatalog/aws-s3"."b_amzn-s3-demo-source-bucket"."inventory"
LIMIT 10;
```
以下示例说明如何将 AWS 托管式表与您自己的表联接：
```
SELECT *
FROM "s3tablescatalog/aws-s3"."b_amzn-s3-demo-source-bucket"."inventory" a
JOIN "s3tablescatalog/amzn-s3-demo-table-bucket"."my_namespace"."my_table" b
ON a.key = b.key
LIMIT 10;
```
------
#### [ Using Spark ]
以下示例说明如何使用 Spark 查询表：
```
spark.sql("""
SELECT *
FROM ice_catalog.inventory a
JOIN ice_catalog.my_table b
ON a.key = b.key
""").show(10, true)
```
以下示例说明如何将 AWS 托管式表与另一个表联接：
```
SELECT *
FROM inventory a
JOIN my_table b
ON a.key = b.key
LIMIT 10;
```
------
## AWS 托管式表存储桶的加密
默认情况下，AWS 托管式表存储桶通过使用 Amazon S3 托管式密钥的服务器端加密（SSE-S3）进行加密。在创建 AWS 托管式表存储桶后，可以使用 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_PutTableBucketEncryption.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_PutTableBucketEncryption.html) 来将存储桶的默认加密设置设为使用具有 AWS Key Management Service（AWS KMS）密钥的服务器端加密（SSE-KMS）。
在创建 AWS 托管式表期间，可以选择使用 SSE-KMS 对其进行加密。如果选择使用 SSE-KMS，则必须提供与 AWS 托管式表存储桶位于同一区域的客户自主管理型 KMS 密钥。只能在创建 AWS 托管式表的过程中为表设置加密类型。创建 AWS 托管式表后，无法更改其加密设置。
如果您希望 AWS 托管式表存储桶和存储在其中的表使用相同的 KMS 密钥，请确保在创建表存储桶后，使用您用于加密表的 KMS 密钥对其进行加密。将表存储桶的默认加密设置更改为使用 SSE-KMS 后，这些加密设置将用于将来在存储桶中创建的任何表。
# 将标签与 S3 表存储桶结合使用
AWS 标签是用于保存有关资源（在本例中为 Amazon S3 表存储桶）的元数据的键值对。您可以在创建 S3 表存储桶时为其添加标签，也可以管理现有表存储桶上的标签。有关标签的一般信息，请参阅[添加标签以进行成本分配或基于属性的访问权限控制（ABAC）](tagging.md)。
**注意**
在表存储桶上使用标签时，除了标准 S3 API 请求费率之外，没有任何其他费用。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)。
## 将标签与表存储桶结合使用的常用方法
使用 S3 表存储桶上的标签来执行以下操作：
**基于属性的访问权限控制（ABAC）**：根据 S3 表存储桶的标签扩展访问权限并授予对这些存储桶的访问权限。有关更多信息，请参阅 [Using tags for ABAC](https://docs.aws.amazon.com/AmazonS3/latest/userguide/tagging.html#using-tags-for-abac)。
### 适用于 S3 表存储桶的 ABAC
Amazon S3 表存储桶支持使用标签进行基于属性的访问权限控制（ABAC）。请在您的 AWS Organizations、AWS Identity and Access Management（IAM）和 S3 表存储桶策略中使用基于标签的条件键。Amazon S3 中的 ABAC 支持跨多个 AWS 账户进行授权。
在您的 IAM 策略中，您可以使用 `s3tables:TableBucketTag/tag-key` 条件键或 [AWS 全局条件键](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-tagkeys) `aws:ResourceTag/key-name`、`aws:RequestTag/key-name` 或 `aws:TagKeys`，根据表存储桶的标签控制对 S3 表存储桶的访问。
#### aws:ResourceTag/key-name
使用此条件键可将您在策略中指定的标签键值对与附加到资源的键值对进行比较。例如，您可能会要求仅在表存储桶具有标签键 `Department` 和值 `Marketing` 时才允许访问该表存储桶。
此条件键将应用于使用 Amazon S3 控制台、AWS 命令行界面（CLI）、S3 API 或 AWS SDK 执行的所有表存储桶操作（针对 `CreateBucket` API 请求的操作除外）。
有关策略示例，请参阅 [1.1：用于通过标签限制对表存储桶内表的操作的表存储桶策略](#example-policy-table-bucket-resource-tag)。
有关更多示例策略和信息，请参阅《AWS Identity and Access Management 用户指南》**中的[控制对 AWS 资源的访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-resources)。
**注意**
对于对表执行的操作，此条件键将对应用于表的标签起作用，而非应用于包含该表的表存储桶的标签。如果您希望 ABAC 策略在您执行表操作时对表存储桶的标签起作用，请改用 `s3tables:TableBucketTag/tag-key`。
#### aws:RequestTag/key-name
使用此条件键可将请求中传递的标签键值对与您在策略中指定的标签对进行比较。例如，您可以检查为表存储桶添加标签的请求是否包含标签键 `Department` 并具有值 `Accounting`。
在 `TagResource` 或 `CreateTableBucket` API 操作请求中传递标签键时，或者使用 Amazon S3 控制台、AWS 命令行界面（CLI）或 AWS SDK 标记或创建带有标签的表存储桶时，此条件键适用。
有关策略示例，请参阅 [1.2：用于创建或修改具有特定标签的表存储桶的 IAM 策略](#example-policy-table-bucket-request-tag)。
有关更多示例策略和信息，请参阅《AWS Identity and Access Management 用户指南》**中的[在 AWS 请求期间控制访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-requests)。
#### aws:TagKeys
使用此条件键可将请求中的标签键与您在策略中指定的键进行比较，从而定义允许用于访问操作的标签键。例如，要允许在 `CreateTableBucket` 操作期间添加标签，必须创建一个同时允许 `s3tables:TagResource` 和 `s3tables:CreateTableBucket` 操作的策略。然后，您可以使用 `aws:TagKeys` 条件键来强制仅在 `CreateTableBucket` 请求中使用特定标签。
在 `TagResource`、`UntagResource` 或 `CreateTableBucket` API 操作中传递标签键时，或者使用 Amazon S3 控制台、AWS 命令行界面（CLI）或 AWS SDK 来标记、取消标记或创建带有标签的表存储桶时，此条件键适用。
有关策略示例，请参阅 [1.3：用于控制对现有资源上的标签的修改以保持标签治理的 IAM 策略](#example-policy-table-bucket-tag-keys)。
有关更多示例策略和更多信息，请参阅《AWS Identity and Access Management 用户指南》**中的[根据标签键控制访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys)。
#### s3tables:TableBucketTag/tag-key
使用此条件键可通过标签授予对表存储桶中特定数据的权限。此条件键主要作用于针对所有 S3 表操作分配给表存储桶的标签。即使在您创建带有标签的表时，此条件键也会对应用于包含该表的表存储桶的标签起作用。下面是一些例外情况：
+ 当您创建带有标签的表存储桶时，此条件键会对请求中的标签起作用。
有关策略示例，请参阅 [1.4：使用 s3tables:TableBucketTag 条件键](#example-policy-table-bucket-tag)。
#### 适用于表存储桶的示例 ABAC 策略
请参阅以下适用于 Amazon S3 表存储桶的示例 ABAC 策略。
**注意**
如果您使用 Lake Formation 来管理对 Amazon S3 表类数据存储服务的访问，并且您拥有基于 IAM 或 S3 表类数据存储服务资源的策略（根据主体标签限制 IAM 用户和 IAM 角色），则必须将相同的主体标签附加到 Lake Formation 用来访问 Amazon S3 数据的 IAM 角色（例如，LakeFormationDataAccessRole），并为该角色授予必要的权限。这是基于标签的访问控制策略与 S3 表类数据存储服务分析集成正常协同工作所必需的。
##### 1.1：用于通过标签限制对表存储桶内表的操作的表存储桶策略
在此表存储桶策略中，指定的 IAM 主体（用户和角色）仅在表的 `project` 标签的值与主体的 `project` 标签的值匹配时，才能对表存储桶中的任何表执行 `GetTable` 操作。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowGetTable",
"Effect": "Allow",
"Principal": {
"AWS": "111122223333"
},
"Action": "s3tables:GetTable",
"Resource": "arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/project": "${aws:PrincipalTag/project}"
}
}
}
]
}
```
##### 1.2：用于创建或修改具有特定标签的表存储桶的 IAM 策略
**注意**
如果您使用 AWS Lake Formation 管理对 Amazon S3 表的访问，并且将 ABAC 与 Amazon S3 表类数据存储服务结合使用，请确保您还为 Lake Formation 代入的 IAM 角色授予所需的访问权限。有关为 Lake Formation 设置 IAM 角色的更多信息，请参阅《AWS Lake Formation 开发人员指南》**中的[将 Amazon S3 表目录与 Data Catalog 和 Lake Formation 集成的先决条件](https://docs.aws.amazon.com/lake-formation/latest/dg/s3tables-catalog-prerequisites.html)。
在此 IAM 策略中，具有此策略的用户或角色仅在以下情况下才能创建 S3 表存储桶：他们在表存储桶创建请求中使用标签键 `project` 和标签值 `Trinity` 为表存储桶添加标签。他们还可以在现有 S3 表存储桶上添加或修改标签，前提是 `TagResource` 请求包含标签键值对 `project:Trinity`。此策略不授予对表存储桶或其对象的读取、写入或删除权限。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CreateTableBucketWithTags",
"Effect": "Allow",
"Action": [
"s3tables:CreateTableBucket",
"s3tables:TagResource"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestTag/project": [
"Trinity"
]
}
}
}
]
}
```
##### 1.3：用于控制对现有资源上的标签的修改以保持标签治理的 IAM 策略
在此 IAM 策略中，IAM 主体（用户或角色）仅在表存储桶的 `project` 标签的值与主体的 `project` 标签的值匹配时，才能修改表存储桶上的标签。对于这些表存储桶，只允许使用在 `aws:TagKeys` 条件键中指定的四个标签 `project`、`environment`、`owner` 和 `cost-center`。这有助于强制执行标签治理，防止未经授权修改标签，并使标签架构跨表存储桶保持一致。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EnforceTaggingRulesOnModification",
"Effect": "Allow",
"Action": [
"s3tables:TagResource",
"s3tables:UntagResource"
],
"Resource": "arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket",
"Condition": {
"StringEquals": {
"aws:ResourceTag/project": "${aws:PrincipalTag/project}"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"project",
"environment",
"owner",
"cost-center"
]
}
}
}
]
}
```
##### 1.4：使用 s3tables:TableBucketTag 条件键
在此 IAM 策略中，条件语句仅在表存储桶具有标签键 `Environment` 和标签值 `Production` 时，才支持访问表存储桶的数据。`s3tables:TableBucketTag/` 与 `aws:ResourceTag/` 条件键不同，因为除了根据标签控制对表存储桶的访问外，它还支持根据父表存储桶上的标签控制对表的访问。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowAccessToSpecificTables",
"Effect": "Allow",
"Action": "*",
"Resource": "arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/*",
"Condition": {
"StringEquals": {
"s3tables:TableBucketTag/Environment": "Production"
}
}
}
]
}
```
## 管理表存储桶的标签
您可以使用 Amazon S3 控制台、AWS 命令行界面（CLI）、AWS SDK 或以下 S3 API 为 S3 表存储桶添加或管理标签：[TagResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_TagResource.html)、[UntagResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_UntagResource.html) 和 [ListTagsForResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_ListTagsForResource.html)。有关更多信息，请参阅下列内容：
**Topics**
+ [将标签与表存储桶结合使用的常用方法](#common-ways-to-use-tags-table-bucket)
+ [管理表存储桶的标签](#table-bucket-working-with-tags)
+ [创建带有标签的表存储桶](table-bucket-create-tag.md)
+ [向表存储桶添加标签](table-bucket-tag-add.md)
+ [查看表存储桶标签](table-bucket-tag-view.md)
+ [从表存储桶删除标签](table-bucket-tag-delete.md)
# 创建带有标签的表存储桶
您可以在创建 Amazon S3 表存储桶时为其添加标签。在表存储桶上使用标签时，除了标准 S3 API 请求费率之外，没有任何其他费用。有关更多信息，请参阅 [Amazon S3 定价](https://docs.aws.amazon.com/s3/pricing/)。有关为表存储桶添加标签的更多信息，请参阅[将标签与 S3 表存储桶结合使用](table-bucket-tagging.md)。
## 权限
要创建带有标签的表存储桶，您必须具有以下权限：
+ `s3tables:CreateTableBucket`
+ `s3tables:TagResource`
## 错误故障排除
如果您在尝试创建带有标签的表存储桶时遇到错误，可以执行以下操作：
+ 验证您是否具有创建表存储桶并向其应用标签所需的[权限](#table-bucket-create-tag-permissions)。
+ 检查 IAM 用户策略，了解是否存在任何基于属性的访问权限控制（ABAC）条件。您的策略可能要求您仅使用特定的标签键和值为表存储桶添加标签。有关 ABAC 和示例表存储桶 ABAC 策略的更多信息，请参阅[适用于 S3 表存储桶的 ABAC](https://docs.aws.amazon.com/AmazonS3/latest/userguide/table-bucket-tagging.html#abac-for-table-buckets)。
## Steps
您可以使用 Amazon S3 控制台、AWS Command Line Interface（AWS CLI）、Amazon S3 表类数据存储服务 REST API 和 AWS SDK 来创建应用了标签的表存储桶。
## 使用 S3 控制台
使用 Amazon S3 控制台创建带有标签的表存储桶：
1. 登录到 Amazon S3 控制台，网址：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 要创建新的表存储桶，请选择**创建表存储桶**。
1. 输入表存储桶的名称。有关更多信息，请参阅 [Amazon S3 表存储桶、表和命名空间命名规则](s3-tables-buckets-naming.md)。
1. 在**创建表存储桶**页面上，有一个**标签**部分。
1. 选择**添加新标签**以打开标签编辑器并输入标签键值对。标签键是必需的，但值是可选的。
1. 要添加其它标签，请再次选择**添加新标签**。最多可输入 50 个标签键值对。
1. 为新的表存储桶指定其余选项。有关更多信息，请参阅 [创建表存储桶](s3-tables-buckets-create.md)。
1. 选择**创建表存储桶**。
## 使用 REST API
有关 Amazon S3 表类数据存储服务 REST API 支持创建带有标签的表存储桶的相关信息，请参阅《Amazon Simple Storage Service API 参考》**中的以下部分：
+ [CreateTableBucket](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_CreateTableBucket.html)
## 使用 AWS CLI
要安装 AWS CLI，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
以下 CLI 示例说明如何使用 AWS CLI 创建带有标签的表存储桶。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
创建表存储桶时，必须提供配置详细信息。有关更多信息，请参阅 [创建表存储桶](s3-tables-buckets-create.md)。您还必须使用符合表存储桶命名约定的名称来命名表存储桶。有关更多信息，请参阅 [Amazon S3 表存储桶、表和命名空间命名规则](s3-tables-buckets-naming.md)。
**请求**
```
aws --region us-west-2 \
s3tables create-table-bucket \
--tags '{"Department":"Engineering"}' \
--name amzn-s3-demo-table-bucket
```
# 向表存储桶添加标签
您可以向 Amazon S3 表存储桶添加标签并修改这些标签。有关为表存储桶添加标签的更多信息，请参阅[将标签与 S3 表存储桶结合使用](table-bucket-tagging.md)。
## 权限
要向表存储桶添加标签，您必须具有以下权限：
+ `s3tables:TagResource`
## 错误故障排除
如果您在尝试向表存储桶添加标签时遇到错误，可以执行以下操作：
+ 验证您是否具有向表存储桶添加标签所需的[权限](#table-bucket-tag-add-permissions)。
+ 如果您尝试添加以 AWS 保留前缀 `aws:` 开头的标签键，请更改标签键并重试。
+ 标签键是必需的。此外，请确保标签键和标签值不超过最大字符长度，并且不包含受限字符。有关更多信息，请参阅 [添加标签以进行成本分配或基于属性的访问权限控制（ABAC）](tagging.md)。
## Steps
您可以使用 Amazon S3 控制台、AWS 命令行界面（AWS CLI）、Amazon S3 表类数据存储服务 REST API 和 AWS SDK 向表存储桶添加标签。
## 使用 S3 控制台
使用 Amazon S3 控制台向表存储桶添加标签：
1. 登录到 Amazon S3 控制台，网址：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择表存储桶名称。
1. 选择**属性**选项卡。
1. 滚动到**标签**部分，然后选择**添加新标签**。
1. 这会打开**添加标签**页面。最多可以输入 50 个标签键值对。
1. 如果您添加的新标签与现有标签具有相同的键名称，则新标签的值将覆盖现有标签的值。
1. 还可以在此页面上编辑现有标签的值。
1. 添加标签后，选择**保存更改**。
## 使用 REST API
有关 Amazon S3 REST API 支持向表存储桶添加标签的相关信息，请参阅《Amazon Simple Storage Service API 参考》**中的以下部分：
+ [TagResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_TagResource.html)
## 使用 AWS CLI
要安装 AWS CLI，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
以下 CLI 示例说明如何使用 AWS CLI 向表存储桶添加标签。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
**请求**
```
aws --region us-west-2 \
s3tables tag-resource \
--resource-arn arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket \
--tags '{"Department":"Engineering"}'
```
# 查看表存储桶标签
您可以查看或列出应用于 Amazon S3 表存储桶的标签。有关为表存储桶添加标签的更多信息，请参阅[将标签与 S3 表存储桶结合使用](table-bucket-tagging.md)。
## 权限
要查看应用于表存储桶的标签，您必须具有以下权限：
+ `s3tables:ListTagsForResource`
## 错误故障排除
如果您在尝试列出或查看表存储桶的标签时遇到错误，可以执行以下操作：
+ 验证您是否具有查看表存储桶的标签所需的[权限](#table-bucket-tag-view-permissions)。
## Steps
您可以使用 Amazon S3 控制台、AWS Command Line Interface（AWS CLI）、Amazon S3 REST API 和 AWS SDK 来查看应用于表存储桶的标签。
## 使用 S3 控制台
使用 Amazon S3 控制台查看应用于表存储桶的标签：
1. 登录到 Amazon S3 控制台，网址：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择表存储桶名称。
1. 选择**属性**选项卡。
1. 滚动至**标签**部分，以查看应用于表存储桶的所有标签。
1. 默认情况下，**标签**部分显示**用户定义的标签**。您可以选择 **AWS 生成的标签**选项卡来查看 AWS 服务应用到表存储桶的标签。
## 使用 REST API
有关 Amazon S3 REST API 支持查看应用于表存储桶的标签的相关信息，请参阅《Amazon Simple Storage Service API 参考》**中的以下部分：
+ [ListTagsforResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_ListTagsForResource.html)
## 使用 AWS CLI
要安装 AWS CLI，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
以下 CLI 示例说明如何查看应用到表存储桶的标签。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
**请求**
```
aws --region us-west-2 \
s3tables list-tags-for-resource \
--resource-arn arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/table/example_table
```
**响应 - 存在标签：**
```
{
"tags": {
"project": "Trinity",
"code": "123456"
}
}
```
**响应 - 不存在任何标签：**
```
{
"Tags": []
}
```
# 从表存储桶删除标签
您可以从 Amazon S3 表存储桶删除标签。有关为表存储桶添加标签的更多信息，请参阅[将标签与 S3 表存储桶结合使用](table-bucket-tagging.md)。
**注意**
如果您删除某个标签，但后来得知该标签用于跟踪成本或用于访问控制，则可以将该标签重新添加到表存储桶。
## 权限
要从表存储桶删除标签，您必须具有以下权限：
+ `s3tables:UntagResource`
## 错误故障排除
如果在尝试从表存储桶删除标签时遇到错误，可以执行以下操作：
+ 验证您是否具有从表存储桶删除标签所需的[权限](#table-bucket-tag-delete-permissions)。
## Steps
您可以使用 Amazon S3 控制台、AWS Command Line Interface（AWS CLI）、Amazon S3 表类数据存储服务 REST API 和 AWS SDK 从表存储桶删除标签。
## 使用 S3 控制台
使用 Amazon S3 控制台从表存储桶删除标签：
1. 登录到 Amazon S3 控制台，网址：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择表存储桶名称。
1. 选择**属性**选项卡。
1. 滚动到**标签**部分，然后选中要删除的一个或多个标签旁边的复选框。
1. 选择**删除**。
1. 将显示**删除用户定义的标签**弹出窗口，要求您确认删除所选的一个或多个标签。
1. 选择 **Delete (删除)** 以确认。
## 使用 REST API
有关 Amazon S3 REST API 支持从表存储桶删除标签的相关信息，请参阅《Amazon Simple Storage Service API 参考》**中的以下部分：
+ [UnTagResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_UntagResource.html)
## 使用 AWS CLI
要安装 AWS CLI，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
以下 CLI 示例说明如何使用 AWS CLI 从表存储桶删除标签。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
**请求**
```
aws --region us-west-2 \
s3tables untag-resource \
--resource-arn arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket \
--tags-keys '["Department"]'
```
# S3 表类数据存储服务维护
Amazon S3 自动执行维护，以提高 S3 表存储桶中表的性能。维护是在表存储桶和各个表级别执行的，包括以下内容：
**表存储桶级维护：**
+ **未引用文件移除**：清理孤立文件以优化存储使用率和成本。
**表级维护：**
+ **文件压缩**：整合小文件以提高查询性能并降低存储成本。
+ **快照管理**：控制表版本历史记录并防止元数据过度增长。
默认情况下，将启用这些选项。可以通过维护配置文件来编辑或禁用这些操作。
除了这些选项之外，您还可以为表启用和配置记录过期设置。使用此选项，当记录过期时，Amazon S3 会自动从表中删除记录。
**Topics**
+ [S3 表类数据存储服务维护任务状态](s3-tables-maintenance-status.md)
+ [表存储桶的维护](s3-table-buckets-maintenance.md)
+ [表维护](s3-tables-maintenance.md)
+ [表的记录过期时间](s3-tables-record-expiration.md)
+ [维护任务的注意事项和限制](s3-tables-considerations.md)
# S3 表类数据存储服务维护任务状态
S3 表类数据存储服务维护任务会定期为您的 S3 表或表存储桶运行。可以使用 `GetTableMaintenanceJobStatus` API 查询这些任务的状态。
**使用 AWS CLI 获取维护任务的状态**
以下示例将使用 `GetTableMaintenanceJobStatus` API 获取维护任务的状态。
```
aws s3tables get-table-maintenance-job-status \
--table-bucket-arn="arn:aws:s3tables:arn:aws::111122223333:bucket/amzn-s3-demo-bucket1" \
--namespace="mynamespace" \
--name="testtable"
```
有关更多信息，请参阅《AWS CLI Command Reference》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/get-table-maintenance-job-status.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/get-table-maintenance-job-status.html)。
S3 表类数据存储服务维护任务可以在四种可能的状态之间转换：
+ `Successful`
+ `Failed`
+ `Disabled`
+ `Not_Yet_Run`
状态为失败的任务将包含一条失败消息。下面的列表介绍了可能的失败消息。
+ 尝试读取表时遇到 Iceberg 验证异常。确保您的表可读，符合 Iceberg 规范，并且仅包含以 S3 表别名开头的 S3 路径。
+ Iceberg 快照管理目前不支持用户定义的标签或引用。
+ Iceberg 表维护配置与“history.expire.max-snapshot-age-ms”和“history.expire.min-snapshots-to-keep”表属性不兼容。
+ 当“gc.enabled”表属性为 false 时，不支持 Iceberg 快照管理和未引用文件移除。确保此属性为未设置或显式设置为 true。
+ 由于元数据过期，提交失败。将在下次有机会时重试维护。
+ 访问权限不足，无法执行表维护。确保用于加密表的密钥处于活动状态、存在且具有向 S3 服务主体 `maintenance.s3tables.amazonaws.com` 授予访问权限的资源策略。
**注意**
有关 S3 表类数据存储服务的 AWS KMS 权限的更多信息，请参阅 [S3 表类数据存储服务 SSE-KMS 加密的权限要求](s3-tables-kms-permissions.md)。
+ 内部错误
# 表存储桶的维护
Amazon S3 提供维护操作，以增强表存储桶的管理和性能。默认情况下，对所有表存储桶启用了以下选项。您可以通过为表存储桶指定维护配置文件来编辑或禁用此选项。
编辑此配置需要 `s3tables:PutTableBucketMaintenanceConfiguration` 权限。
**Topics**
+ [未引用文件移除](#s3-table-bucket-maintenance-unreferenced)
+ [注意事项和限制](#s3-tables-buckets-considerations-see-more)
## 未引用文件移除
未引用文件移除会识别并删除所有未被任何表快照引用的对象。作为未引用文件移除策略的一部分，您可以配置两个属性：`unreferencedDays`（默认为 3 天）和 `nonCurrentDays`（默认为 10 天）。
对于您的表未引用且早于 `unreferencedDays` 属性的任何对象，S3 将该对象标记为非当前版本。S3 会在 `nonCurrentDays` 属性指定的天数后删除非当前对象。
**注意**
删除非当前对象是永久性的，无法恢复这些对象。
要查看或恢复已标记为非当前版本的对象，必须联系 AWS 支持。有关联系 AWS 支持 的信息，请参阅[联系 AWS](https://aws.amazon.com/contact-us/) 或 [AWS 支持 文档](https://aws.amazon.com/documentation/aws-support/)。
未引用文件移除仅根据对表的引用来确定要从该表中删除的对象。在表之外对这些对象进行的任何引用都不会阻止未引用文件移除来删除对象。
如果您禁用未引用文件移除，则任何正在进行的任务都不会受到影响。配置更改后，新配置将在下一个任务中生效。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)中的定价信息。
您只能在表存储桶级配置未引用文件移除。此配置将应用于存储桶中的每个表。
**使用 AWS CLI 配置未引用文件移除**
以下示例将使用 `PutTableBucketMaintenanceConfiguration` API 将 `unreferencedDays` 设置为 4 天，并将 `nonCurrentDays` 设置为 10 天。
```
aws s3tables put-table-bucket-maintenance-configuration \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--type icebergUnreferencedFileRemoval \
--value '{"status":"enabled","settings":{"icebergUnreferencedFileRemoval":{"unreferencedDays":4,"nonCurrentDays":10}}}'
```
有关更多信息，请参阅《AWS CLI Command Reference》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-bucket-maintenance-configuration.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-bucket-maintenance-configuration.html)。
## 注意事项和限制
要了解有关未引用文件移除的其它注意事项和限制的更多信息，请参阅[维护任务的注意事项和限制](s3-tables-considerations.md)。
# 表维护
S3 表类数据存储服务提供维护操作，以增强各个表的管理和性能。默认情况下为表存储桶中的所有表启用以下选项。可以通过为 S3 表指定维护配置文件来编辑或禁用这些选项。
编辑此配置需要 `s3tables:GetTableMaintenanceConfiguration` 和 `s3tables:PutTableMaintenanceConfiguration` 权限。
**注意**
您可以通过 CloudTrail 日志来跟踪 S3 表类数据存储服务对表的自动维护操作，有关更多信息，请参阅 [S3 表类数据存储服务维护的 CloudTrail 管理事件](s3-tables-logging.md#s3-tables-maintenance-events)。
**Topics**
+ [压缩](#s3-tables-maintenance-compaction)
+ [快照管理](#s3-tables-maintenance-snapshot)
+ [注意事项和限制](#s3-tables-considerations-see-more)
## 压缩
压缩是在表级别配置的，可将多个较小的对象组合成更少、更大的对象，以提高 Apache Iceberg 查询性能。当组合对象时，压缩还会应用表中行级删除的效果。
默认情况下，对所有表启用压缩功能，默认目标文件大小为 512 MB，或者您指定的自定义值介于 64 MB 到 512 MB 之间。压缩后的文件将作为表的最新快照写入。
**注意**
仅 Apache Parquet、Avro 和 ORC 文件类型支持压缩。
### 压缩策略
您可以从多种压缩策略中进行选择，这些策略可以进一步提高查询性能，具体取决于查询模式和表排序顺序。
S3 表类数据存储服务现在对于表支持以下压缩策略：
+ **Auto（默认）**
+ Amazon S3 根据表排序顺序选择最佳压缩策略。这是适用于所有表的默认压缩策略。
+ 对于在元数据中具有已定义的排序顺序的表，`auto` 将自动应用 `sort` 压缩。
+ 对于没有排序顺序的表，`auto` 将默认为使用 `binpack` 压缩。
+ **Binpack**
+ 将小文件组合成较大的文件（目标大小通常超过 100 MB），同时应用任何待执行的删除。这是适用于未排序表的默认压缩策略。
+ **排序**
+ 在压缩期间根据指定的列整理数据，这些列自动按层次结构排序，从而提高筛选出的操作的查询性能。当查询经常会筛选特定列时，建议使用此策略。当您使用此策略时，如果在表属性中定义了 `sort_order`，S3 表类数据存储服务会自动对列应用分层排序。
+ **Z-order**
+ 通过将多个属性混合成一个可用于排序的标量值来优化数据的组织，从而实现跨多个维度高效查询。需要同时跨多个维度查询数据时，建议使用此策略。此策略要求您在 Iceberg 表属性中使用 `sort_order` 表属性定义排序顺序。
压缩将产生额外费用。`z-order` 和 `sort` 压缩策略的成本可能高于 `binpack`。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)中的定价信息。
### 压缩示例
以下示例展示了表压缩的配置。
**使用 AWS CLI 配置压缩目标文件大小**
最小目标压缩文件大小为 64 MB；最大值为 512 MB。
以下示例将使用 `PutTableMaintenanceConfiguration` API 将目标文件大小更改为 256 MB。
```
aws s3tables put-table-maintenance-configuration \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1 \
--type icebergCompaction \
--namespace mynamespace \
--name testtable \
--value='{"status":"enabled","settings":{"icebergCompaction":{"targetFileSizeMB":256}}}'
```
有关更多信息，请参阅《AWS CLI Command Reference》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-maintenance-configuration.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-maintenance-configuration.html)。
**使用 AWS CLI 配置压缩策略**
以下示例使用 `PutTableMaintenanceConfiguration` API 将压缩策略更改为 `sort`。设置压缩时，您可以从以下压缩策略中进行选择：`auto`、`binpack`、`sort` 或 `z-order`
要将压缩策略设置为 `sort` 或 `z-order`，需要满足以下先决条件：
+ 在 Iceberg 表属性中定义的排序顺序。
+ `s3tables:GetTableData` 权限。
```
aws s3tables put-table-maintenance-configuration \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--type icebergCompaction \
--namespace mynamespace \
--name testtable \
--value='{"status":"enabled","settings":{"icebergCompaction":{"strategy":"sort"}}}'
```
有关更多信息，请参阅《AWS CLI Command Reference》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-maintenance-configuration.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-maintenance-configuration.html)。
**使用 AWS CLI 禁用压缩**
以下示例将使用 `PutTableMaintenanceConfiguration` API 禁用压缩。
```
aws s3tables put-table-maintenance-configuration \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--type icebergCompaction \
--namespace mynamespace \
--name testtable \
--value='{"status":"disabled","settings":{"icebergCompaction":{"targetFileSizeMB":256}}}'
```
有关更多信息，请参阅《AWS CLI Command Reference》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-maintenance-configuration.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-maintenance-configuration.html)。
## 快照管理
快照管理确定表的活动快照的数量。这基于 `MinimumSnapshots`（默认为 1）和 `MaximumSnapshotAge`（默认为 120 小时）。快照管理会根据这些配置使表快照到期和移除表快照。
快照到期后，Amazon S3 会将仅由该快照引用的任何对象标记为非当前对象。这些非当前对象将在由未引用文件移除策略中的 `NoncurrentDays` 属性指定的天数后被删除。
**注意**
删除非当前对象是永久性的，无法恢复这些对象。
要查看或恢复已标记为非当前对象的对象，必须联系 AWS 支持。有关联系 AWS 支持 的信息，请参阅[联系 AWS](https://aws.amazon.com/contact-us/) 或 [AWS 支持 文档](https://aws.amazon.com/documentation/aws-support/)。
快照管理根据仅对表的引用来确定要从该表中删除的对象。从表外部对这些对象进行的引用将不会阻止快照管理删除这些对象。
**注意**
快照管理不支持您在 `metadata.json` 文件中或通过 `ALTER TABLE SET TBLPROPERTIES` SQL 命令配置为 Iceberg 表属性的保留值，包括基于分支或标签的保留。当您配置基于分支或标签的保留策略，或者在 `metadata.json` 文件上配置的保留策略长度超过通过 `PutTableMaintenanceConfiguration` API 配置的值时，快照管理将被禁用。在这些情况下，S3 不会使快照到期或移除快照，您需要手动删除快照或从 Iceberg 表中移除属性，以避免产生存储费用。
只能在表级配置快照管理。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)中的定价信息。
### 快照管理示例
以下示例展示了表快照管理的配置。
**使用 AWS CLI 配置快照管理**
以下示例将使用 `PutTableMaintenanceConfiguration` API 将 `MinimumSnapshots` 设置为 10，并将 `MaximumSnapshotAge` 设置为 2500 小时。
```
aws s3tables put-table-maintenance-configuration \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--namespace my_namespace \
--name my_table \
--type icebergSnapshotManagement \
--value '{"status":"enabled","settings":{"icebergSnapshotManagement":{"minSnapshotsToKeep":10,"maxSnapshotAgeHours":2500}}}'
```
**使用 AWS CLI 禁用快照管理**
以下示例将使用 `PutTableMaintenanceConfiguration` API 禁用快照管理。
```
aws s3tables put-table-maintenance-configuration \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--namespace my_namespace \
--name my_table \
--type icebergSnapshotManagement \
--value '{"status":"disabled","settings":{"icebergSnapshotManagement":{"minSnapshotsToKeep":1,"maxSnapshotAgeHours":120}}}'
```
有关更多信息，请参阅《AWS CLI Command Reference》**中的 [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-maintenance-configuration.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3tables/put-table-maintenance-configuration.html)。
## 注意事项和限制
要详细了解压缩和快照管理的其它注意事项和限制，请参阅[维护任务的注意事项和限制](s3-tables-considerations.md)。
**注意**
S3 表类数据存储服务应用的 parquets row-group-default 为 128 MB。
# 表的记录过期时间
默认情况下，S3 表中的记录不会过期。为了帮助尽可能降低表的存储成本，您可以为表启用和配置记录过期。使用此选项，当记录过期时，Amazon S3 会自动从表中删除记录。
如果为表启用记录过期，则可以指定记录过期之前在表中保留记录的天数。这可以是从 1 天到 2147483647 天之间的任意天数。例如，要将表记录保留一年，请指定 `365` 天。然后，记录会保留 365 天。365 天后，记录过期，Amazon S3 会自动将其删除。
对于存储来自特定 AWS 服务（目前包括 Amazon S3 Storage Lens 存储统计管理工具和 Amazon SageMaker 目录）的特定数据集的 AWS 托管的表，您可以启用和配置记录过期。记录过期选项目前不可用于 AWS 托管的其他表。唯一的例外是 Amazon S3 元数据日记表。日记表使用您在服务级别指定的不同记录过期设置。有关为此类表配置记录过期的信息，请参阅[使日记表记录过期](metadata-tables-expire-journal-table-records.md)。请注意，记录过期选项不可用于您创建的 S3 表。
为表启用记录过期后，您可以随时禁用该功能。Amazon S3 随即停止过期，不再从表中删除记录。
**Topics**
+ [工作原理](#s3-tables-record-expiration-how-it-works)
+ [配置记录过期](#s3-tables-record-expiration-configure)
+ [监控记录过期](#s3-tables-record-expiration-monitor)
+ [注意事项](#s3-tables-expiration-considerations)
## 记录过期的工作原理
当记录的寿命超过您在表的记录过期设置中指定的天数时，记录过期会自动从 S3 表中删除这些记录。为了确定记录何时过期，Amazon S3 使用记录中的特定时间戳。时间戳列的选择直接派生自表的表架构。您无需指定要使用的时间戳列。这些表由 AWS 管理，当您为表启用记录过期时，Amazon S3 会自动选择要使用的相应列。
对于存储特定 Amazon S3 Storage Lens 存储统计管理工具指标或特定 Amazon SageMaker 目录元数据的 AWS 托管的表，您可以启用和配置记录过期设置。记录过期选项可用于这些服务的以下 AWS 托管的表：
+ S3 Storage Lens 存储统计管理工具：`bucket_property_metrics`、`default_activity_metrics`、`default_storage_metrics`、`expanded_prefixes_activity_metrics` 和 `expanded_prefixes_storage_metrics`。为了确定这些表中的记录何时过期，Amazon S3 使用记录中的 `report_time` 字段。
+ Amazon SageMaker 目录：`ASSET`。为了确定此表中的记录何时过期，Amazon S3 使用记录中的 `snapshot_time` 字段。
为表启用记录过期后，Amazon S3 开始运行记录过期作业，这些作业对表执行以下操作：
1. 识别超过了指定过期设置的记录。
1. 创建新的快照，排除对已过期记录的引用。
删除操作还会基于表的维护配置设置中的快照过期时间和未引用的文件删除设置。有关这些设置的更多信息，请参阅[表维护](s3-tables-maintenance.md)。
**警告**
在记录满足过期的条件之后，Amazon S3 会在 24 到 48 小时内使这些记录过期并删除。系统从最新的快照中移除表记录。通过表维护操作来移除记录的数据和存储。表记录在过期后无法恢复。
## 为表配置记录过期
您可以使用 Amazon S3 控制台、Amazon S3 REST API、AWS Command Line Interface（AWS CLI）或 AWS SDK，启用、配置和以其他方式管理 S3 表的记录过期设置。
在尝试对表执行这些任务之前，确保您拥有以下 AWS Identity and Access Management（IAM）权限：
+ `s3tables:GetTableRecordExpirationConfiguration`：此操作让您可以访问表的当前记录过期设置。
+ `s3tables:PutTableRecordExpirationConfiguration`：此操作让您可以启用、配置和禁用表的记录过期设置。
+ `s3tables:GetTableRecordExpirationJobStatus`：此操作让您可以监控表的记录过期操作（作业）的状态以及访问操作的指标。
以下各节介绍如何使用 Amazon S3 控制台和 AWS CLI，为表启用、配置和禁用记录过期设置。要使用 Amazon S3 REST API 或 AWS SDK 执行这些任务，请使用 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_PutTableRecordExpirationConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_PutTableRecordExpirationConfiguration.html) 操作。有关更多信息，请参阅《Amazon Simple Storage Service API 参考》**中的[使用 Amazon S3 进行开发](https://docs.aws.amazon.com/AmazonS3/latest/API/developing-s3.html)。
### 使用 S3 控制台
要使用控制台启用和配置 S3 表的记录过期设置，请按照以下步骤操作。
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在**表存储桶**页面上，选择存储表的存储桶。
1. 在**表**选项卡上，选择表。
1. 在**维护**选项卡上的**记录过期**部分，选择**编辑**。
1. 在**记录过期**下，选择**启用**。
1. 对于**记录距离过期的天数**，输入表中记录的保留天数。这可以是从 1 到 2147483647 之间的任意整数。例如，要将记录保留一年，请输入 **365**。
**警告**
确定表中记录的相应保留期限时，请注意，记录在过期后无法恢复。
1. 选择**保存更改**。
以后若要更改保留期，请重复上述步骤。
以后若要禁用记录过期，请重复步骤 1 到 5。然后，在第 6 步中选择**禁用**。完成后，选择**保存更改**。
### 使用 AWS CLI
要使用 AWS CLI 配置和管理 S3 表的记录过期设置，请运行 [https://docs.aws.amazon.com/cli/latest/reference/s3tables/put-table-record-expiration-configuration.html](https://docs.aws.amazon.com/cli/latest/reference/s3tables/put-table-record-expiration-configuration.html) 命令。
您可以先创建 JSON 文件，其中包含要应用于表的记录过期设置。以下示例说明对表启用记录过期的 JSON 文件的内容。它还为表中的记录指定了 30 天的保留期。换而言之，它指定表记录应在 30 天后过期。
```
{
"status": "enabled",
"settings": {
"days": 30
{
}
```
要使用前述示例，请将 `user input placeholders` 替换为您自己的信息。
**警告**
确定表中记录的相应保留期限时，请注意，记录在过期后无法恢复。
要为表禁用记录过期，请为 `status` 字段指定 `disabled` 并在文件中省略 `settings` 对象。例如：
```
{
"status": "disabled"
}
```
创建包含要应用的设置的 JSON 文件后，运行 `put-table-record-expiration-configuration` 命令。对于 `table-arn` 参数，请指定表的 Amazon 资源名称（ARN）。对于 `value` 参数，请指定存储设置的文件的名称。
例如，以下命令更新表的记录过期设置。这些设置在名为 *`record-expiration-config.json`* 的文件中指定。
```
aws s3tables put-table-record-expiration-configuration \
--table-arn arn:aws:s3tables:us-east-1:123456789012:bucket/amzn-s3-demo-table-bucket/table/amzn-s3-demo-table \
--value file://./record-expiration-config.json
```
要使用前述示例，请将 `user input placeholders` 替换为您自己的信息。
## 监控表的记录过期
要监控 S3 表的记录过期操作的状态和结果，请使用 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_GetTableRecordExpirationJobStatus.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_GetTableRecordExpirationJobStatus.html) 操作，如果您使用 AWS CLI，则运行 [https://docs.aws.amazon.com/cli/latest/reference/s3tables/get-table-record-expiration-job-status.html](https://docs.aws.amazon.com/cli/latest/reference/s3tables/get-table-record-expiration-job-status.html) 命令。在请求中，指定表的 Amazon 资源名称（ARN）。
例如，以下 AWS CLI 命令检索表存储桶中特定表的记录过期操作的状态。要使用此示例，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables get-table-record-expiration-job-status \
--table-arn arn:aws:s3tables:us-east-1:123456789012:bucket/amzn-s3-demo-table-bucket/table/amzn-s3-demo-table
```
如果您的请求成功，则会收到一条响应，其中提供了详细信息，例如 Amazon S3 最近一次对表运行记录过期操作的时间以及该操作的状态。如果最近一次运行成功，则响应还包括处理指标，例如，删除的数据文件和记录的数量，以及删除数据的总大小。如果最近一次运行出错，则响应中会包含一条失败消息，说明运行失败的原因。
## 注意事项
在为 AWS 托管的 S3 表配置和管理记录过期设置时，请记住以下几点：
+ 记录过期仅可用于由支持的 AWS 服务（Amazon S3 Storage Lens 存储统计管理工具和 Amazon SageMaker 目录）创建的某些 AWS 托管的表。此外，记录过期仅可用于单个表，而不是整个表存储桶。
+ 为了确定记录何时过期，Amazon S3 使用表中的特定时间戳。这些时间戳表示数据的创建时间，而不是 Amazon S3 摄取表中记录的时间。使用的时间戳列取决于发布表的服务：对于 S3 Storage Lens 存储统计管理工具指标为 `report_time` 字段；对于 Amazon SageMaker 目录元数据为 `snapshot_time` 字段。您无法指定要使用哪个字段，因为这些表是由 AWS 管理的。
+ 如果将数据导出到表时出现延迟，则记录可能比您预期的更早达到过期条件。因此，我们建议您考虑潜在的摄取延迟，在表的过期设置中为保留期添加缓冲时间。
+ 记录会在达到过期条件后的 24 到 48 小时内过期并删除。Amazon S3 不会在记录达到过期条件后立即使记录过期并删除记录。
+ 记录在过期并被删除后无法恢复。
# 维护任务的注意事项和限制
Amazon S3 提供维护操作，以提高 S3 表或表存储桶的性能。这些选项为文件压缩、快照管理和未引用文件移除。以下是这些管理选项的限制和注意事项。
**Topics**
+ [压缩注意事项](#s3-tables-compaction-considerations)
+ [快照管理注意事项](#s3-tables-snapshot-considerations)
+ [未引用文件移除的注意事项](#s3-tables-unreferenced-file-removal-considerations)
+ [S3 表和表存储桶维护操作限制和相关 API](#s3-tables-maintenance-limits)
## 压缩注意事项
以下注意事项适用于压缩。有关压缩的更多信息，请参阅 [表维护](s3-tables-maintenance.md)。
+ 仅 Apache Parquet、Avro 和 ORC 文件类型支持压缩。
+ 默认情况下，压缩以 Apache Parquet 格式写入新文件。要改为将文件压缩为 Avro 或 ORC 格式，请将 `write.format.default` 表属性设置为 `avro` 或 `orc`。
+ 压缩不支持数据类型：`Fixed`。
+ 压缩不支持压缩类型：`brotli`、`lz4`。
+ 压缩按照自动时间表进行。如果您想要防止与压缩关联的费用，则可以使用 [PutTableMaintenanceConfiguration](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_PutTableMaintenanceConfiguration.html) API 操作手动为表禁用压缩功能。
**注意**
Apache Iceberg 使用乐观并发模型以及冲突检测来仲裁写入事务。使用乐观并发，用户和压缩事务可能会发生冲突，而导致事务失败。如果发生冲突，压缩任务将在失败时重试。建议您的管道也使用重试逻辑来解决因操作冲突而失败的事务。
## 快照管理注意事项
以下注意事项适用于快照管理。有关快照管理的更多信息，请参阅 [表维护](s3-tables-maintenance.md)。
+ 只有在同时满足以下两个条件时，才会保留快照：要保留的最小快照数量和指定的保留期。
+ 快照管理从 Apache Iceberg 中删除到期的快照元数据，从而防止对到期快照进行时空旅行查询，并选择性删除关联的数据文件。
+ 快照管理不支持您在 `metadata.json` 文件中或通过 `ALTER TABLE SET TBLPROPERTIES` SQL 命令配置为 Iceberg 表属性的保留值，包括基于分支或标签的保留。当您配置基于分支或标签的保留策略，或者在 `metadata.json` 文件上配置的保留策略长度超过通过 `PutTableMaintenanceConfiguration` API 配置的值时，快照管理将被禁用。在这些情况下，S3 不会使快照到期或移除快照，您需要手动删除快照或从 Iceberg 表中移除属性，以避免产生存储费用。
## 未引用文件移除的注意事项
以下注意事项适用于未引用文件移除。有关未引用文件移除的更多信息，请参阅 [表存储桶的维护](s3-table-buckets-maintenance.md)。
+ 未引用文件移除会删除 Iceberg 元数据不再引用的数据和元数据文件（如果其创建时间早于保留期）。
## S3 表和表存储桶维护操作限制和相关 API
| 维护操作 | 属性 | 是否可在表存储桶级进行配置？ | 是否可在表级进行配置？ | 默认值 | 最小值 | 相关的 Iceberg 维护例程 | 控制 S3 表类数据存储服务 API |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 压缩 | targetFileSizeMB | 否 | 是 | 512 MB | 64MB | [https://iceberg.apache.org/docs/latest/maintenance/#compact-data-files](https://iceberg.apache.org/docs/latest/maintenance/#compact-data-files) | [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableMaintenanceConfiguration.html) |
| 快照管理 | minimumSnapshots | 否 | 是 | 1 | 1 | [https://iceberg.apache.org/docs/latest/maintenance/#expire-snapshots](https://iceberg.apache.org/docs/latest/maintenance/#expire-snapshots) retainLast | [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableMaintenanceConfiguration.html) |
| 快照管理 | maximumSnapshotAge | 否 | 是 | 120 小时 | 1 小时 | [https://iceberg.apache.org/docs/latest/maintenance/#expire-snapshots](https://iceberg.apache.org/docs/latest/maintenance/#expire-snapshots) expireOlderThan | [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableMaintenanceConfiguration.html) |
| 未引用文件移除 | unreferencedDays | 是 | 否 | 3 天 | 1 天 | [https://iceberg.apache.org/docs/latest/maintenance/#delete-orphan-files](https://iceberg.apache.org/docs/latest/maintenance/#delete-orphan-files) | [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableBucketMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableBucketMaintenanceConfiguration.html) |
| 未引用文件移除 | nonCurrentDays | 是 | 否 | 10 天 | 1 天 | 不适用 | [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableBucketMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3tables_PutTableBucketMaintenanceConfiguration.html) |
**注意**
S3 表类数据存储服务应用的 parquets row-group-default 为 128 MB。
# 使用智能分层优化表成本
您可以使用 S3 Intelligent-Tiering 自动优化表的存储成本。S3 表类数据存储服务智能分层存储类别可在访问模式发生变化时，自动将数据移动到最经济实惠的访问层。当您使用 S3 Intelligent-Tiering 时，访问频率较低的数据会自动移至成本较低的层，当您再次访问时，这些数据会移回频繁访问层。
所有数据在各层之间移动时，不会产生检索费用、性能影响或可用性变化。此外，表维护操作（例如压缩）会根据访问模式进行优化，仅处理频繁访问层中有活跃访问的数据，同时降低成本较低层中较不频繁访问数据的维护成本。
**Topics**
+ [S3 表类数据存储服务智能分层访问层](#tables-intelligent-tiering-access-tiers)
+ [使用 S3 Intelligent-Tiering 的自动分层行为](#tables-intelligent-tiering-auto-tiering-behavior)
+ [将 S3 Intelligent-Tiering 指定为存储类别](#tables-intelligent-tiering-specifying-storage-class)
+ [监控存储使用情况](#tables-intelligent-tiering-monitoring-storage)
## S3 表类数据存储服务智能分层访问层
当表存储在 S3 Intelligent-Tiering 存储类别中时，Amazon S3 会持续监控访问模式并自动在访问层之间移动表数据。
分层操作发生在单个文件级别，因此根据访问模式，单个表中的文件可能会放在不同的层中。根据访问模式，表数据会自动移动到以下访问层之一：
+ **频繁访问**：所有文件的默认层。其他层中的文件在被访问时会自动移回频繁访问层。
+ **不频繁访问**：如果某个文件在连续 30 天内未被访问，就会移到不频繁访问层。
+ **归档即时访问**：如果某个文件在连续 90 天内未被访问，就会移到归档即时访问层。
所有层均提供毫秒延迟、高吞吐量性能，并且设计为具有 99.9% 的可用性和 99.999999999% 的持久性。
## 使用 S3 Intelligent-Tiering 的自动分层行为
以下操作构成了自动将文件从不频繁访问层或归档即时访问层移回频繁访问层的访问：
+ 使用 `GetObject`、`PutObject` 或 `CompleteMultipartUpload` 操作对表数据或元数据文件进行的任何读取或写入操作
+ 使用 [Iceberg REST API 操作](https://docs.aws.amazon.com//AmazonS3/latest/userguide/s3-tables-integrating-open-source.html#endpoint-supported-api)的 `LoadTable` 或 `UpdateTable` 操作
+ S3 表类数据存储服务复制操作
其他操作不构成自动将文件从不频繁访问层或归档即时访问层移回频繁访问层的访问。
**注意**
小于 128 KB 的文件不符合自动分层条件，仍会保留在频繁访问层中。通过压缩可以将这些文件合并成更少、更大的对象，然后将它们作为新快照提交回表中。如果新压缩的文件大于 128 KB 甚至更大，就符合对新文件自动分层的条件。
### 表维护行为
Amazon S3 自动执行的表维护操作（例如快照管理、未引用文件移除和记录过期）将继续在您的表上运行，不受分层的影响。压缩操作仅对频繁访问层中的文件运行，这样即可以优化频繁访问数据的性能，又可以降低成本较低层中数据的维护成本。
维护操作不会影响表中文件所处的访问层。维护操作执行的读取不会导致文件更改所处的层。不过，如果维护操作（例如压缩或记录过期）写入了新文件，则会在频繁访问层中创建该文件。
**注意**
由于压缩仅处理频繁访问层中的文件，因此在成本较低层的中，对数据执行删除操作所创建的删除文件不会被自动压缩。当与删除文件关联的数据文件被访问并移回频繁访问层时，这些删除文件就符合压缩的条件。对于不经常访问的表，您可以使用 Amazon EMR 手动执行压缩来压缩这些删除文件以及与其关联的数据文件。有关更多信息，请参阅[使用压缩来维护表](https://docs.aws.amazon.com//prescriptive-guidance/latest/apache-iceberg-on-aws/best-practices-compaction.html#compaction-emr-glue)。您可以使用 Amazon CloudWatch 指标监控表中的文件增长情况，来确定什么时候进行手动压缩能够带来好处。
## 将 S3 Intelligent-Tiering 指定为存储类别
默认情况下，所有表都在 S3 Standard 存储类别中创建，无法移动到 S3 Intelligent-Tiering 中。要使用 S3 Intelligent-Tiering，您必须在创建表时指定它。您还可以将 S3 Intelligent-Tiering 设置为表存储桶的默认存储类别，这样就可以将在存储桶中创建的任何新表自动存储为 S3 Intelligent-Tiering 存储类别。
### 为表存储桶指定 S3 Intelligent-Tiering
在创建新表存储桶时，您可以通过在操作 `CreateTableBucket` 中使用 `storage-class-configuration` 标头，将 S3 Intelligent-Tiering 指定为默认存储类别。
要检查现有表存储桶的默认存储类别，请使用 `GetTableBucketStorageClass` 操作。要修改现有表存储桶的默认存储类别，请使用 `PutTableBucketStorageClass` 操作。
**注意**
当您修改表存储桶的默认存储类别时，该设置仅应用到在该存储桶中创建的新表。现有表的存储类别不会更改。
### 为表指定 S3 Intelligent-Tiering
在创建新表时，您可以通过在操作 `CreateTable` 中使用 `storage-class-configuration` 标头，将 S3 Intelligent-Tiering 指定为存储类别。
如果您在创建表时未指定存储类别，则将使用表存储桶上当时配置的默认存储类别来创建表。表在创建之后，无法修改其存储类别。
要检查现有表存储桶的默认存储类别，请使用 `GetTableBucketStorageClass` 操作。
## 监控存储使用情况
您可以在账户的 AWS 成本和使用情况报告中，按访问层查看存储使用情况明细。有关更多信息，请参阅《AWS Data Exports 用户指南》**中的[创建成本和使用情况报告](https://docs.aws.amazon.com//cur/latest/userguide/creating-cur.html)。
您的账单报告中包含以下使用类型：
| 使用类型 | 单位 | 粒度 | 说明 |
| --- | --- | --- | --- |
| region-Tables-TimedStorage-INT-FA-ByteHrs | GB-月 | 每天 | 在 S3 Intelligent-Tiering 存储中，存储在 S3 Intelligent-Tiering 频繁访问层中数据的 GB-月数 |
| region-Tables-TimedStorage-INT-IA-ByteHrs | GB-月 | 每天 | 在 S3 Intelligent-Tiering 存储中，存储在 S3 Intelligent-Tiering 不频繁访问层中数据的 GB-月数 |
| region-Tables-TimedStorage-INT-AIA-ByteHrs | GB-月 | 每天 | 在 S3 Intelligent-Tiering 存储中，存储在 S3 Intelligent-Tiering 归档即时访问层中数据的 GB-月数 |
| region-Tables-Requests-INT-Tier1 | 计数 | 每小时 | 对 S3 表类数据存储服务智能分层对象的 PUT、COPY 或 POST 请求的数量 |
| region-Tables-Requests-INT-Tier2 | 计数 | 每小时 | 对 S3 表类数据存储服务智能分层对象的 GET 和所有其他非 Tier1 请求的数量 |
# 表命名空间
在 Amazon S3 表存储桶中创建表时，可以将它们组织成称为*命名空间*的逻辑分组。与 S3 表和表存储桶不同，命名空间不是资源。命名空间是有助于您以可扩展的方式组织和管理表的构造。例如，公司中属于人力资源部门的所有表都可以分组到一个公共命名空间值 `hr` 下。
要控制对特定命名空间的访问权限，可以使用表存储桶资源策略。有关更多信息，请参阅 [S3 表类数据存储服务的基于资源的策略](s3-tables-resource-based-policies.md)。
以下规则适用于表命名空间：
+ 每个命名空间在表存储桶内都必须是唯一的。
+ 您可以为每个表存储桶创建最多 10000 个命名空间。
+ 每个表名称在命名空间内都必须是唯一的。
+ 每个表只能有一个级别的命名空间。命名空间不能嵌套。
+ 每个表都属于单个命名空间。
+ 您可以在命名空间之间移动表。
表命名空间在各种 AWS 服务和查询引擎中称为数据库。下表将 S3 表类数据存储服务命名空间使用的术语映射到一些常见的引擎和服务。
| **服务或引擎** | **术语**： |
| --- | --- |
| AWS Lake Formation | 数据库 |
| AWS Glue Data Catalog | 数据库 |
| Athena | 数据库 |
| Spark | 命名空间 |
**Topics**
+ [创建命名空间](s3-tables-namespace-create.md)
+ [删除命名空间](s3-tables-namespace-delete.md)
# 创建命名空间
表命名空间是在 Amazon S3 表存储桶中对表进行分组的逻辑构造。每个表都属于单个命名空间。在表存储桶中创建表之前，必须创建一个命名空间来对表进行分组。可以使用 Amazon S3 控制台、AWS Command Line Interface（AWS CLI）、Amazon S3 REST API、AWS SDK 或集成查询引擎创建命名空间。
**命名空间名称**
以下命名规则适用于命名空间：
+ 名称长度必须介于 1 到 255 个字符之间。
+ 名称只能由小写字母、数字和下划线 (`_`) 组成。命名空间名称的开头或结尾不支持使用下划线。
+ 名称必须以字母或数字开头和结尾。
+ 名称不得包含连字符 (`-`) 或句点 (`.`)。
+ 命名空间在表存储桶中必须是唯一的。
+ 命名空间名称不得以保留前缀 `aws` 开头。
有关有效命名空间名称的更多信息，请参阅[表和命名空间的命名规则](s3-tables-buckets-naming.md#naming-rules-table)。
## 使用 S3 控制台和 Amazon Athena
以下过程通过**使用 Athena 创建表**工作流程在 Amazon S3 控制台中创建命名空间。如果您不想同时使用 Amazon Athena 在命名空间中创建表，则可以在创建命名空间后取消该工作流程。
**创建命名空间**
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在**表存储桶**页面上，选择要在其中创建命名空间的存储桶。
1. 在存储桶详细信息页面上，选择**使用 Athena 创建表**。
1. 在**使用 Athena 创建表**对话框中，选择**创建命名空间**，然后选择**创建命名空间**。
1. 在**命名空间名称**字段中输入名称。命名空间名称必须为 1 到 255 个字符，并且在表存储桶中是唯一的。有效字符为 a–z、0–9 和下划线 (`_`)。命名空间名称的开头或结尾不支持使用下划线。
1. 选择**创建命名空间**。
1. 如果您还想创建表，请选择**使用 Athena 创建表**。有关使用 Athena 创建表的更多信息，请参阅[使用 S3 控制台和 Amazon Athena](s3-tables-create.md#create-table-console)。如果您不想立即创建表，请选择**取消**。
## 使用 AWS CLI
此示例说明如何使用 AWS CLI 创建表命名空间。要使用此示例，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables create-namespace \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1 \
--namespace example_namespace
```
## 使用查询引擎
您可以在连接到 Amazon S3 表存储桶的 Apache Spark 会话中创建命名空间。
此示例向您展示如何在与 S3 表类数据存储服务集成的查询引擎中使用 `CREATE` 语句来创建表。要使用此示例，请将*用户输入占位符* 替换为您自己的信息。
```
spark.sql("CREATE NAMESPACE IF NOT EXISTS s3tablesbucket.my_namespace")
```
# 删除命名空间
在从 Amazon S3 表存储桶中删除表命名空间之前，必须删除该命名空间中的所有表，或者将它们移到另一个命名空间下。可以使用 Amazon S3 REST API、AWS SDK、AWS Command Line Interface（AWS CLI）或集成查询引擎来删除命名空间。
有关删除命名空间所需的权限的信息，请参阅《Amazon Simple Storage Service API Reference》**中的 [https://docs.aws.amazon.com//AmazonS3/latest/API/API_s3TableBuckets_DeleteNamespace.html](https://docs.aws.amazon.com//AmazonS3/latest/API/API_s3TableBuckets_DeleteNamespace.html)。
## 使用 AWS CLI
此示例说明如何使用 AWS CLI 删除表命名空间。要使用此示例，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables delete-namespace \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1 \
--namespace example_namespace
```
# S3 表存储桶中的表
S3 表表示由基础表数据和相关元数据组成的结构化数据集。该数据作为子资源存储在表存储桶中。表存储桶中的所有表均以 [Apache Iceberg](https://iceberg.apache.org/docs/latest/) 表格式存储。Amazon S3 通过自动文件压缩和快照管理来管理表的维护。有关更多信息，请参阅 [表维护](s3-tables-maintenance.md)。
要使 AWS 分析服务可以访问您账户中的表，您可以将 Amazon S3 表存储桶与 Amazon SageMaker 智能湖仓集成。这种集成支持 Amazon Athena 和 Amazon Redshift 等 AWS 分析服务自动发现和访问您的表数据。
创建表时，Amazon S3 会自动为表生成仓库位置。这是一个唯一的 S3 位置，用于存储与表关联的对象。以下示例显示了仓库位置的格式：
```
s3://63a8e430-6e0b-46f5-k833abtwr6s8tmtsycedn8s4yc3xhuse1b--table-s3
```
在表存储桶中，可以将表组织成称为命名空间的逻辑分组。有关更多信息，请参阅 [表命名空间](s3-tables-namespace.md)。
您可以重命名表，但每个表都有自己唯一的 Amazon 资源名称（ARN）和唯一的表 ID。每个表还附加了资源策略。可以使用此策略来管理对表的访问权限。
表 ARN 使用以下格式：
```
arn:aws:s3tables:region:owner-account-id:bucket/bucket-name/table/table-id
```
默认情况下，您可以在表存储桶中创建多达 10000 个表。要请求增加表存储桶或表的配额，请联系 [支持](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)。
Amazon S3 在表存储桶中支持以下类型的表：
**客户表**
客户表是您可以读取和写入的表。您可以使用集成的查询引擎从这些表中检索数据。您可以使用 S3 API 操作或集成的查询引擎在其中插入、更新或删除数据。
**AWS 表**
AWS 表是由 AWS 服务 代表您生成的只读表。这些表由 Amazon S3 管理，而不能由 Amazon S3 本身以外的任何 IAM 主体进行修改。您可以从这些表中检索信息，但无法修改表中的数据。AWS 表包括 S3 元数据表，其中包含从 S3 通用存储桶内的对象中捕获的元数据。有关更多信息，请参阅 [使用 S3 元数据表发现您的数据](metadata-tables-overview.md)。
**Topics**
+ [创建 Amazon S3 表](s3-tables-create.md)
+ [删除 Amazon S3 表](s3-tables-delete.md)
+ [查看有关 Amazon S3 表的详细信息](s3-tables-table-details.md)
+ [管理表策略](s3-tables-table-policy.md)
+ [将标签与 S3 表结合使用](table-tagging.md)
# 创建 Amazon S3 表
Amazon S3 表是表存储桶的子资源。表以 Apache Iceberg 格式存储，以便您通过使用查询引擎和其它支持 Apache Iceberg 的应用程序来处理这些表。Amazon S3 会持续优化表，以有助于降低存储成本并提高分析查询性能。
创建表时，Amazon S3 会自动为表生成*仓库位置*。仓库位置是一个唯一的 S3 位置，您可以在其中读取和写入与表关联的对象。以下示例显示了仓库位置的格式：
```
s3://63a8e430-6e0b-46f5-k833abtwr6s8tmtsycedn8s4yc3xhuse1b--table-s3
```
表具有以下 Amazon 资源名称（ARN）格式：
```
arn:aws:s3tables:region:owner-account-id:bucket/bucket-name/table/table-id
```
默认情况下，您可以在表存储桶中创建多达 10000 个表。要请求增加表存储桶或表的配额，请联系 [支持](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)。
可以使用 Amazon S3 控制台、Amazon S3 REST API、AWS SDK、AWS Command Line Interface（AWS CLI）或连接到表存储桶的查询引擎来创建表。
创建表时，您可以为该表指定加密设置，除非您使用 Athena 创建表。如果您未指定加密设置，则将使用表存储桶的默认设置对表进行加密。有关更多信息，请参阅 [为表指定加密](s3-tables-kms-specify.md#specify-kms-table)。
**创建表的先决条件**
要创建表，首先必须执行以下操作：
+ [创建表存储桶](s3-tables-buckets-create.md).
+ 在表存储桶中[创建命名空间](s3-tables-namespace-create.md)。
+ 确保您对 `s3tables:CreateTable` 和 `s3tables:PutTableData` 具有 AWS Identity and Access Management（IAM）权限。
+
**注意**
如果您对表使用 SSE-KMS 加密，则需要对 `s3tables:PutTableEncryption` 拥有权限，并对所选 AWS KMS 密钥拥有 `DescribeKey` 权限。此外，您使用的 AWS KMS 密钥需要向 S3 表类数据存储服务授予执行自动表维护的权限。有关更多信息，请参阅 [S3 表类数据存储服务 SSE-KMS 加密的权限要求](s3-tables-kms-permissions.md)。
有关有效表名称的信息，请参阅[表和命名空间的命名规则](s3-tables-buckets-naming.md#naming-rules-table)。
**重要**
创建表时，请确保在表名称和表定义中全部使用小写字母。例如，请确保列名称全部为小写。如果表名称或表定义包含大写字母，则 AWS Lake Formation 或 AWS Glue Data Catalog 不支持该表。在这种情况下，Amazon Athena 等 AWS 分析服务将无法看到您的表，即使表存储桶与 AWS 分析服务集成，也不例外。
如果表定义包含大写字母，则在 Athena 中运行 `SELECT` 查询时会收到以下错误消息：“GENERIC\$1INTERNAL\$1ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names.”
## 使用 S3 控制台和 Amazon Athena
以下过程使用 Amazon S3 控制台通过 Amazon Athena 来创建表。如果您尚未在表存储桶中创建命名空间，则可以在此过程中创建命名空间。在执行以下步骤之前，请确保您已在此区域中将表存储桶与 AWS 分析服务集成。有关更多信息，请参阅 [将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
**注意**
当您使用 Athena 创建表时，该表将从表存储桶继承默认加密设置。如果要使用不同的加密类型，则需要使用另一种方法创建表。
**创建表**
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在**表存储桶**页面上，选择要在其中创建表的存储桶。
1. 在存储桶详细信息页面上，选择**使用 Athena 创建表**。
1. 在**使用 Athena 创建表**对话框中，执行下列操作之一：
+ 创建新的命名空间。选择**创建命名空间**，然后在**命名空间名称**字段中输入名称。命名空间名称必须为 1 到 255 个字符，并且在表存储桶中是唯一的。有效字符为 a–z、0–9 和下划线 (`_`)。命名空间名称的开头不支持使用下划线。
+ 选择 **Create namespace (创建命名空间)**。
+ 指定现有的命名空间。选择**指定此表存储桶中的现有命名空间**。然后选择**从现有命名空间中选择**或**输入现有命名空间名称**。如果存储桶中有超过 1000 个命名空间，则当命名空间名称未出现在列表中时，必须输入该名称。
1. 选择**使用 Athena 创建表**。
1. Amazon Athena 控制台将打开，并出现 Athena 查询编辑器。**目录**字段中应填充 **s3tablescatalog/**，后跟表存储桶的名称，例如 **s3tablescatalog/*amzn-s3-demo-bucket***。**数据库**字段中应填充您之前创建或选择的命名空间。
**注意**
如果您在**目录**和**数据库**字段中看不到这些值，请确保您已在该区域中将表存储桶与 AWS 分析服务集成。有关更多信息，请参阅 [将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
1. 查询编辑器中填充了一个可用于创建表的示例查询。修改此查询，以指定您希望表具有的表名称和列。
1. 修改完查询后，选择**运行**来创建表。
**注意**
如果您在尝试在 Athena 中运行查询时收到错误“权限不足，无法执行查询。主体对指定的资源没有任何权限”，则必须向您授予对于表的必需 Lake Formation 权限。有关更多信息，请参阅 [授予对表或数据库的 Lake Formation 权限](grant-permissions-tables.md#grant-lf-table)。
如果您在尝试在 Athena 中运行查询时收到错误“Iceberg 无法访问所请求的资源”，请转到 AWS Lake Formation 控制台，并确保您已授予自己对您创建的表存储桶目录和数据库（命名空间）的权限。授予这些权限时请勿指定表。有关更多信息，请参阅 [授予对表或数据库的 Lake Formation 权限](grant-permissions-tables.md#grant-lf-table)。
如果在 Athena 中运行 `SELECT` 查询时收到以下错误消息，则此消息是由表名称中或表定义的列名称中具有大写字母而引起的：“GENERIC\$1INTERNAL\$1ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names.” 确保表名称和列名称全部为小写。
如果表创建取得成功，则新表的名称将显示在 Athena 中的表列表中。当您导航回 Amazon S3 控制台时，刷新列表后，新表将出现在表存储桶的存储桶详细信息页面上的**表**列表中。
## 使用 AWS CLI
此示例展示了如何使用 AWS CLI 并使用 JSON 指定表元数据，来通过架构创建表。要使用此示例，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables create-table --cli-input-json file://mytabledefinition.json
```
对于 `mytabledefinition.json` 文件，请使用以下示例表定义。要使用此示例，请将 `user input placeholders` 替换为您自己的信息。
```
{
"tableBucketARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket",
"namespace": "your_namespace",
"name": "example_table",
"format": "ICEBERG",
"metadata": {
"iceberg": {
"schema": {
"fields": [
{"name": "id", "type": "int","required": true},
{"name": "name", "type": "string"},
{"name": "value", "type": "int"}
]
}
}
}
}
```
## 使用查询引擎
您可以在连接到表存储桶的受支持的查询引擎中创建表，例如在 Amazon EMR 上的 Apache Spark 会话中。
以下示例说明如何通过 Spark 使用 `CREATE` 语句创建表，以及如何使用 `INSERT` 语句或从现有文件中读取数据来添加表数据。要使用此示例，请将 `user input placeholders` 替换为您自己的信息。
```
spark.sql(
" CREATE TABLE IF NOT EXISTS s3tablesbucket.example_namespace.`example_table` (
id INT,
name STRING,
value INT
)
USING iceberg "
)
```
创建表后，可以将数据加载到表中。从以下方法中进行选择：
+ 使用 `INSERT` 语句向表中添加数据。
```
spark.sql(
"""
INSERT INTO s3tablesbucket.my_namespace.my_table
VALUES
(1, 'ABC', 100),
(2, 'XYZ', 200)
""")
```
+ 加载现有的数据文件。
1. 将数据读入 Spark：
```
val data_file_location = "Path such as S3 URI to data file"
val data_file = spark.read.parquet(data_file_location)
```
1. 将数据写入 Iceberg 表：
```
data_file.writeTo("s3tablesbucket.my_namespace.my_table").using("Iceberg").tableProperty ("format-version", "2").createOrReplace()
```
# 删除 Amazon S3 表
可以使用 Amazon S3 REST API、AWS SDK、AWS Command Line Interface（AWS CLI）或使用集成查询引擎来删除表。
**注意**
S3 表类数据存储服务不支持 `purge=false` 的 `DROP TABLE` 操作。某些版本的 Apache Spark 始终将此标志设置为 `false`，即使在运行 `DROP TABLE PURGE` 命令时也是如此。要删除表，您可以使用 `purge=true` 重试 `DROP TABLE`，或者使用 S3 表类数据存储服务 [https://docs.aws.amazon.com//AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html](https://docs.aws.amazon.com//AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html) REST API 操作。
**重要**
删除表时，需要了解以下事项：
删除表是永久性的，无法撤消。在删除表之前，请确保您已备份或复制所有重要数据。
与表关联的所有数据和配置都将永久移除。
## 使用 AWS CLI
此示例说明如何使用 AWS CLI 删除表。要使用此命令，请将 `user input placeholders` 替换为您自己的信息。
```
aws s3tables delete-table \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--namespace example_namespace --name example_table
```
## 使用查询引擎
您可以在连接到 Amazon S3 表存储桶的 Apache Spark 会话中删除表。
此示例说明如何使用 `DROP TABLE PURGE` 命令来删除表。要使用此命令，请将 `user input placeholders` 替换为您自己的信息。
```
spark.sql(
" DROP TABLE [IF EXISTS] s3tablesbucket.example_namespace.example_table PURGE")
```
# 查看有关 Amazon S3 表的详细信息
您可以在控制台中或以编程方式查看表存储桶中表的一般详细信息，例如创建详细信息、格式和类型。您可以使用 S3 表类数据存储服务 REST API、AWS CLI 或 AWS SDK，以编程方式查看表加密设置和维护设置。
## 查看表详细信息
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 获取有关表的详细信息。要使用此示例，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables get-table --table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket --namespace my-namespace --name my-table
```
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择表存储桶，然后选择表。
1. 选择**属性**选项卡。
1. （可选）有关附加到表的权限策略的信息，请选择**权限**。
## 预览表数据
### 使用 S3 控制台
您可以利用以下过程从 Amazon S3 控制台直接预览表中的数据。
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在**表存储桶**页面上，选择包含要查询的表的存储桶。
1. 选择要预览的表，然后选择**预览**。
**注意**
预览显示表的前 10 行和最多 25 列。无法预览超过 50 mb 的表。
## 加密详细信息
有关表存储桶加密的更多信息，请参阅[在表存储桶中使用具有 AWS KMS 密钥的服务器端加密（SSE-KMS）](s3-tables-kms-encryption.md)。
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 来获取有关表的加密设置的详细信息。要使用此示例，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables get-table-encryption --table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket --namespace my-namespace --name my-table
```
## 维护详细信息
有关维护设置的信息，请参阅[表存储桶的维护](s3-table-buckets-maintenance.md)
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 来获取有关表的维护配置设置的详细信息。要使用此示例，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables get-table-maintenance-configuration --table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket --namespace my-namespace --name my-table
```
# 管理表策略
可以使用 Amazon S3 控制台、Amazon S3 REST API、AWS SDK 和 AWS CLI 来添加、删除、更新和查看表的表策略。有关更多信息，请参阅以下主题。有关 Amazon S3 表类数据存储服务支持的 AWS Identity and Access Management（IAM）操作和条件键的更多信息，请参阅 [S3 表类数据存储服务的访问管理](s3-tables-setting-up.md)。有关示例表策略，请参阅 [S3 表类数据存储服务的基于资源的策略](s3-tables-resource-based-policies.md)。
## 添加表策略
要向表添加表策略，可以使用 Amazon S3 REST API、AWS SDK 和 AWS CLI。
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 查看附加到表的策略。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables get-table-policy \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1/table/tableID \
--namespace my-namespace \
--name my-table
```
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择 **Amazon S3**。
1. 选择**表存储桶**并选择包含表的表存储桶名称，然后从该存储桶中选择您的表。
1. 选择 **Permissions（权限）**选项卡。
1. 在**表策略**下，选择**编辑**。
1. 在策略编辑器中，输入策略 JSON。
1. （可选）选择**策略示例**以查看可以根据需要调整的示例策略。
1. 输入您的策略后，选择**保存更改**。
## 查看表策略
要查看附加到表的存储桶策略，可以使用 Amazon S3 REST API、AWS SDK 和 AWS CLI。
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 查看附加到表的策略。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables get-table-policy \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--namespace my-namespace \
--name my-table
```
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择 **Amazon S3**。
1. 选择**表存储桶**并选择包含表的表存储桶名称，然后从该存储桶中选择您的表。
1. 选择 **Permissions（权限）**选项卡。
## 删除表策略
要删除附加到表的策略，可以使用 Amazon S3 REST API、AWS SDK 和 AWS CLI。
### 使用 AWS CLI
此示例说明如何使用 AWS CLI 删除表策略。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables delete-table-policy \
--table-ARN arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--namespace your-namespace \
--name your-table
```
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择 **Amazon S3**。
1. 选择**表存储桶**并选择包含表的表存储桶名称，然后从该存储桶中选择您的表。
1. 选择 **Permissions（权限）**选项卡。
1. 在**表存储桶策略**下，选择**删除**。
# 将标签与 S3 表结合使用
AWS 标签是用于保存有关资源（在本例中为 Amazon S3 表）的元数据的键值对。您可以在创建 S3 表时为其添加标签，也可以管理现有表上的标签。有关标签的一般信息，请参阅[添加标签以进行成本分配或基于属性的访问权限控制（ABAC）](tagging.md)。
**注意**
在表上使用标签时，除了标准 S3 API 请求费率之外，没有任何其他费用。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)。
## 将标签与表结合使用的常用方法
使用 S3 表上的标签来执行以下操作：
1. **成本分配**：在 AWS 账单与成本管理中按表标签跟踪存储成本。有关更多信息，请参阅 [Using tags for cost allocation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/tagging.html#using-tags-for-cost-allocation)。
1. **基于属性的访问权限控制（ABAC）**：根据 S3 表的标签扩展访问权限并授予这些表的访问权限。有关更多信息，请参阅 [Using tags for ABAC](https://docs.aws.amazon.com/AmazonS3/latest/userguide/tagging.html#using-tags-for-abac)。
**注意**
您可以将相同的标签同时用于成本分配和访问权限控制。
### 适用于 S3 表的 ABAC
Amazon S3 表支持使用标签进行基于属性的访问权限控制（ABAC）。请在您的 AWS Organizations、AWS Identity and Access Management（IAM）和 S3 表策略中使用基于标签的条件键。Amazon S3 中的 ABAC 支持跨多个 AWS 账户进行授权。
在您的 IAM 策略中，您可以使用 `s3tables:TableBucketTag/tag-key` 条件键或 [AWS 全局条件键](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-tagkeys) `aws:ResourceTag/key-name`、`aws:RequestTag/key-name` 或 `aws:TagKeys`，根据表的标签控制对 S3 表的访问。
#### aws:ResourceTag/key-name
使用此条件键可将您在策略中指定的标签键值对与附加到资源的键值对进行比较。例如，您可能会要求仅在表具有标签键 `Department` 和值 `Marketing` 时才允许访问该表。
此条件键将应用于使用 Amazon S3 控制台、AWS 命令行界面（CLI）、S3 API 或 AWS SDK 执行的表操作。
有关策略示例，请参阅 [1.1：用于使用标签限制对表的操作的表策略](#example-policy-table-resource-tag)。
有关更多示例策略和信息，请参阅《AWS Identity and Access Management 用户指南》**中的[控制对 AWS 资源的访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-resources)。
**注意**
对于对表执行的操作，此条件键将对应用于表的标签起作用，而非应用于包含该表的表存储桶的标签。如果您希望 ABAC 策略在您执行表操作时对表存储桶的标签起作用，请改用 `s3tables:TableBucketTag/tag-key`。
#### aws:RequestTag/key-name
使用此条件键可将请求中传递的标签键值对与您在策略中指定的标签对进行比较。例如，您可以检查为表添加标签的请求是否包含标签键 `Department` 并具有值 `Accounting`。
在 `TagResource` 或 `CreateTable` API 操作请求中传递标签键时，或者使用 Amazon S3 控制台、AWS 命令行界面（CLI）或 AWS SDK 标记或创建带有标签的表时，此条件键适用。
有关策略示例，请参阅 [1.2：用于创建或修改具有特定标签的表的 IAM 策略](#example-policy-table-request-tag)。
有关更多示例策略和信息，请参阅《AWS Identity and Access Management 用户指南》**中的[在 AWS 请求期间控制访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-requests)。
#### aws:TagKeys
使用此条件键可将请求中的标签键与您在策略中指定的键进行比较，从而定义允许用于访问操作的标签键。例如，要允许在 `CreateTable` 操作期间添加标签，必须创建一个同时允许 `s3tables:TagResource` 和 `s3tables:CreateTable` 操作的策略。然后，您可以使用 `aws:TagKeys` 条件键来强制仅在 `CreateTable` 请求中使用特定标签。
在 `TagResource`、`UntagResource` 或 `CreateTable` API 操作中传递标签键时，或者使用 AWS 命令行界面（CLI）或 AWS SDK 来标记、取消标记或创建带有标签的表时，此条件键适用。
有关策略示例，请参阅 [1.3：用于控制对现有资源上的标签的修改以保持标签治理的 IAM 策略](#example-policy-table-tag-keys)。
有关更多示例策略和更多信息，请参阅《AWS Identity and Access Management 用户指南》**中的[根据标签键控制访问](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys)。
#### s3tables:TableBucketTag/tag-key
使用此条件键可通过标签授予对表存储桶中特定数据的权限。此条件键主要作用于针对所有 S3 表操作分配给表存储桶的标签。即使在您创建带有标签的表时，此条件键也会对应用于包含该表的表存储桶的标签起作用。下面是一些例外情况：
+ 当您创建带有标签的表存储桶时，此条件键会对请求中的标签起作用。
有关策略示例，请参阅 [1.4：使用 s3tables:TableBucketTag 条件键](#example-policy-table-bucket-tag-tables)。
#### 适用于表的示例 ABAC 策略
请参阅以下适用于 Amazon S3 表的示例 ABAC 策略。
**注意**
如果您拥有基于 IAM 或 S3 表类数据存储服务资源的策略来根据主体标签限制 IAM 用户和 IAM 角色，则必须将相同的主体标签附加到 Lake Formation 用来访问 Amazon S3 数据的 IAM 角色（例如，LakeFormationDataAccessRole），并为该角色授予必要的权限。这是基于标签的访问控制策略与 S3 表类数据存储服务分析集成正常协同工作所必需的。
##### 1.1：用于使用标签限制对表的操作的表策略
在此表策略中，指定的 IAM 主体（用户和角色）仅在表的 `project` 标签的值与主体的 `project` 标签的值匹配时，才能执行 `GetTable` 操作。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowGetTable",
"Effect": "Allow",
"Principal": {
"AWS": "111122223333"
},
"Action": "s3tables:GetTable",
"Resource": "arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/my_example_tab;e",
"Condition": {
"StringEquals": {
"aws:ResourceTag/project": "${aws:PrincipalTag/project}"
}
}
}
]
}
```
##### 1.2：用于创建或修改具有特定标签的表的 IAM 策略
在此 IAM 策略中，具有此策略的用户或角色仅在以下情况下才能创建 S3 表：他们在表创建请求中使用标签键 `project` 和标签值 `Trinity` 为表添加标签。他们还可以在现有 S3 表上添加或修改标签，前提是 `TagResource` 请求包含标签键值对 `project:Trinity`。此策略不授予对表或其对象的读取、写入或删除权限。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "CreateTableWithTags",
"Effect": "Allow",
"Action": [
"s3tables:CreateTable",
"s3tables:TagResource"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:RequestTag/project": [
"Trinity"
]
}
}
}
]
}
```
##### 1.3：用于控制对现有资源上的标签的修改以保持标签治理的 IAM 策略
在此 IAM 策略中，IAM 主体（用户或角色）仅在表的 `project` 标签的值与主体的 `project` 标签的值匹配时，才能修改表上的标签。对于这些表，只允许使用在 `aws:TagKeys` 条件键中指定的四个标签 `project`、`environment`、`owner` 和 `cost-center`。这有助于强制执行标签治理，防止未经授权修改标签，并使标签架构跨表保持一致。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EnforceTaggingRulesOnModification",
"Effect": "Allow",
"Action": [
"s3tables:TagResource",
"s3tables:UntagResource"
],
"Resource": "arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/my_example_table",
"Condition": {
"StringEquals": {
"aws:ResourceTag/project": "${aws:PrincipalTag/project}"
},
"ForAllValues:StringEquals": {
"aws:TagKeys": [
"project",
"environment",
"owner",
"cost-center"
]
}
}
}
]
}
```
##### 1.4：使用 s3tables:TableBucketTag 条件键
在此 IAM 策略中，条件语句仅在表存储桶具有标签键 `Environment` 和标签值 `Production` 时，才支持访问表存储桶的数据。`s3tables:TableBucketTag/` 与 `aws:ResourceTag/` 条件键不同，因为除了根据标签控制对表存储桶的访问外，它还支持根据父表存储桶上的标签控制对表的访问。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowAccessToSpecificTables",
"Effect": "Allow",
"Action": "*",
"Resource": "arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/*",
"Condition": {
"StringEquals": {
"s3tables:TableBucketTag/Environment": "Production"
}
}
}
]
}
```
## 管理表的标签
您可以使用 Amazon S3 控制台、AWS 命令行界面（CLI）、AWS SDK 或以下 S3 API 为 S3 表添加或管理标签：[TagResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_TagResource.html)、[UntagResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_UntagResource.html) 和 [ListTagsForResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_ListTagsForResource.html)。有关更多信息，请参阅：
**Topics**
+ [将标签与表结合使用的常用方法](#common-ways-to-use-tags-table)
+ [管理表的标签](#table-working-with-tags)
+ [创建带有标签的表](table-create-tag.md)
+ [向表添加标签](table-tag-add.md)
+ [查看表标签](table-tag-view.md)
+ [从表删除标签](table-tag-delete.md)
# 创建带有标签的表
您可以在创建 Amazon S3 表时为其添加标签。在表上使用标签时，除了标准 S3 API 请求费率之外，没有任何其他费用。有关更多信息，请参阅 [Amazon S3 定价](https://aws.amazon.com/s3/pricing/)。有关为表添加标签的更多信息，请参阅[将标签与 S3 表结合使用](table-tagging.md)。
## 权限
要创建带有标签的表，您必须具有以下权限：
+ `s3tables:CreateTable`
+ `s3tables:TagResource`
## 错误故障排除
如果您在尝试创建带有标签的表时遇到错误，可以执行以下操作：
+ 验证您是否具有创建表并向其应用标签所需的[权限](#table-create-tag-permissions)。
+ 检查 IAM 用户策略，了解是否存在任何基于属性的访问权限控制（ABAC）条件。您的策略可能要求您仅使用特定的标签键和值为表添加标签。有关 ABAC 和示例表 ABAC 策略的更多信息，请参阅[适用于 S3 表的 ABAC](https://docs.aws.amazon.com/AmazonS3/latest/userguide/table-tagging.html#abac-for-tables)。
## Steps
您可以使用 AWS Command Line Interface（AWS CLI）、Amazon S3 表类数据存储服务 REST API 和 AWS SDK 来创建应用了标签的表。
## 使用 REST API
有关 Amazon S3 表类数据存储服务 REST API 支持创建带有标签的表的相关信息，请参阅《Amazon Simple Storage Service API 参考》**中的以下部分：
+ [CreateTable](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_CreateTable.html)
## 使用 AWS CLI
要安装 AWS CLI，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
以下 CLI 示例说明如何使用 AWS CLI 创建带有标签的表。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
创建表时，必须提供配置详细信息。有关更多信息，请参阅 [创建 Amazon S3 表](s3-tables-create.md)。您还必须使用符合表命名约定的名称来命名表。有关更多信息，请参阅 [Amazon S3 表存储桶、表和命名空间命名规则](s3-tables-buckets-naming.md)。
**请求**
```
aws --region us-west-2 \
s3tables create-table \
--endpoint https://ufwae60e2k.execute-api.us-west-2.amazonaws.com/personal/ \
--table-bucket-arn arn:aws:s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket
--tags '{"Department":"Engineering"}' \
--name my_table_abc \
--namespace my_namesapce_123a \
--format ICEBERG
```
# 向表添加标签
您可以向 Amazon S3 表添加标签并修改这些标签。有关为表添加标签的更多信息，请参阅[将标签与 S3 表结合使用](table-tagging.md)。
## 权限
要向表添加标签，您必须具有以下权限：
+ `s3tables:TagResource`
## 错误故障排除
如果您在尝试向表添加标签时遇到错误，可以执行以下操作：
+ 验证您是否具有向表添加标签所需的[权限](#table-tag-add-permissions)。
+ 如果您尝试添加以 AWS 保留前缀 `aws:` 开头的标签键，请更改标签键并重试。
+ 标签键是必需的。此外，请确保标签键和标签值不超过最大字符长度，并且不包含受限字符。有关更多信息，请参阅 [添加标签以进行成本分配或基于属性的访问权限控制（ABAC）](tagging.md)。
## Steps
您可以使用 Amazon S3 控制台、AWS 命令行界面（AWS CLI）、Amazon S3 表类数据存储服务 REST API 和 AWS SDK 向表添加标签。
## 使用 S3 控制台
使用 Amazon S3 控制台向表添加标签：
1. 登录到 Amazon S3 控制台，网址为：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择表存储桶名称。
1. 选择表名称。
1. 选择**属性**选项卡。
1. 滚动到**标签**部分，然后选择**添加新标签**。
1. 这会打开**添加标签**页面。最多可以输入 50 个标签键值对。
1. 如果您添加的新标签与现有标签具有相同的键名称，则新标签的值将覆盖现有标签的值。
1. 还可以在此页面上编辑现有标签的值。
1. 添加标签后，选择**保存更改**。
## 使用 REST API
有关 Amazon S3 REST API 支持向表添加标签的相关信息，请参阅《Amazon Simple Storage Service API 参考》**中的以下部分：
+ [TagResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_TagResource.html)
## 使用 AWS CLI
要安装 AWS CLI，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
以下 CLI 示例说明如何使用 AWS CLI 向表添加标签。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
**请求**
```
aws --region us-west-2 \
s3tables tag-resource \
--resource-arn arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/table/my_example_table \
--tags '{"Department":"engineering"}'
```
# 查看表标签
您可以查看或列出应用于 Amazon S3 表的标签。有关标签的更多信息，请参阅[将标签与 S3 表结合使用](table-tagging.md)。
## 权限
要查看应用于表的标签，您必须具有以下权限：
+ `s3tables:ListTagsForResource`
## 错误故障排除
如果您在尝试列出或查看表的标签时遇到错误，可以执行以下操作：
+ 验证您是否具有查看或列出表的标签所需的[权限](#table-tag-view-permissions)。
## Steps
您可以使用 Amazon S3 控制台、AWS Command Line Interface（AWS CLI）、Amazon S3 REST API 和 AWS SDK 来查看应用于表的标签。
## 使用 S3 控制台
使用 Amazon S3 控制台查看应用于表的标签：
1. 登录到 Amazon S3 控制台，网址为：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择表存储桶名称。
1. 在表存储桶中选择表名称。
1. 选择**属性**选项卡。
1. 滚动至**标签**部分，以查看应用于表的所有标签。
1. 默认情况下，**标签**部分显示**用户定义的标签**。您可以选择 **AWS 生成的标签**选项卡来查看 AWS 服务应用到表的标签。
## 使用 REST API
有关 Amazon S3 REST API 支持查看应用于表的标签的相关信息，请参阅《Amazon Simple Storage Service API 参考》**中的以下部分：
+ [ListTagsforResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_ListTagsForResource.html)
## 使用 AWS CLI
要安装 AWS CLI，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
以下 CLI 示例说明如何查看应用于表的标签。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
**请求**
```
aws --region us-west-2 \
s3tables list-tags-for-resource \
--resource-arn arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/table/my_example_table
```
# 从表删除标签
您可以从 Amazon S3 表删除标签。有关为表添加标签的更多信息，请参阅[将标签与 S3 表结合使用](table-tagging.md)。
**注意**
如果您删除某个标签，但后来得知该标签用于跟踪成本或用于访问控制，则可以将该标签重新添加到表。
## 权限
要从表删除标签，您必须具有以下权限：
+ `s3tables:UntagResource`
## 错误故障排除
如果在尝试从表删除标签时遇到错误，可以执行以下操作：
+ 验证您是否具有从表删除标签所需的[权限](#table-tag-delete-permissions)。
## Steps
您可以使用 Amazon S3 控制台、AWS Command Line Interface（AWS CLI）、Amazon S3 表类数据存储服务 REST API 和 AWS SDK 从表删除标签。
## 使用 S3 控制台
使用 Amazon S3 控制台从表删除标签：
1. 登录到 Amazon S3 控制台，网址为：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择表存储桶名称。
1. 选择表名称。
1. 选择**属性**选项卡。
1. 滚动到**标签**部分，然后选中要删除的一个或多个标签旁边的复选框。
1. 选择**删除**。
1. 将显示**删除用户定义的标签**弹出窗口，要求您确认删除所选的一个或多个标签。
1. 选择 **Delete (删除)** 以确认。
## 使用 REST API
有关 Amazon S3 REST API 支持从表删除标签的相关信息，请参阅《Amazon Simple Storage Service API 参考》**中的以下部分：
+ [UnTagResource](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3Buckets_UntagResource.html)
## 使用 AWS CLI
要安装 AWS CLI，请参阅《AWS Command Line Interface 用户指南》**中的[安装 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)。
以下 CLI 示例说明如何使用 AWS CLI 从表删除标签。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
**请求**
```
aws --region us-west-2 \
s3tables untag-resource \
--resource-arn arn:aws::s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/table/my_example_table \
--tag-keys '["department"]'
```
# 访问表数据
有多种方法可以访问 Amazon S3 表存储桶中的表，您可以使用 Amazon SageMaker 智能湖仓将表与 AWS 分析服务集成，也可以直接使用 Amazon S3 表类数据存储服务 Iceberg REST 端点或适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录来访问表。您使用的访问方法将取决于您的目录设置、治理模式和访问控制需要。下文概述了这些访问方法。
**Amazon SageMaker 智能湖仓集成**
这是处理 S3 表存储桶中的表的推荐访问方法。该集成为您提供了统一的表管理、集中式治理以及跨多个 AWS 分析服务的精细访问控制。集成后，可以在 Athena 和 Amazon Redshift 等服务中查询表。
**直接访问**
如果您需要使用 AWS Partner Network（APN）目录实现、自定义目录实现，或者只需要对单个表存储桶中的表执行基本读/写操作，请使用此方法。
**注意**
要访问表，您使用的 IAM 身份需要访问您的表资源和 S3 表类数据存储服务操作。有关更多信息，请参阅 [S3 表类数据存储服务的访问管理](s3-tables-setting-up.md)。
## 通过 Amazon SageMaker 智能湖仓集成访问表
您可以将 S3 表存储桶与 Amazon SageMaker 智能湖仓集成，以便通过 AWS 分析服务访问表，例如 Amazon Athena、Amazon Redshift 和 Quick。Amazon SageMaker 智能湖仓统一了您在 Amazon S3 数据湖和 Amazon Redshift 数据仓库中的数据，因此，您可以在单个数据副本上构建分析、机器学习（ML）和生成式人工智能应用程序。该集成会使用您的表资源填充 AWS Glue Data Catalog，并与 AWS Lake Formation 联合访问这些资源。有关集成的更多信息，请参阅[将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
该集成通过 AWS Lake Formation 支持精细的访问控制，以提供额外的安全性。Lake Formation 结合使用自己的权限模型和 IAM 权限模型，来控制对表资源和基础数据的访问权限。这意味着，访问表的请求必须通过由 IAM 和 Lake Formation 执行的权限检查。有关更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Lake Formation permissions overview](https://docs.aws.amazon.com/lake-formation/latest/dg/lf-permissions-overview.html)。
以下 AWS 分析服务可以通过此集成访问表：
+ [Amazon Athena](s3-tables-integrating-athena.md)
+ [Amazon Redshift](s3-tables-integrating-redshift.md)
+ [Amazon EMR](s3-tables-integrating-emr.md)
+ [Quick](s3-tables-integrating-quicksight.md)
+ [Amazon Data Firehose](s3-tables-integrating-firehose.md)
+ [AWS Glue ETL](s3-tables-integrating-glue.md)
+ [使用 SageMaker 融通式合作开发工作室查询 S3 表类数据存储服务](s3-tables-integrating-sagemaker.md)
### 使用 AWS Glue Iceberg REST 端点访问表
在将 S3 表存储桶与 Amazon SageMaker 智能湖仓集成后，还可以使用 AWS Glue Iceberg REST 端点，从支持 Iceberg 的第三方查询引擎连接到 S3 表。有关更多信息，请参阅 [使用 AWS Glue Iceberg REST 端点访问 Amazon S3 表](s3-tables-integrating-glue-endpoint.md)。
当您要从 Spark、PyIceberg 或其它 Iceberg 兼容的客户端访问表时，我们建议使用 AWS Glue Iceberg REST 端点。
以下客户端可以直接通过 AWS Glue Iceberg REST 端点访问表：
+ 任何 Iceberg 客户端，包括 Spark、PyIceberg 等。
## 直接访问表
您可以通过将 S3 表类数据存储服务管理操作与 Apache Iceberg 分析应用程序连接起来的方法，直接从开源查询引擎访问表。有两种直接访问方法：Amazon S3 表类数据存储服务 Iceberg REST 端点或适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录。建议使用 REST 端点。
如果您访问自行管理的目录实现中的表，或者只需要对单个表存储桶中的表执行基本的读/写操作，我们建议您直接访问。对于其它访问场景，我们建议使用 Amazon SageMaker 智能湖仓集成。
对表的直接访问可通过附加到表和表存储桶的基于 IAM 身份的策略或基于资源的策略来进行管理。直接访问表时，您无需管理表的 Lake Formation 权限。
### 通过 Amazon S3 表类数据存储服务 Iceberg REST 端点访问表
您可以使用 Amazon S3 表类数据存储服务 Iceberg REST 端点，通过 HTTP 端点直接从任何 Iceberg REST 兼容的客户端访问您的表，有关更多信息，请参阅[使用 Amazon S3 表类数据存储服务 Iceberg REST 端点访问表](s3-tables-integrating-open-source.md)。
以下 AWS 分析服务和查询引擎可以使用 Amazon S3 表类数据存储服务 Iceberg REST 端点直接访问表：
**支持的查询引擎**
+ 任何 Iceberg 客户端，包括 Spark、PyIceberg 等。
+ [Amazon EMR](s3-tables-integrating-emr.md)
+ [AWS Glue ETL](s3-tables-integrating-glue.md)
### 通过适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录直接访问表
也可以通过使用 S3 表类数据存储服务客户端目录直接从查询引擎（例如 Apache Spark）访问表，有关更多信息，请参阅[使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录访问 Amazon S3 表](s3-tables-client-catalog.md)。但是，S3 建议使用 Amazon S3 表类数据存储服务 Iceberg REST 端点进行直接访问，因为它支持更多应用程序，而无需语言或引擎特定的代码。
以下查询引擎可以使用客户端目录直接访问表：
+ [Apache Spark](s3-tables-client-catalog.md#s3-tables-integrating-open-source-spark)
# Amazon S3 表类数据存储服务与 AWS 分析服务集成概述
要使 AWS 分析服务可以访问您账户中的表，您可以将 Amazon S3 表存储桶与 Amazon SageMaker 智能湖仓集成。这种集成支持 AWS 分析服务自动发现和访问您的表数据。您可以使用此集成在以下服务中处理表：
+ [Amazon Athena](s3-tables-integrating-athena.md)
+ [Amazon Redshift](s3-tables-integrating-redshift.md)
+ [Amazon EMR](s3-tables-integrating-emr.md)
+ [Quick](s3-tables-integrating-quicksight.md)
+ [Amazon Data Firehose](s3-tables-integrating-firehose.md)
**注意**
此集成使用 AWS Glue 和 AWS Lake Formation 服务，可能会产生 AWS Glue 请求和存储成本。有关更多信息，请参阅 [AWS Glue 定价](https://aws.amazon.com/glue/pricing/)。
在 S3 表上运行查询需支付额外费用。有关更多信息，请参阅您使用的查询引擎的定价信息。
## 集成的工作原理
当您在控制台中创建表存储桶时，Amazon S3 会启动以下操作，来将您选择的区域中的表存储桶与 AWS 分析服务集成：
1. 创建一个新的 AWS Identity and Access Management（IAM）[服务角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-service.html)，该角色授予 Lake Formation 访问所有表存储桶的权限。
1. 使用服务角色，Lake Formation 在当前区域中注册表存储桶。这可让 Lake Formation 管理该区域中所有当前和将来的表存储桶的访问、权限和治理。
1. 将 `s3tablescatalog` 目录添加到当前区域中的 AWS Glue Data Catalog。添加 `s3tablescatalog` 目录后，就可以在数据目录中填充所有表存储桶、命名空间和表。
**注意**
这些操作通过 Amazon S3 控制台自动完成。如果您以编程方式执行此集成，则必须手动执行所有这些操作。
您可以为每个 AWS 区域集成一次表存储桶。完成集成后，所有当前和将来的表存储桶、命名空间和表都将添加到该区域中的 AWS Glue Data Catalog。
下图显示了 `s3tablescatalog` 目录如何自动将当前区域中的表存储桶、命名空间和表填充为数据目录中的相应对象。表存储桶以子目录的形式填充。表存储桶中的命名空间以数据库的形式填充到其各自的子目录中。表以表的形式填充到各自的数据库中。
![\[在 AWS Glue Data Catalog 中表示表资源的方式。\]](http://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/images/S3Tables-glue-catalog.png)
**权限的工作原理**
我们建议将表存储桶与 AWS 分析服务集成，以便您可以跨使用 AWS Glue Data Catalog 作为元数据存储的服务处理表数据。该集成通过 AWS Lake Formation 支持精细的访问控制。这种安全方法意味着，除了 AWS Identity and Access Management（IAM）权限外，您还必须向 IAM 主体授予对表的 Lake Formation 权限，然后才能使用这些表。
AWS Lake Formation 中有两种主要类型的权限：
+ 元数据访问权限控制着在数据目录中创建、读取、更新和删除元数据数据库和表的能力。
+ 基础数据访问权限控制着对数据目录资源指向的基础 Amazon S3 位置读取和写入数据的能力。
Lake Formation 结合使用自己的权限模型和 IAM 权限模型，来控制对数据目录资源和基础数据的访问权限：
+ 为了使访问数据目录资源或基础数据的请求取得成功，请求必须通过由 IAM 和 Lake Formation 进行的权限检查。
+ IAM 权限控制对 Lake Formation 和 AWS Glue API 以及资源的访问权限，而 Lake Formation 权限控制对数据目录资源、Amazon S3 位置和基础数据的访问权限。
Lake Formation 权限仅适用于授予这些权限的区域，并且主体必须由数据湖管理员或其它具有必要权限的主体授权，才能获得 Lake Formation 权限。
有关更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Overview of Lake Formation permissions](https://docs.aws.amazon.com/lake-formation/latest/dg/lf-permissions-overview.html)。
请确保按照[将 S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)中的步骤进行操作，以便您拥有访问 AWS Glue Data Catalog 和表资源以及使用 AWS 分析服务的相应权限。
## 后续步骤
+ [将 S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)
+ [创建命名空间](s3-tables-namespace-create.md)
+ [创建表](s3-tables-create.md)
# 将 Amazon S3 表类数据存储服务与 AWS 分析服务集成
本主题介绍将 Amazon S3 表存储桶与 AWS 分析服务集成的先决条件和过程。有关集成工作原理的概述，请参阅 [S3 表类数据存储服务集成概述](s3-tables-integration-overview.md)。
**注意**
此集成使用 AWS Glue 和 AWS Lake Formation 服务，可能会产生 AWS Glue 请求和存储成本。有关更多信息，请参阅 [AWS Glue 定价](https://aws.amazon.com/glue/pricing/)。
在 S3 表上运行查询需支付额外费用。有关更多信息，请参阅您使用的查询引擎的定价信息。
## 集成的先决条件
要将表存储桶与 AWS 分析服务集成，需要满足以下先决条件：
+ [创建表存储桶。](s3-tables-buckets-create.md)
+ 将 [https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSLakeFormationDataAdmin.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AWSLakeFormationDataAdmin.html) AWS 托管式策略附加到 AWS Identity and Access Management（IAM）主体，以使该用户成为数据湖管理员。有关如何创建数据湖管理员的更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Create a data lake administrator](https://docs.aws.amazon.com//lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)。
+ 向 IAM 主体添加 `glue:PassConnection` 操作的权限。
+ 向 IAM 主体添加 `lakeformation:RegisterResource` 和 `lakeformation:RegisterResourceWithPrivilegedAccess` 操作的权限。
+ [更新到 AWS Command Line Interface（AWS CLI）的最新版本](https://docs.aws.amazon.com//cli/latest/userguide/getting-started-install.html#getting-started-install-instructions)。
**重要**
创建表时，请确保在表名称和表定义中全部使用小写字母。例如，请确保列名称全部为小写。如果表名称或表定义包含大写字母，则 AWS Lake Formation 或 AWS Glue Data Catalog 不支持该表。在这种情况下，Amazon Athena 等 AWS 分析服务将无法看到您的表，即使表存储桶与 AWS 分析服务集成，也不例外。
如果表定义包含大写字母，则在 Athena 中运行 `SELECT` 查询时会收到以下错误消息：“GENERIC\$1INTERNAL\$1ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names.”
## 将表存储桶与 AWS 分析服务集成
Amazon S3 表类数据存储服务与 AWS Glue Data Catalog（数据目录）集成，并将该目录注册为 Lake Formation 数据位置。您可以通过 Lake Formation 控制台或使用服务 API 来设置此注册。注册位置时，您必须指定 IAM 角色，来向 Lake Formation 注册的角色授予对该位置的读/写权限。Lake Formation 在向集成 AWS 服务提供临时凭证时会代入该角色。
如果您拥有基于 IAM 或 S3 表类数据存储服务资源的策略来根据主体标签限制 IAM 用户和 IAM 角色，则必须将相同的主体标签附加到 Lake Formation 用来访问 Amazon S3 数据的 IAM 角色（例如，LakeFormationDataAccessRole），并为该角色授予必要的权限。这是基于标签的访问控制策略与 S3 表类数据存储服务分析集成正常协同工作所必需的。
每个 AWS 区域均必须配置此集成。
**重要**
AWS 分析服务集成现在可在 `registerResource` Lake Formation API 操作中使用 `WithPrivilegedAccess` 选项来注册 S3 表存储桶。现在，集成还会通过在 `CreateCatalog` AWS Glue API 操作中使用 `AllowFullTableExternalDataAccess` 选项来在 AWS Glue Data Catalog 中创建 `s3tablescatalog` 目录。
如果您使用预览版设置集成，则可以继续使用当前的集成。但是，更新的集成流程提供了性能改进，因此我们建议进行迁移。要迁移到更新的集成，请参阅[迁移到更新的集成流程](#migrate-integrate-console)。
### 使用 S3 控制台
1. 通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 选择**创建表存储桶**。
此时将打开**创建表存储桶**页面。
1. 输入**表存储桶名称**，并确保选中**启用集成**复选框。
1. 选择**创建表存储桶**。Amazon S3 将尝试自动在该区域中集成您的表存储桶。
首次在任何区域中集成表存储桶时，Amazon S3 都会代表您创建一个新的 IAM 服务角色。此角色可让 Lake Formation 访问您账户中的所有表存储桶，并以联合身份验证方式访问 AWS Glue Data Catalog 中的表。
### 使用 AWS CLI
**使用 AWS CLI 集成表存储桶**
以下步骤展示了如何使用 AWS CLI 来集成表存储桶。要使用这些步骤，请将 `user input placeholders` 替换为您自己的信息。
1. 创建表存储桶。
```
aws s3tables create-table-bucket \
--region us-east-1 \
--name amzn-s3-demo-table-bucket
```
1. 创建可让 Lake Formation 访问表资源的 IAM 服务角色。
1. 创建一个名为 `Role-Trust-Policy.json` 的文件，其中包含以下信任策略：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "LakeFormationDataAccessPolicy",
"Effect": "Allow",
"Principal": {
"Service": "lakeformation.amazonaws.com"
},
"Action": [
"sts:AssumeRole",
"sts:SetContext",
"sts:SetSourceIdentity"
],
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
}
}
}
]
}
```
------
使用以下命令创建 IAM 服务角色：
```
aws iam create-role \
--role-name S3TablesRoleForLakeFormation \
--assume-role-policy-document file://Role-Trust-Policy.json
```
1. 创建一个名为 `LF-GluePolicy.json` 的文件，其中包含以下策略：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "LakeFormationPermissionsForS3ListTableBucket",
"Effect": "Allow",
"Action": [
"s3tables:ListTableBuckets"
],
"Resource": [
"*"
]
},
{
"Sid": "LakeFormationDataAccessPermissionsForS3TableBucket",
"Effect": "Allow",
"Action": [
"s3tables:CreateTableBucket",
"s3tables:GetTableBucket",
"s3tables:CreateNamespace",
"s3tables:GetNamespace",
"s3tables:ListNamespaces",
"s3tables:DeleteNamespace",
"s3tables:DeleteTableBucket",
"s3tables:CreateTable",
"s3tables:DeleteTable",
"s3tables:GetTable",
"s3tables:ListTables",
"s3tables:RenameTable",
"s3tables:UpdateTableMetadataLocation",
"s3tables:GetTableMetadataLocation",
"s3tables:GetTableData",
"s3tables:PutTableData"
],
"Resource": [
"arn:aws:s3tables:us-east-1:111122223333:bucket/*"
]
}
]
}
```
------
使用以下命令将策略附加到角色：
```
aws iam put-role-policy \
--role-name S3TablesRoleForLakeFormation \
--policy-name LakeFormationDataAccessPermissionsForS3TableBucket \
--policy-document file://LF-GluePolicy.json
```
1. 创建一个名为 `input.json` 的文件，其中包含以下内容：
```
{
"ResourceArn": "arn:aws:s3tables:us-east-1:111122223333:bucket/*",
"WithFederation": true,
"RoleArn": "arn:aws:iam::111122223333:role/S3TablesRoleForLakeFormation"
}
```
使用以下命令在 Lake Formation 中注册表存储桶：
```
aws lakeformation register-resource \
--region us-east-1 \
--with-privileged-access \
--cli-input-json file://input.json
```
1. 创建一个名为 `catalog.json` 的文件，其中包含以下目录：
```
{
"Name": "s3tablescatalog",
"CatalogInput": {
"FederatedCatalog": {
"Identifier": "arn:aws:s3tables:us-east-1:111122223333:bucket/*",
"ConnectionName": "aws:s3tables"
},
"CreateDatabaseDefaultPermissions":[],
"CreateTableDefaultPermissions":[],
"AllowFullTableExternalDataAccess": "True"
}
}
```
使用以下命令创建 `s3tablescatalog` 目录。创建此目录后，将使用与表存储桶、命名空间和表对应的对象填充 AWS Glue Data Catalog。
```
aws glue create-catalog \
--region us-east-1 \
--cli-input-json file://catalog.json
```
1. 使用以下命令验证是否在 AWS Glue 中添加了 `s3tablescatalog` 目录：
```
aws glue get-catalog --catalog-id s3tablescatalog
```
### 迁移到更新的集成流程
AWS 分析服务集成流程已更新。如果您已使用预览版设置了集成，则可以继续使用当前的集成。但是，更新的集成流程提供了性能改进，因此我们建议使用以下步骤进行迁移。有关迁移或集成流程的更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Creating an Amazon S3 Tables catalog in the AWS Glue Data Catalog](https://docs.aws.amazon.com/lake-formation/latest/dg/create-s3-tables-catalog.html)。
1. 打开 AWS Lake Formation 控制台（网址为 [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/)），并以数据湖管理员身份登录。有关如何创建数据湖管理员的更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Create a data lake administrator](https://docs.aws.amazon.com/lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)。
1. 通过执行以下操作删除 `s3tablescatalog` 目录：
+ 在左侧导航窗格中，选择**目录**。
+ 在**目录**列表中，选择 `s3tablescatalog` 目录旁边的选项按钮。在**操作** 菜单上，选择**删除**。
1. 通过执行以下操作注销 `s3tablescatalog` 目录的数据位置：
+ 在左侧导航窗格中，转到**管理**部分，然后选择**数据湖位置**。
+ 例如，选择 `s3tablescatalog` 数据湖位置（例如 `s3://tables:region:account-id:bucket/*`）旁边的选项按钮。
+ 在**操作**菜单上，选择**移除**。
+ 在出现的确认对话框中，选择**移除**。
1. 现在，您已经删除了 `s3tablescatalog` 目录和数据湖位置，可以按照以下步骤，使用更新的集成流程[将表存储桶与 AWS 分析服务集成](#table-integration-procedures)。
**注意**
如果您想在集成的 AWS 分析服务中使用通过 SSE-KMS 加密的表，则您使用的角色需要拥有使用您的 AWS KMS 密钥进行加密操作的权限。有关更多信息，请参阅 [向 IAM 主体授予在集成的 AWS 分析服务中使用加密表的权限](s3-tables-kms-permissions.md#tables-kms-integration-permissions)。
集成后，将向 IAM 主体授予访问表的 Lake Formation 权限，如果您想让其它 IAM 主体访问表，则需要向这些主体授予对表的 Lake Formation 权限。有关更多信息，请参阅 [使用 Lake Formation 管理对表或数据库的访问权限](grant-permissions-tables.md)。
**后续步骤**
+ [创建命名空间](s3-tables-namespace-create.md).
+ [创建表](s3-tables-create.md).
# 使用 AWS Glue Iceberg REST 端点访问 Amazon S3 表
将 S3 表存储桶与 AWS Glue Data Catalog 集成后，可以使用 AWS Glue Iceberg REST 端点从 Apache Iceberg 兼容的客户端（例如 PyIceberg 或 Spark）连接到您的 S3 表。AWS Glue Iceberg REST 端点实现了 [Iceberg REST Catalog Open API specification](https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml)，该规范提供了用于与 Iceberg 表进行交互的标准化接口。要使用端点访问 S3 表，您需要通过 IAM 策略和 AWS Lake Formation 授权的组合来配置权限。以下各节介绍如何设置访问权限，包括创建必要的 IAM 角色、定义所需的策略以及为数据库和表级访问建立 Lake Formation 权限。
有关使用 PyIceberg 的端到端演练，请参阅 [Access data in Amazon S3 Tables using PyIceberg through the AWS Glue Iceberg REST endpoint](https://aws.amazon.com/blogs/storage/access-data-in-amazon-s3-tables-using-pyiceberg-through-the-aws-glue-iceberg-rest-endpoint/)。
**先决条件**
+ [将表存储桶与 AWS 分析服务集成](s3-tables-integrating-aws.md)
+ [创建表命名空间](s3-tables-namespace-create.md)
+ [可以访问数据湖管理员账户](https://docs.aws.amazon.com//lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)
## 为客户端创建 IAM 角色
要通过 AWS Glue 端点访问表，您需要创建一个 IAM 角色，该角色拥有执行 AWS Glue 和 Lake Formation 操作的权限。此过程介绍如何创建此角色并配置其权限。
1. 通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在左侧导航窗格中，选择 **Policies（策略）**。
1. 选择**创建策略**，并在策略编辑器中选择 **JSON**。
1. 添加以下内联策略，该策略授予访问 AWS Glue 和 Lake Formation 操作的权限：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"glue:GetCatalog",
"glue:GetDatabase",
"glue:GetDatabases",
"glue:GetTable",
"glue:GetTables",
"glue:CreateTable",
"glue:UpdateTable"
],
"Resource": [
"arn:aws:glue:us-east-1:111122223333:catalog",
"arn:aws:glue:us-east-1:111122223333:catalog/s3tablescatalog",
"arn:aws:glue:us-east-1:111122223333:catalog/s3tablescatalog/amzn-s3-demo-table-bucket",
"arn:aws:glue:us-east-1:111122223333:table/s3tablescatalog/amzn-s3-demo-table-bucket//*",
"arn:aws:glue:us-east-1:111122223333:database/s3tablescatalog/amzn-s3-demo-table-bucket/"
]
},
{
"Effect": "Allow",
"Action": [
"lakeformation:GetDataAccess"
],
"Resource": "*"
}
]
}
```
------
1. 创建策略后，创建一个 IAM 角色，然后选择**自定义信任策略**作为**可信实体类型**。
1. 为**自定义信任策略**输入以下内容。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/Admin_role"
},
"Action": "sts:AssumeRole",
"Condition": {}
}
]
}
```
------
## 在 Lake Formation 中定义访问权限
Lake Formation 为数据湖表提供精细的访问控制。当您将 S3 存储桶与 AWS Glue Data Catalog 集成时，表会自动在 Lake Formation 中注册为资源。要访问这些表，除了 IAM 策略权限外，您还必须向您的 IAM 身份授予特定的 Lake Formation 权限。
以下步骤说明了如何应用 Lake Formation 访问控制，来支持 Iceberg 客户端连接到表。您必须以数据湖管理员身份登录，才能应用这些权限。
### 支持外部引擎访问表数据
在 Lake Formation 中，必须为外部引擎启用完全表访问权限，才能访问数据。这样，第三方应用程序在使用对所请求的表具有完全权限的 IAM 角色时，就可以从 Lake Formation 获取临时凭证。
通过 [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/) 打开 Lake Formation 控制台。
1. 通过 [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/) 打开 Lake Formation 控制台，并以数据湖管理员身份登录。
1. 在导航窗格中的**管理**下，选择**应用程序集成设置**。
1. 选择**支持外部引擎以完全表访问权限访问 Amazon S3 位置的数据**。然后选择**保存**。
### 授予 Lake Formation 对表资源的权限
接下来，向您为 Iceberg 兼容的客户端创建的 IAM 角色授予 Lake Formation 权限。这些权限将支持该角色在您的命名空间中创建和管理表。您需要同时提供数据库级和表级权限。有关更多信息，请参阅 [授予对表或数据库的 Lake Formation 权限](grant-permissions-tables.md#grant-lf-table)。
## 设置环境以使用端点
设置 IAM 角色（该角色具有访问表所需的权限）后，可以使用以下命令，通过您的角色配置 AWS CLI，使用该角色从本地计算机运行 Iceberg 客户端：
```
aws sts assume-role --role-arn "arn:aws:iam:::role/" --role-session-name
```
要通过 AWS Glue REST 端点访问表，您需要在 Iceberg 兼容的客户端中初始化目录。此初始化要求指定自定义属性，包括 sigv4 属性、端点 URI 和仓库位置。按如下方式指定这些属性：
+ Sigv4 属性：必须启用 Sigv4，签名名称为 `glue`
+ 仓库位置：这是表存储桶，按以下格式指定：`:s3tablescatalog/`
+ 端点 URI：有关区域特定的端点，请参阅 AWS Glue 服务端点参考指南。
下面的示例说明如何初始化 pyIceberg 目录。
```
rest_catalog = load_catalog(
s3tablescatalog,
**{
"type": "rest",
"warehouse": ":s3tablescatalog/",
"uri": "https://glue..amazonaws.com/iceberg",
"rest.sigv4-enabled": "true",
"rest.signing-name": "glue",
"rest.signing-region": region
}
)
```
有关 AWS Glue Iceberg REST 端点实现的更多信息，请参阅《AWS Glue 用户指南》**中的[使用 AWS GlueIceberg REST 端点连接到数据目录](https://docs.aws.amazon.com/glue/latest/dg/connect-glu-iceberg-rest.html)。
# 使用 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)。
# 使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录访问 Amazon S3 表
可以使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录客户端目录，从开源查询引擎（例如 Apache Spark）访问 S3 表。适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录是由 AWS 实验室托管的开源库。它的工作原理是将查询引擎中的 Apache Iceberg 操作（例如表发现、元数据更新以及添加或移除表）转换为 S3 表类数据存储服务类 API 操作。
适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录以名为 `s3-tables-catalog-for-iceberg.jar` 的 Maven JAR 形式分发。可以从 [AWS Labs GitHub repository](https://github.com/awslabs/s3-tables-catalog) 中构建客户端目录 JAR，也可以从 [Maven](https://mvnrepository.com/artifact/software.amazon.s3tables/s3-tables-catalog-for-iceberg) 下载它。连接到表时，在为 Apache Iceberg 初始化 Spark 会话的过程中，客户端目录 JAR 将用作依赖关系。
## 将适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录与 Apache Spark 结合使用
初始化 Spark 会话时，可以使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录客户端目录，从开源应用程序连接到表。在会话配置中，您可以指定 Iceberg 和 Amazon S3 依赖关系，并创建将表存储桶用作元数据仓库的自定义目录。
****先决条件****
+ 可以访问表存储桶和 S3 表类数据存储服务操作的 IAM 身份。有关更多信息，请参阅 [S3 表类数据存储服务的访问管理](s3-tables-setting-up.md)。
**使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录初始化 Spark 会话**
+ 使用以下命令初始化 Spark。要使用该命令，请将适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录*版本号*替换为 [AWS Labs GitHub repository](https://github.com/awslabs/s3-tables-catalog) 中的最新版本，并将*表存储桶 ARN* 替换为您自己的表存储桶 ARN。
```
spark-shell \
--packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.6.1,software.amazon.s3tables:s3-tables-catalog-for-iceberg-runtime:0.1.4 \
--conf spark.sql.catalog.s3tablesbucket=org.apache.iceberg.spark.SparkCatalog \
--conf spark.sql.catalog.s3tablesbucket.catalog-impl=software.amazon.s3tables.iceberg.S3TablesCatalog \
--conf spark.sql.catalog.s3tablesbucket.warehouse=arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions
```
### 使用 Spark SQL 查询 S3 表
使用 Spark，您可以对 S3 表运行 DQL、DML 和 DDL 操作。查询表时，请使用完全限定的表名称，包括遵循以下规律的会话目录名称：
`CatalogName.NamespaceName.TableName`
以下示例查询显示了您可以与 S3 表进行交互的一些方式。要在查询引擎中使用这些示例查询，请将*用户输入占位符*值替换为您自己的信息。
**使用 Spark 查询表**
+ 创建命名空间
```
spark.sql(" CREATE NAMESPACE IF NOT EXISTS s3tablesbucket.my_namespace")
```
+ 创建表
```
spark.sql(" CREATE TABLE IF NOT EXISTS s3tablesbucket.my_namespace.`my_table`
( id INT, name STRING, value INT ) USING iceberg ")
```
+ 查询表
```
spark.sql(" SELECT * FROM s3tablesbucket.my_namespace.`my_table` ").show()
```
+ 将数据插入表中
```
spark.sql(
"""
INSERT INTO s3tablesbucket.my_namespace.my_table
VALUES
(1, 'ABC', 100),
(2, 'XYZ', 200)
""")
```
+ 将现有数据文件加载到表中
1. 将数据读入 Spark。
```
val data_file_location = "Path such as S3 URI to data file"
val data_file = spark.read.parquet(data_file_location)
```
1. 将数据写入 Iceberg 表。
```
data_file.writeTo("s3tablesbucket.my_namespace.my_table").using("Iceberg").tableProperty ("format-version", "2").createOrReplace()
```
# 使用 Athena 查询 Amazon S3 表类数据存储服务
Amazon Athena 是一种交互式查询服务，可用于通过使用标准 SQL 直接分析 Amazon S3 中的数据。有关更多信息，请参阅《Amazon Athena 用户指南》中的 [什么是 Amazon Athena？](https://docs.aws.amazon.com//athena/latest/ug/what-is.html)**。
将表存储桶与 AWS 分析服务集成后，可以使用 Athena 对 S3 表运行数据定义语言（DDL）、数据操作语言（DML）和数据查询语言（DQL）查询。有关如何查询表存储桶中的表的更多信息，请参阅《Amazon Athena 用户指南》**中的[注册 S3 表存储桶目录](https://docs.aws.amazon.com//athena/latest/ug/gdc-register-s3-table-bucket-cat.html)。
还可以在 Athena 中从 Amazon S3 控制台运行查询。
**重要**
创建表时，请确保在表名称和表定义中全部使用小写字母。例如，请确保列名称全部为小写。如果表名称或表定义包含大写字母，则 AWS Lake Formation 或 AWS Glue Data Catalog 不支持该表。在这种情况下，Amazon Athena 等 AWS 分析服务将无法看到您的表，即使表存储桶与 AWS 分析服务集成，也不例外。
如果表定义包含大写字母，则在 Athena 中运行 `SELECT` 查询时会收到以下错误消息：“GENERIC\$1INTERNAL\$1ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names.”
## 使用 S3 控制台和 Amazon Athena
以下过程使用 Amazon S3 控制台访问 Athena 查询编辑器，以便您可以使用 Amazon Athena 查询表。
**注意**
在执行以下步骤之前，请确保您已在此区域中将表存储桶与 AWS 分析服务集成。有关更多信息，请参阅 [将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
**查询表**
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在**表存储桶**页面上，选择包含要查询的表的存储桶。
1. 在存储桶详细信息页面上，选择要查询的表名称旁边的选项按钮。
1. 选择**使用 Athena 查询表**。
1. Amazon Athena 控制台打开，Athena 查询编辑器随即出现，其中包含为您加载的示例 `SELECT` 查询。根据您的用例需要修改此查询。
在查询编辑器中，**目录**字段中应填充 **s3tablescatalog/**，后跟表存储桶的名称，例如 **s3tablescatalog/*amzn-s3-demo-bucket***。**数据库**字段中应填充在其中存储表的命名空间。
**注意**
如果您在**目录**和**数据库**字段中看不到这些值，请确保您已在该区域中将表存储桶与 AWS 分析服务集成。有关更多信息，请参阅 [将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
1. 要运行查询，请选择 **Run**（运行）。
**注意**
如果您在尝试在 Athena 中运行查询时收到错误“权限不足，无法执行查询。主体对指定的资源没有任何权限”，则必须向您授予对于表的必需 Lake Formation 权限。有关更多信息，请参阅 [授予对表或数据库的 Lake Formation 权限](grant-permissions-tables.md#grant-lf-table)。
如果您在尝试运行查询时收到错误“Iceberg 无法访问所请求的资源”，请转到 AWS Lake Formation 控制台，并确保您已授予自己对您创建的表存储桶目录和数据库（命名空间）的权限。授予这些权限时请勿指定表。有关更多信息，请参阅 [授予对表或数据库的 Lake Formation 权限](grant-permissions-tables.md#grant-lf-table)。
如果在 Athena 中运行 `SELECT` 查询时收到以下错误消息，则此消息是由表名称中或表定义的列名称中具有大写字母而引起的：“GENERIC\$1INTERNAL\$1ERROR: Get table request failed: com.amazonaws.services.glue.model.ValidationException: Unsupported Federation Resource - Invalid table or column names.” 确保表名称和列名称全部为小写。
# 使用 Amazon Redshift 访问 Amazon S3 表类数据存储服务
Amazon Redshift 是一项快速且完全托管的 PB 级数据仓库服务，可让您使用现有的商业智能工具轻松且经济高效地分析所有数据。Redshift Serverless 让您可以访问和分析数据，而无需对预置数据仓库进行所有配置。有关更多信息，请参阅《Amazon Redshift 入门指南》**中的 [Serverless 数据仓库入门](https://docs.aws.amazon.com//redshift/latest/gsg/new-user-serverless.html)。
## 使用 Amazon Redshift 查询 Amazon S3 表
**先决条件**
+ [将表存储桶与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
+ [创建命名空间](s3-tables-namespace-create.md).
+ [创建表](s3-tables-create.md).
+ [使用 Lake Formation 管理对表或数据库的访问权限](grant-permissions-tables.md).
满足先决条件后，可以通过以下方式之一开始使用 Amazon Redshift 来查询表：
+ [使用 Amazon Redshift 查询编辑器 V2](https://docs.aws.amazon.com//redshift/latest/mgmt/query-editor-v2.html)
+ [使用 SQL 客户端工具连接到 Amazon Redshift 数据仓库](https://docs.aws.amazon.com//redshift/latest/mgmt/connecting-to-cluster.html)
+ [使用 Amazon Redshift 数据 API](https://docs.aws.amazon.com//redshift/latest/mgmt/data-api.html)
# 使用 Amazon EMR 访问 Amazon S3 表类数据存储服务
Amazon EMR（以前称为 Amazon Elastic MapReduce）是一个托管式集群平台，可简化在 AWS 上运行大数据框架（如 Apache Hadoop 和 Apache Spark）的过程，以处理和分析海量数据。使用这些框架和相关的开源项目，您可以处理用于分析目的的数据和业务情报工作负载。Amazon EMR 还可让您转换大量数据，并将数据移入/移出其它 AWS 数据存储和数据库。
通过在 Spark 会话中连接到表存储桶，您可以使用 Amazon EMR 中的 Apache Iceberg 集群来处理 S3 表类数据存储服务。要连接到 Amazon EMR 中的表存储桶，可以通过 AWS Glue Data Catalog 使用 AWS 分析服务集成，也可以使用适用于 Apache Iceberg 的开源 Amazon S3 表类数据存储服务目录客户端目录。
**注意**
[Amazon EMR version 7.5](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-release-components.html) 或更高版本支持 S3 表类数据存储服务。
## 在 Amazon EMR Iceberg 集群上使用 Spark 连接到 S3 表存储桶
在此过程中，您设置为 Apache Iceberg 配置的 Amazon EMR 集群，然后启动连接到表存储桶的 Spark 会话。您可以通过 AWS Glue 使用 AWS 分析服务集成来设置此项，也可以使用适用于 Apache Iceberg 的开源 Amazon S3 表类数据存储服务目录客户端目录。有关客户端目录的信息，请参阅[使用 Amazon S3 表类数据存储服务 Iceberg REST 端点访问表](s3-tables-integrating-open-source.md)。
从以下选项中选择在 Amazon EMR 中使用表的方法。
------
#### [ Amazon S3 Tables Catalog for Apache Iceberg ]
使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录在 Amazon EMR 上通过 Spark 查询表需要满足以下先决条件。
有关最新版本的客户端目录 JAR，请参阅 [s3-tables-catalog GitHub 存储库](https://github.com/awslabs/s3-tables-catalog)。
**先决条件**
+ 将 `AmazonS3TablesFullAccess` 策略附加到您用于 Amazon EMR 的 IAM 角色。
**设置 Amazon EMR 集群以使用 Spark 查询表**
1. 使用以下配置创建集群。要使用此示例，请将 `user input placeholders` 替换为您自己的信息。
```
aws emr create-cluster --release-label emr-7.5.0 \
--applications Name=Spark \
--configurations file://configurations.json \
--region us-east-1 \
--name My_Spark_Iceberg_Cluster \
--log-uri s3://amzn-s3-demo-bucket/ \
--instance-type m5.xlarge \
--instance-count 2 \
--service-role EMR_DefaultRole \
--ec2-attributes \
InstanceProfile=EMR_EC2_DefaultRole,SubnetId=subnet-1234567890abcdef0,KeyName=my-key-pair
```
`configurations.json`:
```
[{
"Classification":"iceberg-defaults",
"Properties":{"iceberg.enabled":"true"}
}]
```
1. [Connect to the Spark primary node using SSH.](https://docs.aws.amazon.com//emr/latest/ManagementGuide/emr-connect-master-node-ssh.html#emr-connect-cli)
1. 要初始化 Iceberg 的连接到表存储桶的 Spark 会话，请输入以下命令。将 `user input placeholders` 替换为表存储桶 ARN。
```
spark-shell \
--packages software.amazon.s3tables:s3-tables-catalog-for-iceberg-runtime:0.1.8 \
--conf spark.sql.catalog.s3tablesbucket=org.apache.iceberg.spark.SparkCatalog \
--conf spark.sql.catalog.s3tablesbucket.catalog-impl=software.amazon.s3tables.iceberg.S3TablesCatalog \
--conf spark.sql.catalog.s3tablesbucket.warehouse=arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1 \
--conf spark.sql.defaultCatalog=s3tablesbucket \
--conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions
```
1. 使用 Spark SQL 查询表。有关示例查询，请参阅[使用 Spark SQL 查询 S3 表](s3-tables-client-catalog.md#query-with-spark)。
------
#### [ AWS analytics services integration ]
使用 AWS 分析服务集成在 Amazon EMR 上通过 Spark 查询表需要满足以下先决条件。
**先决条件**
+ [将表存储桶与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
+ 为 Amazon EMR 创建默认服务角色 (`EMR_DefaultRole_V2`)。有关详细信息，请参阅 [Service role for Amazon EMR (EMR role)](https://docs.aws.amazon.com//emr/latest/ManagementGuide/emr-iam-role.html)。
+ 为 Amazon EMR 创建 Amazon EC2 实例配置文件 (`EMR_EC2_DefaultRole`)。有关详细信息，请参阅 [Service role for cluster EC2 instances (EC2 instance profile)](https://docs.aws.amazon.com//emr/latest/ManagementGuide/emr-iam-role-ec2.html)。
+ 将 `AmazonS3TablesFullAccess` 策略附加到 `EMR_EC2_DefaultRole`。
**设置 Amazon EMR 集群以使用 Spark 查询表**
1. 使用以下配置创建集群。要使用此示例，请将 `user input placeholder` 值替换为您自己的信息。
```
aws emr create-cluster --release-label emr-7.5.0 \
--applications Name=Spark \
--configurations file://configurations.json \
--region us-east-1 \
--name My_Spark_Iceberg_Cluster \
--log-uri s3://amzn-s3-demo-bucket/ \
--instance-type m5.xlarge \
--instance-count 2 \
--service-role EMR_DefaultRole \
--ec2-attributes \
InstanceProfile=EMR_EC2_DefaultRole,SubnetId=subnet-1234567890abcdef0,KeyName=my-key-pair
```
`configurations.json`:
```
[{
"Classification":"iceberg-defaults",
"Properties":{"iceberg.enabled":"true"}
}]
```
1. [Connect to the Spark primary node using SSH.](https://docs.aws.amazon.com//emr/latest/ManagementGuide/emr-connect-master-node-ssh.html#emr-connect-cli)
1. 输入以下命令来初始化 Iceberg 的连接到表的 Spark 会话。将区域、账户 ID 和表存储桶名称的 `user input placeholders` 替换为您自己的信息。
```
spark-shell \
--conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
--conf spark.sql.defaultCatalog=s3tables \
--conf spark.sql.catalog.s3tables=org.apache.iceberg.spark.SparkCatalog \
--conf spark.sql.catalog.s3tables.catalog-impl=org.apache.iceberg.aws.glue.GlueCatalog \
--conf spark.sql.catalog.s3tables.client.region=us-east-1 \
--conf spark.sql.catalog.s3tables.glue.id=111122223333:s3tablescatalog/amzn-s3-demo-table-bucket
```
1. 使用 Spark SQL 查询表。有关示例查询，请参阅[使用 Spark SQL 查询 S3 表](s3-tables-client-catalog.md#query-with-spark)
------
**注意**
如果您在 Amazon EMR 中使用 `DROP TABLE PURGE` 命令：
Amazon EMR 版本 7.5
将 Spark 配置 `spark.sql.catalog.your-catalog-name.cache-enabled` 设置为 `false`。如果此配置设置为 `true`，请在新的会话或应用程序中运行该命令，这样就不会激活表缓存。
高于 7.5 的 Amazon EMR 版本
`DROP TABLE`不支持 。可以使用 S3 表类数据存储服务 `DeleteTable` REST API 来删除表。
# 使用 Quick 实现表数据可视化
Quick 是一项快速业务分析服务，可用于构建可视化内容，执行临时分析，并快速地从您的数据中获得业务见解。Quick 无缝地发现 AWS 数据来源，使组织可以扩展至数十万用户，并通过使用 Quick 超快、并行、内存、计算引擎（SPICE）提供快速的响应式查询性能。有关更多信息，请参阅《Quick 用户指南》**中的[什么是 Quick？](https://docs.aws.amazon.com//quicksight/latest/user/welcome.html)
[将表存储桶与 AWS 分析服务集成](s3-tables-integrating-aws.md)后，可以从表中创建数据集，然后通过从查询引擎中使用 SPICE 或直接 SQL 查询，来在 Quick 中使用这些数据集。Quick 支持 Athena 作为 S3 表的数据来源。
## 为 Quick 配置访问表的权限
在 Quick 中处理 S3 表数据之前，您必须向 Quick 服务角色、Quick 管理员用户授予权限，并向 Lake Formation 授予对您要访问的表的权限。
**向 Quick 服务角色授予权限**
首次在账户中设置 Quick 时，AWS 会创建一个服务角色，让 Quick 访问其它 AWS 服务（例如 Athena 或 Amazon Redshift）中的数据来源。默认角色名为 `aws-quicksight-service-role-v0`。
1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 选择**角色**，然后选择 Quick 服务角色。默认名称为 `aws-quicksight-service-role-v0`
1. 选择**添加权限**，然后选择**创建内联策略**。
1. 选择 **JSON** 以打开 JSON 策略编辑器，然后添加以下策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "glue:GetCatalog",
"Resource": "*"
}
]
}
```
------
1. 选择**下一步**，输入**策略名称**，然后**创建策略**。
**为 Quick 管理员用户配置权限**
1. 运行以下 AWS CLI 命令以查找 Quick 管理员用户的 ARN。
```
aws quicksight list-users --aws-account-id 111122223333 --namespace default --region region
```
1. 向 Lake Formation 授予对此 ARN 的权限 有关更多信息，请参阅 [使用 Lake Formation 管理对表或数据库的访问权限](grant-permissions-tables.md)。
## 在 Quick 中使用表数据
可以使用 Athena 作为数据来源连接到表数据。
**先决条件**
+ [将表存储桶与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
+ [创建命名空间](s3-tables-namespace-create.md).
+ [创建表](s3-tables-create.md).
+ [为 Quick 配置访问表的权限](#quicksight-permissions-tables).
+ [注册 Quick](https://docs.aws.amazon.com/quicksight/latest/user/signing-up.html)。
1. 登录您的 Quick 账户，网址为 [https://quicksight.aws.amazon.com/](https://quicksight.aws.amazon.com/.)
1. 在控制面板中，选择**新分析**。
1. 选择**新数据集**。
1. 选择 **Athena**。
1. 输入**数据来源名称**，然后选择**创建数据来源**。
1. 选择使用自定义 SQL。您将无法从**选择您的表**窗格中选择您的表。
1. 输入用于捕获要可视化的列的 Athena SQL 查询，然后选择**确认查询**。例如，使用以下查询选择所有列：
```
SELECT * FROM "s3tablescatalog/table-bucket-name".namespace.table-name
```
1. 选择**可视化**以分析数据并开始构建控制面板。有关更多信息，请参阅[在 Quick 中实现数据可视化](https://docs.aws.amazon.com//quicksight/latest/user/working-with-visuals.html)和[探索 Quick 中的交互式控制面板](https://docs.aws.amazon.com//quicksight/latest/user/using-dashboards.html)
# 使用 Amazon Data Firehose 将数据流式传输到表
Amazon Data Firehose 是一项完全托管式服务，用于实时将[流数据](https://aws.amazon.com//streaming-data/)传输到目标，如 Amazon S3、Amazon Redshift、Amazon OpenSearch Service、Splunk、Apache Iceberg 表和自定义 HTTP 端点或由受支持的第三方服务提供商拥有的 HTTP 端点。在使用 Amazon Data Firehose 时，您无需编写应用程序或管理资源。您可以配置数据生成工具向 Firehose 发送数据，然后 Firehose 会将数据自动传输到您指定的目标。还可以配置 Firehose 在传输数据之前转换数据。要了解有关 Amazon Data Firehose 的更多信息，请参阅 [What is Amazon Data Firehose?](https://docs.aws.amazon.com//firehose/latest/dev/what-is-this-service.html)
完成以下步骤以设置 Firehose 流式传输到 S3 表存储桶中的表：
1. [将表存储桶与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
1. 配置 Firehose 以将数据传输到 S3 表中。为此，您需要[创建一个支持 Firehose 访问表的 AWS Identity and Access Management（IAM）服务角色](#firehose-role-s3tables)。
1. 向 Firehose 服务角色授予对表或表命名空间的显式权限。有关更多信息，请参阅[授予 Lake Formation 对表资源的权限](grant-permissions-tables.md)。
1. [创建一个 Firehose 流来将数据路由到表。](#firehose-stream-tables)
## 为 Firehose 创建一个角色以使用 S3 表作为目标
Firehose 需要具有特定权限的 IAM [服务角色](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_roles_create_for-service.html)，才能访问 AWS Glue 表并将数据写入 S3 表。在创建 Firehose 流时，您需要提供此 IAM 角色。
1. 通过 [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) 打开 IAM 控制台。
1. 在左侧导航窗格中，选择**策略**
1. 选择**创建策略**，并在策略编辑器中选择 **JSON**。
1. 添加以下内联策略，来授予对数据目录中所有数据库和表的权限。如果需要，则您可以仅向特定的表和数据库授予权限。要使用此策略，请将 `user input placeholders` 替换为您自己的信息。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "S3TableAccessViaGlueFederation",
"Effect": "Allow",
"Action": [
"glue:GetTable",
"glue:GetDatabase",
"glue:UpdateTable"
],
"Resource": [
"arn:aws:glue:us-east-1:111122223333:catalog/s3tablescatalog/*",
"arn:aws:glue:us-east-1:111122223333:catalog/s3tablescatalog",
"arn:aws:glue:us-east-1:111122223333:catalog",
"arn:aws:glue:us-east-1:111122223333:database/*",
"arn:aws:glue:us-east-1:111122223333:table/*/*"
]
},
{
"Sid": "S3DeliveryErrorBucketPermission",
"Effect": "Allow",
"Action": [
"s3:AbortMultipartUpload",
"s3:GetBucketLocation",
"s3:GetObject",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:PutObject"
],
"Resource": [
"arn:aws:s3:::error delivery bucket",
"arn:aws:s3:::error delivery bucket/*"
]
},
{
"Sid": "RequiredWhenUsingKinesisDataStreamsAsSource",
"Effect": "Allow",
"Action": [
"kinesis:DescribeStream",
"kinesis:GetShardIterator",
"kinesis:GetRecords",
"kinesis:ListShards"
],
"Resource": "arn:aws:kinesis:us-east-1:111122223333:stream/stream-name"
},
{
"Sid": "RequiredWhenDoingMetadataReadsANDDataAndMetadataWriteViaLakeformation",
"Effect": "Allow",
"Action": [
"lakeformation:GetDataAccess"
],
"Resource": "*"
},
{
"Sid": "RequiredWhenUsingKMSEncryptionForS3ErrorBucketDelivery",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": [
"arn:aws:kms:us-east-1:111122223333:key/KMS-key-id"
],
"Condition": {
"StringEquals": {
"kms:ViaService": "s3.us-east-1.amazonaws.com"
},
"StringLike": {
"kms:EncryptionContext:aws:s3:arn": "arn:aws:s3:::error delivery bucket/prefix*"
}
}
},
{
"Sid": "LoggingInCloudWatch",
"Effect": "Allow",
"Action": [
"logs:PutLogEvents"
],
"Resource": [
"arn:aws:logs:us-east-1:111122223333:log-group:log-group-name:log-stream:log-stream-name"
]
},
{
"Sid": "RequiredWhenAttachingLambdaToFirehose",
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction",
"lambda:GetFunctionConfiguration"
],
"Resource": [
"arn:aws:lambda:us-east-1:111122223333:function:function-name:function-version"
]
}
]
}
```
------
此策略有一些语句，支持访问 Kinesis Data Streams、调用 Lambda 函数和访问 AWS KMS 密钥。如果您不使用这些资源中的任何一个，则可以删除相应的语句。
如果启用了错误日志记录，则 Firehose 还会将数据传输错误发送到您的 CloudWatch 日志组和流。为此，您必须配置日志组和日志流名称。对于日志组和日志流名称，请参阅 [Monitor Amazon Data Firehose Using CloudWatch Logs](https://docs.aws.amazon.com//firehose/latest/dev/controlling-access.html#using-iam-iceberg)。
1. 创建策略后，创建一个 IAM 角色，其中 **AWS 服务**为**可信实体类型**。
1. 对于**服务或使用案例**，选择 **Kinesis**。对于**使用案例**，选择 **Kinesis Firehose**。
1. 选择**下一步**，然后选择之前创建的策略。
1. 为您的角色命名。检查角色详细信息，然后选择**创建角色**。该角色将具有以下信任策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"sts:AssumeRole"
],
"Principal": {
"Service": [
"firehose.amazonaws.com"
]
}
}
]
}
```
------
## 创建到 S3 表的 Firehose 流
以下过程说明如何使用控制台创建 Firehose 流来向 S3 表传输数据。要设置到 S3 表的 Firehose 流，需要满足以下先决条件。
**先决条件**
+ [将表存储桶与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
+ [创建命名空间](s3-tables-namespace-create.md).
+ [创建表](s3-tables-create.md).
+ 创建[供 Firehose 访问 S3 表类数据存储服务的角色](#firehose-role-s3tables)。
+ 向您创建的 Firehose 服务角色[授予访问表的 Lake Formation 权限](grant-permissions-tables.md)。
要在配置流时向 Firehose 提供路由信息，可以使用命名空间作为数据库名称和该命名空间中表的名称。可以在 Firehose 流配置的“唯一键”部分使用这些值，来将数据路由到单个表。也可以使用这些值通过 JSON 查询表达式路由到表。有关更多信息，请参阅 [Route incoming records to a single Iceberg table](https://docs.aws.amazon.com/firehose/latest/dev/apache-iceberg-format-input-record.html)。
**设置到 S3 表的 Firehose 流（控制台）**
1. 在 [https://console.aws.amazon.com/firehose/](https://console.aws.amazon.com/firehose/) 中打开 Firehose 控制台。
1. 选择**创建 Firehose 流**。
1. 对于**源**，选择下列源之一：
+ Amazon Kinesis Data Streams
+ Amazon MSK
+ 直接 PUT
1. 对于**目标**，选择 **Apache Iceberg 表**。
1. 输入 **Firehose 流名称**。
1. 配置**源设置**。
1. 对于**目标设置**，选择**当前账户**以流式传输到您账户中的表，或者选择**跨账户**以流式传输到其它账户中的表。
+ 对于**当前账户**中的表，请从**目录**下拉列表中选择您的 S3 表类数据存储服务目录。
+ 对于**跨账户**中的表，请在另一个账户中输入您要流式传输到的目录的**目录 ARN**。
1. 使用**唯一密钥配置**、JSONQuery 表达式或在 Lambda 函数中配置数据库和表名称。有关更多信息，请参阅《Amazon Data Firehose Developer Guide》**中的 [Route incoming records to a single Iceberg table](https://docs.aws.amazon.com/firehose/latest/dev/apache-iceberg-format-input-record.html) 和 [Route incoming records to different Iceberg tables](https://docs.aws.amazon.com//firehose/latest/dev/apache-iceberg-format-input-record-different.html)。
1. 在**备份设置**下，指定 **S3 备份存储桶**。
1. 对于**高级设置**下的**现有 IAM 角色**，选择您为 Firehose 创建的 IAM 角色。
1. 选择**创建 Firehose 流**。
有关您可以为流配置的其它设置的更多信息，请参阅《Amazon Data Firehose Developer Guide》**中的 [Set up the Firehose stream](https://docs.aws.amazon.com/firehose/latest/dev/apache-iceberg-stream.html)。
# 使用 AWS Glue 对 Amazon S3 表运行 ETL 任务
AWS Glue 是一项无服务器数据集成服务，可让使用分析功能的用户轻松发现、准备、移动和集成来自多个来源的数据。可以使用 AWS Glue 运行提取、转换、加载（ETL）管道，来将数据加载到数据湖中。有关 AWS Glue 的更多信息，请参阅《*AWS Glue 开发人员指南*》中的[什么是 AWS Glue？](https://docs.aws.amazon.com//glue/latest/dg/what-is-glue.html)。
AWS Glue 作业将封装连接到源数据的脚本，处理该脚本，然后将其写入数据目标。通常，作业运行提取、转换和加载 (ETL) 脚本。作业可以运行专为 Apache Spark 运行时环境设计的脚本。您可以监控作业运行以了解运行时指标（例如完成状态、持续时间和开始时间）。
您可以使用 AWS Glue 作业来处理 S3 表中的数据，方法是通过与 AWS 分析服务的集成连接到表，或者直接使用 Amazon S3 表类数据存储服务 Iceberg REST 端点或适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录进行连接。本指南涵盖了开始将 AWS Glue 与 S3 表类数据存储服务结合使用的基本步骤，包括：
**Topics**
+ [步骤 1：先决条件](#glue-etl-prereqs)
+ [步骤 2：创建用于连接到表存储桶的脚本](#glue-etl-script)
+ [步骤 3：创建用于查询表的 AWS Glue 任务](#glue-etl-job)
根据特定的 AWS Glue ETL 任务要求选择访问方法：
+ **AWS 分析服务集成（建议）**：当您需要跨多项 AWS 分析服务进行集中式元数据管理、需要利用现有 AWS Glue Data Catalog 权限和 Lake Formation 的精细访问控制功能，或者正在构建与 Athena 或 Amazon EMR AWS 等其它服务集成的生产 ETL 管道时，建议使用此访问方法。
+ **Amazon S3 表类数据存储服务 Iceberg REST 端点**：当您需要从支持 Apache Iceberg 的第三方查询引擎连接到 S3 表、构建需要直接 REST API 访问的自定义 ETL 应用程序，或者需要在不依赖 AWS Glue Data Catalog 的情况下控制目录操作时，建议使用此访问方法。
+ **适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录**：仅用于需要 Java 客户端库的传统应用程序或特定编程方案。由于额外的 `JAR` 依赖项管理和复杂性，因此不建议将此方法用于新的 AWS Glue ETL 任务实现。
**注意**
[AWS Glue 版本 5.0 或更高版本](https://docs.aws.amazon.com//glue/latest/dg/release-notes.html)支持 S3 表类数据存储服务。
## 步骤 1：先决条件
在从 AWS Glue 任务中查询表之前，必须配置 AWS Glue 可用来运行该任务的 IAM 角色。选择访问方法以查看该方法的特定先决条件。
------
#### [ AWS analytics services integration (Recommended) ]
使用 S3 表类数据存储服务 AWS 分析集成来运行 AWS Glue 任务所需的先决条件。
+ [将表存储桶与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
+ [为 AWS Glue 创建 IAM 角色。](https://docs.aws.amazon.com//glue/latest/dg/create-an-iam-role.html)
+ 将 `AmazonS3TablesFullAccess` 托管式策略附加到角色。
+ 将 `AmazonS3FullAccess` 托管式策略附加到角色。
------
#### [ Amazon S3 Tables Iceberg REST endpoint ]
使用 Amazon S3 表类数据存储服务 Iceberg REST 端点来运行 AWS Glue ETL 任务的先决条件。
+ [为 AWS Glue 创建 IAM 角色。](https://docs.aws.amazon.com//glue/latest/dg/create-an-iam-role.html)
+ 将 `AmazonS3TablesFullAccess` 托管式策略附加到角色。
+ 将 `AmazonS3FullAccess` 托管式策略附加到角色。
------
#### [ Amazon S3 Tables Catalog for Apache Iceberg ]
先决条件使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录来运行 AWS Glue ETL 任务。
+ [为 AWS Glue 创建 IAM 角色。](https://docs.aws.amazon.com//glue/latest/dg/create-an-iam-role.html)
+ 将 `AmazonS3TablesFullAccess` 托管式策略附加到角色。
+ 将 `AmazonS3FullAccess` 托管式策略附加到角色。
+ 要使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录，您需要下载客户端目录 JAR 并将其上传到 S3 存储桶。
****下载目录 JAR****
1. 在 [Maven Central](https://mvnrepository.com/artifact/software.amazon.s3tables/s3-tables-catalog-for-iceberg-runtime) 上检查最新版本。您可以使用浏览器或使用以下命令从 Maven Central 下载 JAR。请务必将*版本号*替换为最新版本。
```
wget https://repo1.maven.org/maven2/software/amazon/s3tables/s3-tables-catalog-for-iceberg-runtime/0.1.5/s3-tables-catalog-for-iceberg-runtime-0.1.5.jar
```
1. 将下载的 JAR 上传到 AWS Glue IAM 角色可以访问的 S3 存储桶。您可以使用以下 AWS CLI 命令来上传 JAR。请务必将*版本号*替换为最新版本，并将*存储桶名称*和*路径*替换为您自己的信息。
```
aws s3 cp s3-tables-catalog-for-iceberg-runtime-0.1.5.jar s3://amzn-s3-demo-bucket/jars/
```
------
## 步骤 2：创建用于连接到表存储桶的脚本
要在运行 AWS Glue ETL 作业时访问表数据，可以为 Apache Iceberg 配置一个 Spark 会话，用于连接到 S3 表存储桶。可以修改现有脚本以连接到表存储桶或创建新脚本。有关创建 AWS Glue 脚本的更多信息，请参阅《AWS Glue 开发人员指南》**中的[教程：编写 AWS Glue for Spark 脚本](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-intro-tutorial.html)。
可以将会话配置为通过以下任一 S3 表类数据存储服务访问方法连接到表存储桶：
+ S3 表类数据存储服务 AWS 分析服务集成（建议）
+ Amazon S3 表类数据存储服务 Iceberg REST 端点
+ 适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录
从以下访问方法中进行选择，以查看设置说明和配置示例。
------
#### [ AWS analytics services integration (Recommended) ]
作为使用 AWS 分析服务集成在 AWS Glue 上使用 Spark 查询表的先决条件，您必须[将表存储桶与 AWS 分析服务进行集成](s3-tables-integrating-aws.md)
可以通过作业中的 Spark 会话或交互式会话中的 AWS Glue Studio 魔法来配置与表存储桶的连接。要使用以下示例，请将*占位符值*替换为您自己的表存储桶的信息。
**使用 PySpark 脚本**
在 PySpark 脚本中使用以下代码段，以便将 AWS Glue 作业配置为使用集成连接到表存储桶。
```
spark = SparkSession.builder.appName("SparkIcebergSQL") \
.config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.4_2.12:1.4.2") \
.config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
.config("spark.sql.defaultCatalog","s3tables") \
.config("spark.sql.catalog.s3tables", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.s3tables.catalog-impl", "org.apache.iceberg.aws.glue.GlueCatalog") \
.config("spark.sql.catalog.s3tables.glue.id", "111122223333:s3tablescatalog/amzn-s3-demo-table-bucket") \
.config("spark.sql.catalog.s3tables.warehouse", "s3://amzn-s3-demo-table-bucket/warehouse/") \
.getOrCreate()
```
**使用交互式 AWS Glue 会话**
如果您将交互式笔记本会话与 AWS Glue 5.0 结合使用，请在执行代码之前，在单元格中使用 `%%configure` 魔法指定相同的配置。
```
%%configure
{"conf": "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions --conf spark.sql.defaultCatalog=s3tables --conf spark.sql.catalog.s3tables=org.apache.iceberg.spark.SparkCatalog --conf spark.sql.catalog.s3tables.catalog-impl=org.apache.iceberg.aws.glue.GlueCatalog --conf spark.sql.catalog.s3tables.glue.id=111122223333:s3tablescatalog/amzn-s3-demo-table-bucket --conf spark.sql.catalog.s3tables.warehouse=s3://amzn-s3-demo-table-bucket/warehouse/"}
```
------
#### [ Amazon S3 Tables Iceberg REST endpoint ]
可以通过作业中的 Spark 会话或交互式会话中的 AWS Glue Studio 魔法来配置与表存储桶的连接。要使用以下示例，请将*占位符值*替换为您自己的表存储桶的信息。
**使用 PySpark 脚本**
在 PySpark 脚本中使用以下代码段，以便将 AWS Glue 作业配置为使用端点连接到表存储桶。
```
spark = SparkSession.builder.appName("glue-s3-tables-rest") \
.config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.4_2.12:1.4.2") \
.config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
.config("spark.sql.defaultCatalog", "s3_rest_catalog") \
.config("spark.sql.catalog.s3_rest_catalog", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.s3_rest_catalog.type", "rest") \
.config("spark.sql.catalog.s3_rest_catalog.uri", "https://s3tables.Region.amazonaws.com/iceberg") \
.config("spark.sql.catalog.s3_rest_catalog.warehouse", "arn:aws:s3tables:Region:111122223333:bucket/amzn-s3-demo-table-bucket") \
.config("spark.sql.catalog.s3_rest_catalog.rest.sigv4-enabled", "true") \
.config("spark.sql.catalog.s3_rest_catalog.rest.signing-name", "s3tables") \
.config("spark.sql.catalog.s3_rest_catalog.rest.signing-region", "Region") \
.config('spark.sql.catalog.s3_rest_catalog.io-impl','org.apache.iceberg.aws.s3.S3FileIO') \
.config('spark.sql.catalog.s3_rest_catalog.rest-metrics-reporting-enabled','false') \
.getOrCreate()
```
**使用交互式 AWS Glue 会话**
如果您将交互式笔记本会话与 AWS Glue 5.0 结合使用，请在执行代码之前，在单元格中使用 `%%configure` 魔法指定相同的配置。将占位符值 替换为您自己的表存储桶的信息。
```
%%configure
{"conf": "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions --conf spark.sql.defaultCatalog=s3_rest_catalog --conf spark.sql.catalog.s3_rest_catalog=org.apache.iceberg.spark.SparkCatalog --conf spark.sql.catalog.s3_rest_catalog.type=rest --conf spark.sql.catalog.s3_rest_catalog.uri=https://s3tables.Region.amazonaws.com/iceberg --conf spark.sql.catalog.s3_rest_catalog.warehouse=arn:aws:s3tables:Region:111122223333:bucket/amzn-s3-demo-table-bucket --conf spark.sql.catalog.s3_rest_catalog.rest.sigv4-enabled=true --conf spark.sql.catalog.s3_rest_catalog.rest.signing-name=s3tables --conf spark.sql.catalog.s3_rest_catalog.rest.signing-region=Region --conf spark.sql.catalog.s3_rest_catalog.io-impl=org.apache.iceberg.aws.s3.S3FileIO --conf spark.sql.catalog.s3_rest_catalog.rest-metrics-reporting-enabled=false"}
```
------
#### [ Amazon S3 Tables Catalog for Apache Iceberg ]
作为使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录连接到表的先决条件，您必须先下载最新的目录 jar 并将其上传到 S3 存储桶。然后，在创建作业时，将指向客户端目录 JAR 的路径添加为一个特殊参数。有关 AWS Glue 中作业参数的更多信息，请参阅《AWS Glue 开发人员指南》**中的 [AWS Glue 作业中使用的特殊参数](https://docs.aws.amazon.com/glue/latest/dg/aws-glue-programming-etl-glue-arguments.html)。
可以通过作业中的 Spark 会话或交互式会话中的 AWS Glue Studio 魔法来配置与表存储桶的连接。要使用以下示例，请将*占位符值*替换为您自己的表存储桶的信息。
**使用 PySpark 脚本**
在 PySpark 脚本中使用以下代码段，以便将 AWS Glue 作业配置为使用 JAR 连接到表存储桶。将占位符值 替换为您自己的表存储桶的信息。
```
spark = SparkSession.builder.appName("glue-s3-tables") \
.config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.4_2.12:1.4.2") \
.config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
.config("spark.sql.defaultCatalog", "s3tablesbucket") \
.config("spark.sql.catalog.s3tablesbucket", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.s3tablesbucket.catalog-impl", "software.amazon.s3tables.iceberg.S3TablesCatalog") \
.config("spark.sql.catalog.s3tablesbucket.warehouse", "arn:aws:s3tables:Region:111122223333:bucket/amzn-s3-demo-table-bucket") \
.getOrCreate()
```
**使用交互式 AWS Glue 会话**
如果您将交互式笔记本会话与 AWS Glue 5.0 结合使用，请在执行代码之前，在单元格中使用 `%%configure` 魔法指定相同的配置。将占位符值 替换为您自己的表存储桶的信息。
```
%%configure
{"conf": "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions --conf spark.sql.defaultCatalog=s3tablesbucket --conf spark.sql.catalog.s3tablesbucket=org.apache.iceberg.spark.SparkCatalog --conf spark.sql.catalog.s3tablesbucket.catalog-impl=software.amazon.s3tables.iceberg.S3TablesCatalog --conf spark.sql.catalog.s3tablesbucket.warehouse=arn:aws:s3tables:Region:111122223333:bucket/amzn-s3-demo-table-bucket", "extra-jars": "s3://amzn-s3-demo-bucket/jars/s3-tables-catalog-for-iceberg-runtime-0.1.5.jar"}
```
------
### 示例脚本
以下示例 PySpark 脚本可用于测试通过 AWS Glue 作业来查询 S3 表。这些脚本连接到表存储桶，然后运行查询来执行以下操作：创建新的命名空间、创建示例表、向表中插入数据以及返回表数据。要使用这些脚本，请将*占位符值*替换为您自己的表存储桶的信息。
根据 S3 表类数据存储服务访问方法从以下脚本中进行选择。
------
#### [ S3 Tables integration with AWS analytics services ]
```
from pyspark.sql import SparkSession
spark = SparkSession.builder.appName("SparkIcebergSQL") \
.config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.4_2.12:1.4.2") \
.config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
.config("spark.sql.defaultCatalog","s3tables")
.config("spark.sql.catalog.s3tables", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.s3tables.catalog-impl", "org.apache.iceberg.aws.glue.GlueCatalog") \
.config("spark.sql.catalog.s3tables.glue.id", "111122223333:s3tablescatalog/amzn-s3-demo-table-bucket") \
.config("spark.sql.catalog.s3tables.warehouse", "s3://amzn-s3-demo-table-bucket/bucket/amzn-s3-demo-table-bucket") \
.getOrCreate()
namespace = "new_namespace"
table = "new_table"
spark.sql("SHOW DATABASES").show()
spark.sql(f"DESCRIBE NAMESPACE {namespace}").show()
spark.sql(f"""
CREATE TABLE IF NOT EXISTS {namespace}.{table} (
id INT,
name STRING,
value INT
)
""")
spark.sql(f"""
INSERT INTO {namespace}.{table}
VALUES
(1, 'ABC', 100),
(2, 'XYZ', 200)
""")
spark.sql(f"SELECT * FROM {namespace}.{table} LIMIT 10").show()
```
------
#### [ Amazon S3 Tables Iceberg REST endpoint ]
```
from pyspark.sql import SparkSession
spark = SparkSession.builder.appName("glue-s3-tables-rest") \
.config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.4_2.12:1.4.2") \
.config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
.config("spark.sql.defaultCatalog", "s3_rest_catalog") \
.config("spark.sql.catalog.s3_rest_catalog", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.s3_rest_catalog.type", "rest") \
.config("spark.sql.catalog.s3_rest_catalog.uri", "https://s3tables.Region.amazonaws.com/iceberg") \
.config("spark.sql.catalog.s3_rest_catalog.warehouse", "arn:aws:s3tables:Region:111122223333:bucket/amzn-s3-demo-table-bucket") \
.config("spark.sql.catalog.s3_rest_catalog.rest.sigv4-enabled", "true") \
.config("spark.sql.catalog.s3_rest_catalog.rest.signing-name", "s3tables") \
.config("spark.sql.catalog.s3_rest_catalog.rest.signing-region", "Region") \
.config('spark.sql.catalog.s3_rest_catalog.io-impl','org.apache.iceberg.aws.s3.S3FileIO') \
.config('spark.sql.catalog.s3_rest_catalog.rest-metrics-reporting-enabled','false') \
.getOrCreate()
namespace = "s3_tables_rest_namespace"
table = "new_table_s3_rest"
spark.sql("SHOW DATABASES").show()
spark.sql(f"DESCRIBE NAMESPACE {namespace}").show()
spark.sql(f"""
CREATE TABLE IF NOT EXISTS {namespace}.{table} (
id INT,
name STRING,
value INT
)
""")
spark.sql(f"""
INSERT INTO {namespace}.{table}
VALUES
(1, 'ABC', 100),
(2, 'XYZ', 200)
""")
spark.sql(f"SELECT * FROM {namespace}.{table} LIMIT 10").show()
```
------
#### [ Amazon S3 Tables Catalog for Apache Iceberg ]
```
from pyspark.sql import SparkSession
#Spark session configurations
spark = SparkSession.builder.appName("glue-s3-tables") \
.config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.4_2.12:1.4.2") \
.config("spark.sql.extensions", "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions") \
.config("spark.sql.defaultCatalog", "s3tablesbucket") \
.config("spark.sql.catalog.s3tablesbucket", "org.apache.iceberg.spark.SparkCatalog") \
.config("spark.sql.catalog.s3tablesbucket.catalog-impl", "software.amazon.s3tables.iceberg.S3TablesCatalog") \
.config("spark.sql.catalog.s3tablesbucket.warehouse", "arn:aws:s3tables:Region:111122223333:bucket/amzn-s3-demo-table-bucket") \
.getOrCreate()
#Script
namespace = "new_namespace"
table = "new_table"
spark.sql(f"CREATE NAMESPACE IF NOT EXISTS s3tablesbucket.{namespace}")
spark.sql(f"DESCRIBE NAMESPACE {namespace}").show()
spark.sql(f"""
CREATE TABLE IF NOT EXISTS {namespace}.{table} (
id INT,
name STRING,
value INT
)
""")
spark.sql(f"""
INSERT INTO {namespace}.{table}
VALUES
(1, 'ABC', 100),
(2, 'XYZ', 200)
""")
spark.sql(f"SELECT * FROM {namespace}.{table} LIMIT 10").show()
```
------
## 步骤 3：创建用于查询表的 AWS Glue 任务
以下过程显示了如何设置连接到 S3 表存储桶的 AWS Glue 作业。您可以使用 AWS CLI 或将控制台与 AWS Glue Studio 脚本编辑器结合使用来完成此操作。有关更多信息，请参阅《AWS Glue 用户指南》**中的[在 AWS Glue 中编写任务](https://docs.aws.amazon.com/glue/latest/dg/author-job-glue.html)。
### 使用 AWS Glue Studio 脚本编辑器
以下过程介绍了如何使用 AWS Glue Studio 脚本编辑器来创建用于查询 S3 表的 ETL 任务。
**先决条件**
+ [步骤 1：先决条件](#glue-etl-prereqs)
+ [步骤 2：创建用于连接到表存储桶的脚本](#glue-etl-script)
1. 通过 [https://console.aws.amazon.com/glue/](https://console.aws.amazon.com/glue/) 打开 AWS Glue 控制台。
1. 在导航窗格中，选择 **ETL 任务**。
1. 选择**脚本编辑器**，然后选择**上传脚本**并上传您创建的用于查询 S3 表的 PySpark 脚本。
1. 选择**任务详细信息**选项卡，然后对于**基本属性**输入以下内容。
+ 对于**名称**，输入任务的名称。
+ 对于 **IAM 角色**，选择您为 AWS Glue 创建的角色。
1. （可选）如果您使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录访问方法，请展开**高级属性**，对于**从属 JAR 路径**，输入您作为先决条件上传到 S3 存储桶的客户端目录 jar 的 S3 URI。例如，s3://*amzn-s3-demo-bucket1*/*jars*/s3-tables-catalog-for-iceberg-runtime-*0.1.5*.jar
1. 选择**保存**以创建任务。
1. 选择**运行**以启动任务，然后在**运行**选项卡下查看任务状态。
### 使用 AWS CLI
以下过程介绍了如何使用 AWS CLI 来创建用于查询 S3 表的 ETL 任务。要使用这些命令，请将*占位符值*替换为您自己的值。
**先决条件**
+ [步骤 1：先决条件](#glue-etl-prereqs)
+ [步骤 2：创建用于连接到表存储桶的脚本](#glue-etl-script)并将其上传到 S3 存储桶。
1. 创建 AWS Glue 任务。
```
aws glue create-job \
--name etl-tables-job \
--role arn:aws:iam::111122223333:role/AWSGlueServiceRole \
--command '{
"Name": "glueetl",
"ScriptLocation": "s3://amzn-s3-demo-bucket1/scripts/glue-etl-query.py",
"PythonVersion": "3"
}' \
--default-arguments '{
"--job-language": "python",
"--class": "GlueApp"
}' \
--glue-version "5.0"
```
**注意**
（可选）如果您使用适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录访问方法，请使用 `--extra-jars` 参数将客户端目录 JAR 添加到 `--default-arguments` 中。添加参数时，将*输入占位符*替换为您自己的信息。
```
"--extra-jars": "s3://amzn-s3-demo-bucket/jar-path/s3-tables-catalog-for-iceberg-runtime-0.1.5.jar"
```
1. 启动任务。
```
aws glue start-job-run \
--job-name etl-tables-job
```
1. 要查看任务状态，请复制上一个命令中的运行 ID，然后将其输入到以下命令中。
```
aws glue get-job-run --job-name etl-tables-job \
--run-id jr_ec9a8a302e71f8483060f87b6c309601ea9ee9c1ffc2db56706dfcceb3d0e1ad
```
# 开始使用 Amazon SageMaker 融通式合作开发工作室查询 S3 表类数据存储服务
Amazon SageMaker 融通式合作开发工作室是一项综合分析服务，可让您使用 SQL、自然语言和交互式笔记本查询数据并从中得出见解。它使用统一的界面，支持跨 AWS 数据存储库和第三方来源的团队协作和分析工作流。SageMaker 融通式合作开发工作室直接与 S3 表类数据存储服务集成，在 Amazon S3 控制台中实现了从数据存储到分析的无缝过渡。
您可以通过 Amazon S3 控制台或 SageMaker 融通式合作开发工作室控制台，将 S3 表类数据存储服务与 SageMaker 融通式合作开发工作室集成。
要通过 SageMaker 融通式合作开发工作室控制台进行设置，请参阅 [SageMaker 融通式合作开发工作室文档](https://docs.aws.amazon.com/next-generation-sagemaker/latest/userguide/s3-tables-integration.html)。
## 使用 SageMaker 融通式合作开发工作室查询 S3 表类数据存储服务的要求
将 SageMaker 融通式合作开发工作室与 S3 表类数据存储服务结合使用时，需要满足以下条件：
+ 您的表存储桶已与当前区域的 AWS 分析服务集成。有关更多信息，请参阅 [将 S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
+ 您使用的 IAM 角色有权在 SageMaker 融通式合作开发工作室中创建和查看资源。有关更多信息，请参阅[在 SageMaker 融通式合作开发工作室中设置基于 IAM 的域](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/adminguide/setup-iam-based-domains.html)。
+ 您有一个 SageMaker 域和项目。有关更多信息，请参阅《SageMaker 融通式合作开发工作室管理员指南》**中的[域](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/adminguide/working-with-domains.html)，以及《SageMaker 融通式合作开发工作室用户指南》**中的[项目](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/userguide/projects.html)。
如果您尚未执行这些操作或创建这些资源，S3 表类数据存储服务可以自动为您完成此设置，这样您就可以开始使用 SageMaker 融通式合作开发工作室进行查询。
## 开始使用 SageMaker 融通式合作开发工作室查询 S3 表类数据存储服务
1. 打开 Amazon S3 控制台，网址为 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在**表存储桶**页面上，选择包含要查询的表的存储桶。
1. 在存储桶详细信息页面上，选择要查询的表。
1. 选择 **Query (查询)**。
1. 然后，选择**在 SageMaker 融通式合作开发工作室中查询表**。
1. 如果您已经为表配置了 SageMaker 融通式合作开发工作室，此时 SageMaker 融通式合作开发工作室控制台会打开查询编辑器，其中包含为您加载的示例 `SELECT` 查询。根据您的用例需要修改此查询。
1. 如果您还没有为 S3 表类数据存储服务配置 SageMaker 融通式合作开发工作室，则会显示一个设置页面，其中提供了一个步骤用来启用与 AWS 分析服务的集成，这会将您的表与 SageMaker 融通式合作开发工作室等服务集成。此步骤自动执行，然后您将被重定向到 SageMaker 融通式合作开发工作室控制台中的页面，其中提供以下选项来配置您的账户以查询 S3 表类数据存储服务：
1. 在**将您设置为管理员**中，选择了您当前的联合身份验证 IAM 角色。如果您当前的角色还没有所需的权限，则需要在 [SageMaker 融通式合作开发工作室中设置基于 IAM 的域](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/adminguide/setup-iam-based-domains.html)并为您的角色分配权限，这样您才能登录 SageMaker 融通式合作开发工作室。
1. 在**项目数据和管理控制**中，选择**自动创建具有所需权限的新角色**以自动创建具有所需权限的角色，或者选择**使用现有角色**并选择角色。如果选择的角色还没有所需的权限，则需要在 [SageMaker 融通式合作开发工作室中设置基于 IAM 的域](https://docs.aws.amazon.com/sagemaker-unified-studio/latest/adminguide/setup-iam-based-domains.html)并向管理员执行角色分配权限，这样您才能访问 SageMaker 融通式合作开发工作室中的数据。
1. 在**数据加密**中，选择**使用 AWS 拥有的密钥**可让 AWS 为您负责和管理密钥，或者选择**选择其他 AWS AWS KMS 密钥（高级）**以使用现有密钥或创建新密钥。
1. 选择**设置 SageMaker 融通式合作开发工作室**。
1. 接下来，SageMaker 融通式合作开发工作室控制台会打开查询编辑器，其中包含为您加载的示例 `SELECT` 查询。根据您的用例需要修改此查询。
在查询编辑器中，**目录**字段中应填充 `s3tablescatalog/`，后跟表存储桶的名称，例如 `s3tablescatalog/amzn-s3-demo-table-bucket`。**数据库**字段中应填充存储您的表的命名空间。
# 使用 Apache Iceberg V3
Apache Iceberg 版本 3（V3）是 Apache Iceberg 表格式规范的最新版本，此版本引入了高级功能用于构建 PB 级数据湖，同时改善性能并降低运营开销。V3 解决了 V2 中会遇到的常见性能瓶颈，尤其是在批量更新和合规删除方面。
AWS 支持删除向量和行谱系，如 Apache Iceberg 版本 3（V3）规范中定义。这些功能可在下列服务中使用：[Amazon EMR 7.12](https://docs.aws.amazon.com/prescriptive-guidance/latest/apache-iceberg-on-aws/iceberg-emr.html) 上的 Apache Spark；[AWS Glue ETL](https://docs.aws.amazon.com/prescriptive-guidance/latest/apache-iceberg-on-aws/iceberg-glue.html)；[Amazon SageMaker 融通式合作开发工作室笔记本](https://docs.aws.amazon.com/next-generation-sagemaker/)；以及 [AWS Glue Data Catalog](https://docs.aws.amazon.com/glue/latest/dg/catalog-and-crawler.html) 中的 Apache Iceberg 表（包括 [Amazon S3 表类数据存储服务](https://aws.amazon.com/s3/features/tables/)）。
## V3 中的主要功能
删除向量
将 V2 中的位置删除文件替换成存储为 Puffin 文件的高效二进制格式。这消除了随机批量更新和 GDPR 合规删除带来的写入放大，从而大幅降低维护刷新数据的开销。如果组织在处理高频率更新，可以立即体验到写入性能改进，并可以通过减少小文件来降低存储成本。
行谱系
实现了行级别的精确变更跟踪。您的下游系统可以通过递增方式处理更改，从而加快数据管道并降低更改数据捕获（CDC）工作流的计算成本。此内置功能消除了实施自定义变更跟踪的需求。
## 版本兼容性
V3 保持与 V2 表的向后兼容性。AWS 服务同时支持 V2 和 V3 表，让您可以：
+ 在 V2 和 V3 表上运行查询
+ 无需数据重写即可将现有 V2 表升级到 V3
+ 执行跨 V2 和 V3 快照的时间旅行查询
+ 跨表版本使用架构演变和隐藏分区
**重要**
V3 是一个单向升级。表从 V2 升级到 V3 后，就无法通过标准操作将其降级回 V2。
## 开始使用 V3
### 先决条件
使用 V3 表之前，请确保您具有：
+ AWS 账户和相应的 IAM 权限
+ 一项或多项 AWS 分析服务（EMR、Glue、Amazon SageMaker 融通式合作开发工作室笔记本或 S3 表类数据存储服务）的访问权限
+ S3 存储桶，用于存储表数据和元数据
+ 表存储桶，用于开始使用 S3 表类数据存储服务，如果您在构建自己的 Iceberg 基础设施，则是 S3 通用存储桶
+ 已配置 AWS Glue 目录
### 创建 V3 表
#### 创建新 V3 表
要创建新 Iceberg V3 表，请将 format-version 表属性设置为 3。
**使用 Spark SQL：**
```
CREATE TABLE IF NOT EXISTS myns.orders_v3 (
order_id bigint,
customer_id string,
order_date date,
total_amount decimal(10,2),
status string,
created_at timestamp
)
USING iceberg
TBLPROPERTIES (
'format-version' = '3'
)
```
#### 将 V2 表升级到 V3
您可以自动将现有 V2 表升级到 V3 而无需重写数据。
**使用 Spark SQL：**
```
ALTER TABLE myns.existing_table
SET TBLPROPERTIES ('format-version' = '3')
```
**重要**
V3 是一个单向升级。表从 V2 升级到 V3 后，就无法通过标准操作将其降级回 V2。
**升级期间发生的操作：**
+ 以原子方式创建新的元数据快照
+ 重复使用现有的 Parquet 数据文件
+ 在表元数据中添加了行谱系字段
+ 下次压缩时将移除旧的 V2 删除文件
+ 新修改将使用 V3 的删除向量文件
+ 升级不会对行谱系变更跟踪记录执行历史回填
### 启用删除向量
要利用删除向量进行更新、删除和合并，请配置您的写入模式。
**使用 Spark SQL：**
```
ALTER TABLE myns.orders_v3
SET TBLPROPERTIES ('format-version' = '3',
'write.delete.mode' = 'merge-on-read',
'write.update.mode' = 'merge-on-read',
'write.merge.mode' = 'merge-on-read'
)
```
这些设置可确保更新、删除和合并操作创建删除向量文件，而不是重写整个数据文件。
### 利用行谱系进行变更跟踪
V3 会自动添加行谱系元数据字段用于跟踪更改。
**使用 Spark SQL：**
```
# Query with parameter value provided
last_processed_sequence = 47
SELECT
id,
data,
_row_id,
_last_updated_sequence_number
FROM myns.orders_v3
WHERE _last_updated_sequence_number > :last_processed_sequence
```
\$1row\$1id 字段唯一地标识每行，而 \$1last\$1updated\$1sequence\$1number 则跟踪上次修改该行的时间。使用这些字段可以：
+ 标识已更改的行来进行增量处理
+ 跟踪数据血统以确保合规性
+ 优化 CDC 管道
+ 仅处理更改过的内容，从而降低计算成本
## V3 最佳实践
### 何时使用 V3
在以下情况下，可以考虑升级到 V3 或直接开始使用 V3：
+ 您经常执行批量更新或删除
+ 您需要满足 GDPR 或合规删除要求
+ 您的工作负载涉及频繁的更新插入
+ 您需要高效的 CDC 工作流
+ 您需要降低小文件的存储成本
+ 您需要更好的变更跟踪功能
### 优化写入性能
+ 为更新密集型工作负载启用删除向量：
```
SET TBLPROPERTIES (
'write.delete.mode' = 'merge-on-read',
'write.update.mode' = 'merge-on-read',
'write.merge.mode' = 'merge-on-read'
)
```
+ 配置适当的文件大小：
```
SET TBLPROPERTIES (
'write.target-file-size-bytes' = '536870912' — 512 MB
)
```
### 优化读取性能
+ 利用行谱系进行增量处理
+ 使用时间旅行访问历史数据而无需进行复制
+ 启用统计数据收集以更好地进行查询规划
## 迁移策略
从 V2 迁移到 V3：
+ 首先在非生产环境中进行测试：验证升级过程和性能
+ 在活动较少的时间段进行升级：尽可能减少对并发操作的影响
+ 监控初始性能：在升级后跟踪指标
+ 运行压缩：升级后合并删除文件
+ 更新文档：在团队文档中记录 V3 功能
## 兼容性注意事项
+ 引擎版本：确保所有访问表的引擎都支持 V3
+ 第三方工具：升级前验证 V3 兼容性
+ 备份策略：测试基于快照的恢复程序
+ 监控：更新 V3 特定指标的监控控制面板
## 问题排查
### 常见问题
错误：“不支持 format-version 3”
+ 验证您的引擎版本是否支持 V3
V3 对 AWS 服务的支持如下：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/working-with-apache-iceberg-v3.html)
+ 检查目录兼容性
+ 确保 AWS 服务版本为最新
升级后的性能下降
+ 确认没有压缩故障。有关更多详细信息，请参阅 [S3 表类数据存储服务的日志记录和监控](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-monitoring-overview.html)。
+ 检查是否启用了删除向量。确保已设置下列属性：
```
SET TBLPROPERTIES (
'write.delete.mode' = 'merge-on-read',
'write.update.mode' = 'merge-on-read',
'write.merge.mode' = 'merge-on-read'
)
```
+ 您可以使用以下代码验证表属性：
```
DESCRIBE FORMATTED myns.orders_v3
```
+ 查看分区策略。过度分区会产生小文件。运行以下查询来获取表的平均文件大小：
```
SELECT avg(file_size_in_bytes) as avg_file_size_bytes
FROM myns.orders_v3.files
```
与第三方工具不兼容
+ 验证工具是否支持 V3 规范
+ 考虑为不支持的工具维护 V2 表
+ 请联系工具供应商来了解 V3 支持时间表
### 获取帮助
+ AWS Support：有关特定服务的问题，请联系 AWS Support
+ Apache Iceberg 社区：Iceberg Slack
+ AWS 文档：AWS 分析文档
## 定价
+ Amazon EMR：[计算和存储定价](https://aws.amazon.com/emr/pricing/)
+ [Amazon SageMaker 定价](https://aws.amazon.com/sagemaker/pricing/)
+ AWS Glue：[作业运行和 Data Catalog 定价](https://aws.amazon.com/glue/pricing/)
+ S3 表类数据存储服务：[存储和请求定价](https://aws.amazon.com/s3/pricing/)
## 可用性
所有提供 Amazon EMR、AWS Glue Data Catalog、AWS Glue ETL 和 S3 表类数据存储服务的 AWS 区域均支持 Apache Iceberg V3。
## 其他资源
+ [Apache Iceberg V3 文档](https://docs.aws.amazon.com/prescriptive-guidance/latest/apache-iceberg-on-aws/introduction.html)
+ [迁移最佳实践](https://aws.amazon.com/solutions/guidance/migrating-tabular-data-from-amazon-s3-to-s3-tables/)
+ [入门指南](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-getting-started.html)
# 复制 S3 表
Amazon S3 表类数据存储服务支持自动复制存储在 Amazon S3 表存储桶中的 Apache Iceberg 表。复制目标可以位于同一 AWS 区域、跨多个 AWS 区域、位于同一账户或者位于其他 AWS 账户。通过为表配置复制，您可以跨多个位置维护数据的只读副本。您可以使用副本来提高数据可用性、满足合规要求和提升分布式应用程序的访问性能。
S3 表类数据存储服务复制通过按照与源表相同的顺序将所有表更新（包括快照、元数据和数据文件）提交到目标表来保持数据一致性。
## 何时使用 S3 表类数据存储服务复制
您可以将 S3 表类数据存储服务复制用于以下目的：
+ **最大限度降低延迟**：如果客户位于两个地理位置，您可以通过在距离用户地理位置更近的 AWS 区域维护只读副本，来最大限度降低访问表时的延迟。
+ **监管合规**：您可以在特定地理位置或 AWS 账户中维护只读副本，这可能有助于您满足某些监管或合规要求。您可以将复制目标表存储桶配置为使用与源不同的 AWS KMS 密钥来加密表。
+ **集中式分析**：如果您的数据分布在多个 AWS 区域，您可以将区域特定数据集复制到一个集中的区域，以进行统一报告、跨区域分析和机器学习模型训练。这样就无需跨区域查询数据或构建自定义数据聚合管道。
+ **测试和开发环境**：您可以在单独的 AWS 账户或表存储桶中创建生产表的只读副本，以便为开发和 QA 团队提供真实的测试数据。这样就可以将测试工作负载与生产系统隔离，同时确保测试环境拥有最新的类生产环境数据，而无需进行手动导出或数据同步流程。
## 功能
S3 表类数据存储服务复制提供了以下功能。
**适用于 S3 表类数据存储服务的只读副本**
S3 表类数据存储服务复制会跨表存储桶创建 Apache Iceberg 表的只读副本。您可以使用任何兼容 Iceberg 的引擎独立查询副本。
**自动维护的副本**
S3 表类数据存储服务复制会自动维护副本表。复制通常会在源更新后的几分钟内更新副本。S3 表类数据存储服务会按照与源表相同的顺序提交所有更新以保持一致性。
**到多个目标的复制**
您可以将同一个表复制到多个目标表存储桶。复制目标可以位于同一 AWS 区域、跨多个 AWS 区域、位于同一 AWS 账户或者位于其他 AWS 账户。
**独立快照保留**
副本表的快照过期时间独立于源表，这使您可以在需要时为副本表设置不同的保留期。例如，您可以将源表配置为保留快照 30 天，同时为副本表设置 90 天的保留期。如果您在副本上配置了更长的保留期，那么在源中过期的快照在副本中仍然可用和可查询。此配置为历史分析提供了扩展的时间旅行功能。
**在成本较低的存储层中维护副本表**
您可以将目标表存储桶配置为使用 S3 Intelligent-Tiering 存储类别，该类别可根据访问模式自动优化存储成本，而不会影响性能或产生运营开销。S3 Intelligent-Tiering 非常适合访问频率可能较低的副本表。
有关 S3 表类数据存储服务复制的更多信息，请参阅以下主题。
**Topics**
+ [何时使用 S3 表类数据存储服务复制](#s3-tables-replication-tables-when-to-use)
+ [功能](#s3-tables-replication-tables-features)
+ [S3 表类数据存储服务复制的工作方式](s3-tables-replication-how-replication-works.md)
+ [设置 S3 表类数据存储服务复制](s3-tables-replication-setting-up.md)
+ [管理 S3 表类数据存储服务复制](s3-tables-replication-managing.md)
# S3 表类数据存储服务复制的工作方式
S3 表类数据存储服务复制会跨区域和 AWS 账户创建 Apache Iceberg 表的只读副本。副本表由 S3 表类数据存储服务自动维护，包含源表中的完整数据、元数据和快照历史记录，让您可以使用任何兼容 Iceberg 的引擎进行查询，用于分析和时间旅行操作。
当您为表配置复制时，S3 表类数据存储服务会执行以下操作：
+ 在每个目标表存储桶中创建一个名称和命名空间与源表相同的只读副本表。
+ 用源表的最新状态回填副本
+ 监控源表中是否有新的更新
+ 按照与源表相同的顺序将所有更新提交到副本以保持一致性
有关更多信息，请参阅以下部分。
**Topics**
+ [复制的内容](#s3-tables-replication-what-is-replicated)
+ [数据复制方式](#s3-tables-replication-how-data-replicated)
+ [快照复制](#s3-tables-replication-snapshot-replication)
+ [注意事项和限制](#s3-tables-replication-considerations-limitations)
## 复制的内容
将复制以下表组件：
+ **表快照**：所有快照（包括压缩快照）均按时间顺序复制，以保留源表中的父子关系和序列号。这将确保副本表提供与源表相同的时间旅行功能。
+ **表数据**：表快照引用的所有数据文件都将复制到目标区域。这包括：
+ **元数据文件**：表 metadata.json 文件、清单、清单列表、分区统计信息和表统计信息。
+ **删除文件**：所有删除文件都会被复制，以确保副本表中数据的准确性。
+ **数据文件**：清单引用的所有数据文件都会被复制。
+ **表元数据**：完整的元数据复制，包括架构信息（当前和历史）、分区规范、排序顺序和表属性。
+ **架构信息**：所有表架构都会被复制，包括当前架构版本和历史架构版本。这将确保对副本表的查询使用正确的列定义、数据类型和字段映射。复制过程会保留架构演进历史记录，使时空旅行查询能够在副本表上正常执行。
+ **分区规范**：当前和历史分区规范会被复制，以确保副本表采用与源表相同的分区策略。
+ **排序顺序**：表排序顺序会被复制，以维持查询性能优化。
## 数据复制方式
复制通过比较源表与副本表的 Apache Iceberg 表元数据来确定副本表的有效状态。复制会处理三个类别的元数据以更新您的副本表。
### 对于表元数据
对于受版本控制的元数据字段，复制会将源表中的值合并到副本表的以下字段对应的数组：
+ `snapshots`：按照 snapshot-id 将源表中的所有快照合并到副本表的 snapshots 数组。
+ `snapshot-log`：按照时间戳和 snapshot-id 将源表中的快照日志合并到副本表的 snapshot-log 数组。
+ `sort-orders`：按照 order-id 将源表中的排序顺序定义合并到副本表的 sort-orders 数组。
+ `partition-specs`：按照 spec-id 将源表中的分区规范合并到副本表的 partition-specs 数组。
### 对于表配置
对于表示表配置的字段，复制操作会直接从源表复制值：
+ `properties`
+ `partition-statistics`
+ `statistics`
当前表状态也会从源表传输过来：
+ `current-snapshot-id`
+ `current-schema-id`
+ `last-column-id`
+ `last-partition-id`
+ `last-sequence-number`
+ `default-sort-order-id`
+ `next-row-id`（Iceberg V3）
+ `encryption-keys`（Iceberg V3）
### 特定于副本的状态
以下字段根据合并后的数据计算得出，并针对副本表进行了更新：
+ `location` 在复制期间更新为指向副本表存储桶中的正确文件位置，从而确保所有文件引用在目标环境中均有效。
+ `metadata-log` 包含所有目标元数据文件名，并且每次成功复制后都会使用当前元数据文件名进行更新。
+ 所有文件路径均已修改为指向副本表位置。
## 快照复制
S3 表类数据存储服务复制按照与源表相同的提交顺序复制所有表快照，从而跨区域维护完整的快照历史记录。源表中的父子关系将保留在副本表中。
### 快照保留
您可以为复制的表配置与源表保留期不同的自定义快照保留期。这意味着，即使快照在源表中已过期且不再可用，它们仍然可以在副本中保留。
例如，如果源表的快照保留期为 30 天，但副本表的保留期配置为 90 天，则副本将保留源表中不再可用的前两个月的快照。
您在源表中手动过期的快照也会保留在副本表中。例如，如果您在源表中使用 Spark 过程使 2 月份的快照过期，您仍然可以访问副本表中的这些快照。
## 注意事项和限制
以下注意事项适用于复制的表：
+ S3 表类数据存储服务会同时复制 Iceberg V2 表和 V3 表。但是，不支持复制升级后的表（V2 → V3）。
+ 不支持大小超过 500 MB 的元数据文件。
+ 虽然表更新通常会在数分钟内完成复制，但复制所需的时间可能会根据要复制的表更新大小而延长，例如，当复制开始回填时。
+ 不支持带有标签或分支的表。
+ Amazon S3 元数据表或其他 AWS 生成的系统表不支持复制。
+ 所有表快照（包括压缩快照）均从源表复制。因此，副本表不支持压缩。
# 设置 S3 表类数据存储服务复制
您可以设置复制，以便自动从源表创建表副本并将其复制到最多五个目标表存储桶。可以在存储桶级别（应用于存储桶中的所有表）或表级别（针对特定表）配置复制。本主题介绍如何使用 Amazon S3 控制台或 AWS 命令行界面（AWS CLI）配置复制。
有关设置复制的更多信息，请参阅以下主题。
**Topics**
+ [设置复制的先决条件](#s3-tables-replication-prerequisites)
+ [了解复制配置](#s3-tables-replication-understanding-configurations)
+ [在存储桶级别的复制与表级别的复制之间做出选择](#s3-tables-replication-choosing-configuration)
+ [使用 Amazon S3 控制台设置复制](#s3-tables-replication-console)
+ [使用 AWS CLI 设置复制](#s3-tables-replication-cli)
## 设置复制的先决条件
在配置复制之前，请确保您拥有：
### 所需的资源
+ **源表存储桶**：包含要复制的表的表存储桶
+ **目标表存储桶**：要将您的表复制到的一个或多个表存储桶（最多 5 个目标表存储桶）
+ **源表**：源表存储桶中要复制的现有表
+ **IAM 角色**：一个 IAM 角色，用于授予 Amazon S3 权限以代表您复制表
### 所需的权限
您用于设置复制的 IAM 身份必须具有以下权限：
**对于存储桶级别的复制：**
+ 源表存储桶上的 `s3tables:PutTableBucketReplication`
+ 源表存储桶上的 `s3tables:GetTableBucketReplication`
+ 针对复制 IAM 角色的 `iam:PassRole`
**对于表级别的复制：**
+ 源表上的 `s3tables:PutTableReplication`
+ 源表上的 `s3tables:GetTableReplication`
+ 针对复制 IAM 角色的 `iam:PassRole`
**对于跨账户复制：**
+ 来自目标账户的存储桶策略的权限
### 对跨账户复制的额外要求
如果您的源表存储桶和目标表存储桶位于不同的 AWS 账户中，您还需要：
+ 目标表存储桶上的存储桶策略，该策略用于为源账户授予复制表的权限
+ 目标账户 ID 和表存储桶 Amazon 资源名称（ARN）
### 对加密表的额外要求
如果您要使用 AWS KMS 加密副本表，则需要：
+ 目标区域中的 KMS 密钥
+ 在您的 IAM 复制角色中使用该 KMS 密钥的权限
+ 允许复制角色加密数据的 KMS 密钥策略
## 了解复制配置
复制配置定义了 Amazon S3 如何从您的源表存储桶复制表。可以在两个级别配置复制：
### 存储桶级别的复制
存储桶级别的复制配置将应用于源表存储桶中的所有表。当您配置存储桶级别的复制时，Amazon S3 会自动复制存储桶中创建的所有现有表和新表。
在以下情况下使用存储桶级别的复制：
+ 您希望复制存储桶中的所有表
+ 您希望所有表的复制行为保持一致
+ 您希望通过单一配置来简化管理
### 表级别的复制
表级别的复制配置将应用于特定表。表级别配置会覆盖该特定表的存储桶级别配置。
在以下情况下使用表级别的复制：
+ 您只希望复制特定表
+ 您需要为不同的表设置不同的复制目标
+ 您希望覆盖某些表的存储桶级别配置
### 复制配置元素
每个复制配置都包含：
+ **IAM 角色**：Amazon S3 代入的用于执行复制操作的角色
+ **规则**：一条或多条复制规则（启动时限制为 1 条规则）。每条规则都包含：
+ **目标**：目标表存储桶 ARN 的列表（最多 5 个目标）
+ **状态**：规则是已启用还是已禁用
+ **版本令牌**：用于在更新配置时防止写入冲突的令牌
## 在存储桶级别的复制与表级别的复制之间做出选择
### 配置优先级
当存储桶级别的配置和表级别的配置同时存在时：
+ 对于该特定表，表级别的配置优先。
+ 其他表遵循存储桶级别的配置。
## 使用 Amazon S3 控制台设置复制
此过程说明如何使用 Amazon S3 控制台配置复制。
### 设置存储桶级别的复制
此过程说明如何使用 Amazon S3 控制台创建表存储桶复制配置。表存储桶复制配置将应用于源表存储桶中的所有表。
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在导航窗格中，选择**表存储桶**。
1. 在**表存储桶**列表中，选择要为其配置复制的表存储桶的名称。
1. 选择**管理**选项卡。
1. 在**表存储桶复制配置**部分，选择**创建表存储桶复制配置**。
1. 在**目标**部分，配置您的复制目标：
1. 在**表存储桶 ARN** 字段中，输入目标表存储桶的 ARN。格式为：`arn:aws:s3tables:region:account-id:bucket/table-bucket-name`
或者，也可以选择**浏览 S3** 以从您的账户中选择表存储桶。
1. （可选）要添加其他目标，请选择**添加目标**。您可以再添加最多 4 个表存储桶，对应总共 5 个目标。
1. 在 **IAM 角色**部分中，配置复制角色：
1. 对于 **IAM 角色选择方法**，选择以下选项之一：
+ **创建新的 IAM 角色**：Amazon S3 将创建一个具有所需复制权限的新角色。
+ **从现有 IAM 角色中选择**：选择具有所需复制权限的现有角色。
+ **输入 IAM 角色 ARN**：手动输入现有 IAM 角色的 ARN。
1. 如果您选择了**从现有 IAM 角色中选择**，请从 **IAM 角色**下拉列表中选择一个角色。
1. （可选）选择**查看**以在 IAM 控制台中查看所选角色的权限。
1. 选择**创建复制配置**。
创建复制配置后，Amazon S3 会开始初始回填过程。您可以在**表复制状态**部分中监控复制状态，该部分显示了有关每个目标的信息，包括复制状态、目标表 ARN 和上次复制的元数据。
### 设置表级别的复制
此过程说明如何使用 Amazon S3 控制台创建表级别的复制配置。表复制配置将应用于特定表，并覆盖该表的任何存储桶级别的复制配置。
1. 登录到 AWS 管理控制台，然后通过以下网址打开 Amazon S3 控制台：[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)。
1. 在导航窗格中，选择**表存储桶**。
1. 在**表存储桶**列表中，选择包含要复制的表的表存储桶的名称。
1. 选择 **Tables (表)** 选项卡。
1. 在**表**列表中，选择要复制的表的名称。
1. 选择**管理**选项卡。
1. 在**表复制配置**部分，选择**创建表复制配置**。
1. 在**目标**部分，配置您的复制目标：
1. 在**表存储桶 ARN** 字段中，输入目标表存储桶的 ARN。格式为：`arn:aws:s3tables:region:account-id:bucket/table-bucket-name`
或者，也可以选择**浏览 S3** 以从您的账户中选择表存储桶。
1. （可选）要添加其他目标，请选择**添加目标**。您可以再添加最多 4 个表存储桶，对应总共 5 个目标。
1. 在 **IAM 角色**部分中，配置复制角色：
1. 对于 **IAM 角色选择方法**，选择以下选项之一：
+ **创建新的 IAM 角色**：Amazon S3 将创建一个具有所需复制权限的新角色。
+ **从现有 IAM 角色中选择**：选择具有所需复制权限的现有角色。
+ **输入 IAM 角色 ARN**：手动输入现有 IAM 角色的 ARN。
1. 如果您选择了**从现有 IAM 角色中选择**，请从 **IAM 角色**列表中选择一个角色。
1. （可选）选择**查看**以在 IAM 控制台中查看所选角色的权限。
1. 选择**创建复制配置**。
### 接下来会发生什么？
在您创建复制配置后：
+ Amazon S3 开始初始回填过程，在每个目标存储桶中创建副本表
+ 回填开始后，复制状态将更改为**正在复制**
+ 您可以在**管理**选项卡上监控复制进度
+ 初始复制时间取决于源表的大小
## 使用 AWS CLI 设置复制
此过程介绍如何使用 AWS CLI 配置复制。将账户 ID、区域和存储桶名称替换为实际值，并将所有目标存储桶添加到权限。
### 步骤 1：创建用于复制的 IAM 角色
首先，创建一个 Amazon S3 可以代入的 IAM 角色，用于复制您的表。
1. 创建一个信任策略文档，该文档允许 S3 表类数据存储服务代入该角色。将其另存为 `trust-policy.json`：
```
{
"Version": "2012-10-17"
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "replication.s3tables.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
1. 创建 IAM 角色：
```
aws iam create-role \
--role-name S3TablesReplicationRole \
--assume-role-policy-document file://trust-policy.json \
--description "Role for S3 Tables replication"
```
1. 创建授予复制权限的权限策略。将其另存为 `replication-permissions.json`：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3tables:GetTable",
"s3tables:GetTableMetadataLocation",
"s3tables:GetTableMaintenanceConfiguration",
"s3tables:GetTableData"
],
"Resource": "arn:aws:s3tables:us-east-2:111122223333:bucket/amzn-s3-demo-table-bucket-source/table/*"
},
{
"Effect": "Allow",
"Action": [
"s3tables:ListTables"
],
"Resource": "arn:aws:s3tables:us-east-2:111122223333:bucket/amzn-s3-demo-table-bucket-source"
},
{
"Effect": "Allow",
"Action": [
"s3tables:CreateTable",
"s3tables:CreateNamespace"
],
"Resource": "arn:aws:s3tables:us-east-2:444455556666:bucket/amzn-s3-demo-table-bucket-destination"
},
{
"Effect": "Allow",
"Action": [
"s3tables:PutTableData",
"s3tables:GetTableData",
"s3tables:UpdateTableMetadataLocation",
"s3tables:PutTableMaintenanceConfiguration"
],
"Resource": "arn:aws:s3tables:us-east-2:444455556666:bucket/amzn-s3-demo-table-bucket-destination/table/*"
}
]
}
```
1. 将权限策略附加到角色：
```
aws iam put-role-policy \
--role-name S3TablesReplicationRole \
--policy-name S3TablesReplicationPermissions \
--policy-document file://replication-permissions.json
```
1. （可选）如果使用了 KMS 加密，请将 KMS 权限添加到您的策略：
```
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey",
"kms:Encrypt"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/SOURCE-KEY-ID"
},
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": [
"arn:aws:kms:us-west-2:444455556666:key/DESTINATION-KEY-ID-1"
]
}
```
### （仅限跨账户）步骤 2：配置目标存储桶策略
如果要复制到其他 AWS 账户，则目标账户必须向源账户授予权限。
1. 在目标账户中，为目标表存储桶创建一个存储桶策略。将其另存为 `destination-bucket-policy.json`：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/cross-account-test"
},
"Action": [
"s3tables:PutTableData",
"s3tables:GetTableData",
"s3tables:UpdateTableMetadataLocation",
"s3tables:PutTableMaintenanceConfiguration"
],
"Resource": "arn:aws:s3tables:us-east-2:111122223333:bucket/amzn-s3-demo-table-bucket-cross-account-destination/table/*"
},
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:role/cross-account-test"
},
"Action": [
"s3tables:CreateTable",
"s3tables:CreateNamespace"
],
"Resource": "arn:aws:s3tables:us-east-2:111122223333:bucket/amzn-s3-demo-table-bucket-cross-account-destination"
}
]
}
```
1. 使用 S3 表类数据存储服务 API 应用策略：
```
aws s3tables put-table-bucket-policy \
--table-bucket-arn arn:aws:s3tables:us-west-2:444455556666:bucket/amzn-s3-demo-table-bucket-cross-account-destination \
--policy file://destination-bucket-policy.json \
--profile destination-account
```
1. 修改您的源 KMS 密钥以允许 S3 表类数据存储服务复制和维护：
```
{
"Version": "2012-10-17",
"Id": "key-consolepolicy-3",
"Statement": [
{
"Sid": "allow replication to decrypt",
"Effect": "Allow",
"Principal": {
"AWS": "replication_role_arn"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/SOURCE-KEY-ID"
},
{
"Sid": "allow maintenance",
"Effect": "Allow",
"Principal": {
"Service": "maintenance.s3tables.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/SOURCE-KEY-ID"
}
]
}
```
1. 同样，在目标 KMS 密钥策略中添加权限
```
{
"Version": "2012-10-17",
"Id": "key-policy-3",
"Statement": [
{
"Sid": "allow maintenance",
"Effect": "Allow",
"Principal": {
"Service": "maintenance.s3tables.amazonaws.com"
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-west-2:444455556666:key/DESTINATION-KEY-ID-1"
},
{
"Sid": "allow replication to encrypt/decrypt",
"Effect": "Allow",
"Principal": {
"AWS": "replication_role_arn"
},
"Action": [
"kms:Encrypt",
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-west-2:444455556666:key/DESTINATION-KEY-ID-1"
}
]
```
### 步骤 3：创建复制配置
您可以使用 AWS CLI 在表存储桶级别或表级别创建复制配置。有关更多信息，请参阅以下流程。
#### 创建存储桶级别的复制配置
使用此方法可复制存储桶中的所有表。
1. 创建复制配置文件。将其另存为 `bucket-replication-config.json`：
**Example ：同一个账户中的单个目标**
```
{
"role": "arn:aws:iam::111122223333:role/S3TablesReplicationRole",
"rules": [
{
"destinations": [
{
"destinationTableBucketARN": "arn:aws:s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket-dr"
}
]
}
]
}
```
**Example ：跨区域的多个目标**
```
{
"role": "arn:aws:iam::111122223333:role/S3TablesReplicationRole",
"rules": [
{
"destinations": [
{
"destinationTableBucketARN": "arn:aws:s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket-dr"
},
{
"destinationTableBucketARN": "arn:aws:s3tables:eu-west-1:111122223333:bucket/amzn-s3-demo-table-bucket-eu"
},
{
"destinationTableBucketARN": "arn:aws:s3tables:ap-south-1:111122223333:bucket/amzn-s3-demo-table-bucket-apac"
}
]
}
]
}
```
**Example ：跨账户复制**
```
{
"role": "arn:aws:iam::111122223333:role/S3TablesReplicationRole",
"rules": [
{
"destinations": [
{
"destinationTableBucketARN": "arn:aws:s3tables:us-east-1:444455556666:bucket/amzn-s3-demo-table-bucket-partner"
}
]
}
]
}
```
1. 应用存储桶级别的复制配置：
```
aws s3tables put-table-bucket-replication \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket \
--configuration file://bucket-replication-config.json
```
预期输出：
```
{
"versionToken": "3HL4kqtJl40Nr8X8gdRQBpUMLUo",
"status": "Success"
}
```
#### 创建表级别的复制配置
使用此方法可复制特定表或覆盖存储桶级别的复制。
1. 创建复制配置文件。将其另存为 `table-replication-config.json`：
**Example ：单个表复制**
```
{
"role": "arn:aws:iam::111122223333:role/S3TablesReplicationRole",
"rules": [
{
"destinations": [
{
"destinationTableBucketARN": "arn:aws:s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket-analytics-bucket"
}
]
}
]
}
```
**Example ：包含多个目标的表**
```
{
"role": "arn:aws:iam::111122223333:role/S3TablesReplicationRole",
"rules": [
{
"destinations": [
{
"destinationTableBucketARN": "arn:aws:s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket-dr"
},
{
"destinationTableBucketARN": "arn:aws:s3tables:eu-west-1:111122223333:bucket/amzn-s3-demo-table-bucket-eu"
}
]
}
]
}
```
1. 应用表级别的复制配置：
```
aws s3tables put-table-replication \
--table-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket/table/amzn-s3-demo-table-bucket-sales-data \
--configuration file://table-replication-config.json
```
预期输出：
```
{
"versionToken": "xT2LZkFZ0UuTC2h8XqtGLx2Ak6M",
"status": "Success"
}
```
# 管理 S3 表类数据存储服务复制
在配置 S3 表类数据存储服务复制后，您可以监控副本状态以验证复制的内容。您可以在 Amazon S3 控制台的源表的**管理**选项卡中或使用 AWS CLI 查看复制状态。有关更多信息，请参阅[设置 S3 表类数据存储服务复制](s3-tables-replication-setting-up.md)。本主题介绍如何监控复制和了解指示复制已完成、正在进行或已失败的不同状态值。
## 监控复制状态
所复制表的复制作业会持续运行。您可以使用 GetTableReplicationStatus API 查询复制的状态，也可以在 Amazon S3 控制台中查看。
### 使用 AWS CLI 获取复制的状态
以下示例使用 GetTableReplicationStatus API 获取复制的状态。
```
aws s3tables get-table-replication-status \
--table-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket/table/sales-data
```
预期输出：
```
{
"sourceTableARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket/table/sales-data",
"destinations": [
{
"replicationStatus": "COMPLETED",
"destinationBucketARN": "arn:aws:s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket",
"destinationTableARN": "arn:aws:s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-table-bucket/table/sales-data",
"lastSuccessfulReplicatedUpdate": {
"metadataLocation": "latest_table_metadata.json",
"timestamp": "2025-11-15T14:30:00Z"
}
},
{
"replicationStatus": "PENDING",
"destinationBucketARN": "arn:aws:s3tables:eu-west-1:111122223333:bucket/amzn-s3-demo-table-bucket-eu-bucket",
"destinationTableARN": "arn:aws:s3tables:eu-west-1:111122223333:bucket/amzn-s3-demo-table-bucket-eu-bucket/table/sales-data",
"lastSuccessfulReplicatedUpdate": {
"metadataLocation": "latest_table_metadata.json",
"timestamp": "2025-11-15T14:25:00Z"
}
}
]
}
```
有关更多信息，请参阅《AWS CLI 命令参考》**中的 [get-table-replication-status](https://docs.aws.amazon.com/cli/latest/reference/s3tables/get-table-replication-status.html)。
### 了解响应
响应包含以下元素：
+ **sourceTableARN**：要复制的源表的 ARN。
+ **destinations**：目标状态对象的数组，每个已配置的复制目标对应一个。每个目标对象都包含：
+ **replicationStatus**：此目标的当前复制状态（COMPLETED、PENDING 或 FAILED）。
+ **destinationBucketARN**：目标表存储桶的 ARN。
+ **destinationTableARN**：目标存储桶中副本表的 ARN。
+ **lastSuccessfulReplicatedUpdate**：有关最近成功的复制的信息：
+ **metadataLocation**：上次成功复制的 Iceberg 元数据文件名。将其与源表的当前元数据位置进行比较，以确定复制是否为最新。
+ **timestamp**：将此元数据文件复制到目标的时间。
+ **failureMessage**（仅在状态为 FAILED 时出现）：描述复制失败原因的详细错误消息。
### 复制状态值
对于每个目标表，复制可能有三种状态：
+ **COMPLETED**：所有源表快照已成功复制到目标。源表的最新元数据位置与上次复制的元数据位置匹配。
+ **PENDING**：正在进行复制或正在等待复制新提交的内容。源表的最新元数据位置与上次复制的元数据位置不同。
+ **FAILED**：此表的最后一个复制作业失败。没有新的更新正在复制中。
# S3 表类数据存储服务 AWS 区域、端点和服务配额
以下各节包括 S3 表类数据存储服务支持的 AWS 区域和服务配额。
**Topics**
+ [S3 表类数据存储服务 AWS 区域和端点](#s3-tables-regions)
+ [S3 表类数据存储服务配额](#s3-tables-quotas)
## S3 表类数据存储服务 AWS 区域和端点
有关 S3 表类数据存储服务当前可用的区域的列表，请参阅 [Amazon S3 endpoints](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region)。要通过编程方式连接到 AWS 服务，您需要使用端点。有关更多信息，请参阅[AWS服务端点](https://docs.aws.amazon.com/general/latest/gr/rande.html)。
S3 表类数据存储服务支持将双堆栈端点用于公共访问和 AWS PrivateLink。除了 IPv4 协议之外，双堆栈端点还支持您使用互联网协议版本 6（IPv6）访问 S3 表存储桶，具体取决于网络支持的协议版本。
S3 表类数据存储服务双堆栈端点使用以下命名约定：`s3tables.aws-region.api.aws`
有关 S3 表类数据存储服务端点的完整列表，请参阅 [Amazon S3 endpoints](https://docs.aws.amazon.com/general/latest/gr/s3.html#s3_region)。
## S3 表类数据存储服务配额
配额（也称为限制）是 AWS 账户的服务资源或操作的最大数量。以下是 S3 表类数据存储服务资源的配额。有关 Amazon S3 配额的更多信息，请参阅 [Amazon S3 quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html#limits_s3)。
| 名称 | 默认值 | 可调整 | 说明 |
| --- | --- | --- | --- |
| 表存储桶 | 10 | 要请求提高配额，请联系 [支持](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)。 | 您可以在账户中为每个 AWS 区域创建的 Amazon S3 表存储桶的数量。 |
| 命名空间 | 10000 | 要请求提高配额，请联系 [支持](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)。 | 可以在每个表存储桶中创建的 Amazon S3 表命名空间的数量。 |
| 表 | 10000 | 要请求提高配额，请联系 [支持](https://console.aws.amazon.com/support/home#/case/create?issueType=service-limit-increase)。 | 可以在每个表存储桶中创建的 Amazon S3 表类数据存储服务的数量。 |
# 通过 IPv6 向 S3 表类数据存储服务发出请求
除了 IPv4 协议之外，Amazon S3 还支持使用互联网协议版本 6（IPv6）通过双堆栈端点访问 S3 存储桶的功能。双堆栈端点可以解析为 IPv6 端点或 IPv4 端点，具体取决于网络支持的协议版本。
下面是在尝试通过 IPv6 访问 S3 表类数据存储服务之前应了解的一些事项：
+ 访问表存储桶的客户端和网络必须支持使用 IPv6。
+ 表客户端和 S3 客户端都必须启用了双堆栈。
+ 如果您使用 IP 地址筛选 IAM 策略，则必须对这些策略进行更新才能处理 IPv6 地址。有关使用 IAM 管理访问权限的更多信息，请参阅 [Amazon S3 的身份和访问管理](security-iam.md)。
+ 如果使用 IPv6，服务器访问日志文件以 IPv6 格式输出 IP 地址。您需要对用于分析 Amazon S3 日志文件的现有工具、脚本和软件进行更新，以便它们能够分析 IPv6 格式的 `Remote IP` 地址。有关更多信息，请参阅 [使用服务器访问日志记录来记录请求](ServerLogs.md)。
## 通过 IPv6 发出 S3 表类数据存储服务请求入门
当您向双堆栈端点发出请求时，表存储桶 URL 解析为 IPv6 或 IPv4 地址，具体取决于网络支持的协议版本。如果您的网络优先使用 IPv4，则请求将自动使用 IPv4。如果您的网络优先使用 IPv6，则请求将使用 IPv6。除了更新客户端或应用程序以启用双堆栈端点之外，无需更改任何其它配置。
当使用 REST API 时，您通过使用端点名称（URI）直接访问 Amazon S3 端点。您可以使用以下命名约定，通过双堆栈端点访问 S3 表类数据存储服务和表存储桶：
`s3tables..api.aws`
有关 S3 表类数据存储服务的端点的完整列表，请参阅 [Amazon Simple Storage Service endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/s3.html)。
如果使用 AWS CLI、AWS SDK 和 Iceberg 客户端，则可以使用参数或标志以更改为双堆栈端点。您还可以在配置文件中直接将双堆栈端点指定为覆盖 Amazon S3 端点。
您可以通过使用以下命令设置双堆栈标志，在 SDK 或客户端中启用双堆栈端点解析：
```
S3TablesClient client = S3TablesClient.builder()
.region(Region.US_EAST_1)
.dualstackEnabled(true)
.build();
```
要在 AWS CLI 中使用双堆栈端点，请参阅 [Using dual-stack endpoints from the AWS CLI](https://docs.aws.amazon.com/AmazonS3/latest/API/dual-stack-endpoints.html#dual-stack-endpoints-cli)。
有关为 AWS PrivateLink 使用双堆栈端点的信息，请参阅[使用双堆栈端点访问表和表存储桶](s3-tables-VPC.md#s3-tables-dual-stack-endpoints)。
# S3 表类数据存储服务的安全性
Amazon S3 提供了各种安全功能和工具。以下是 S3 表类数据存储服务支持的这些功能和工具的列表。正确应用这些工具有助于确保资源受到保护，且只有目标用户才能访问这些资源。
**基于身份的策略**
[基于身份的策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html)附加到 IAM 用户、组或角色。您可以使用基于身份的策略，来向 IAM 身份授予对表存储桶或表的访问权限。默认情况下，用户和角色不拥有创建和修改表和表存储桶的权限。他们也无法通过 S3 控制台、AWS CLI 或 Amazon S3 REST API 执行任务。您可以在您的账户中创建 IAM 用户、组和角色，并为其附加访问策略。然和，您可以授予对资源的访问权限。要创建和访问表存储桶和表，IAM 管理员必须向 AWS Identity and Access Management（IAM）角色或用户授予必要的权限。有关更多信息，请参阅 [S3 表类数据存储服务的访问管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-setting-up.html)。
**基于资源的策略**
[基于资源的策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_identity-vs-resource.html)附加到某个资源。您可以为表存储桶和表创建基于资源的策略。您可以使用表存储桶策略来控制表存储桶和命名空间级的 API 访问权限。还可以使用表存储桶策略来控制对存储桶中多个表的表级 API 权限。根据策略定义，附加到存储桶的权限可以应用于存储桶中的所有表或特定表。还可以使用表策略来授予对存储桶中各个表的表级 API 访问权限。
当 S3 表类数据存储服务收到执行表存储桶操作或表操作的请求时，它首先验证请求者是否拥有必要的权限。它对所有相关访问策略、用户策略和基于资源的策略（IAM 用户策略、IAM 角色策略、表存储桶策略和表策略）进行评估，以决定是否对该请求进行授权。通过表存储桶策略和表策略，您可以对资源的访问权限进行个性化设置，以确保只有您已批准的身份才能访问您的资源并对其执行操作。有关更多信息，请参阅 [S3 表类数据存储服务的访问管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-tables-setting-up.html)。
**S3 表类数据存储服务的 AWS Organizations 服务控制策略（SCP）。**
可以在服务控制策略（SCP）中使用 Amazon S3 表类数据存储服务来管理组织中用户的权限。与 IAM 和资源策略类似，所有表和存储桶级操作都作为 `s3tables` 命名空间的一部分在策略中引用。有关更多信息，请参阅《AWS Organizations 用户指南》**中的[服务控制策略（SCP）](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html)。
**Topics**
+ [使用加密保护 S3 表数据](s3-tables-encryption.md)
+ [S3 表类数据存储服务的访问管理](s3-tables-setting-up.md)
+ [S3 表类数据存储服务的 VPC 连接](s3-tables-VPC.md)
+ [S3 表类数据存储服务的安全注意事项和限制](s3-tables-restrictions.md)
# 使用加密保护 S3 表数据
# 在表存储桶中使用具有 AWS KMS 密钥的服务器端加密（SSE-KMS）
**Topics**
+ [SSE-KMS 存储桶如何用于表和表存储桶](#kms-tables-how)
+ [对表和表存储桶强制使用 SSE-KMS 并确定其范围](tables-require-kms.md)
+ [监控和审计表和表存储桶的 SSE-KMS 加密](#kms-tables-audit)
+ [S3 表类数据存储服务 SSE-KMS 加密的权限要求](s3-tables-kms-permissions.md)
+ [在表存储桶中指定具有 AWS KMS 密钥的服务器端加密（SSE-KMS）](s3-tables-kms-specify.md)
表存储桶具有默认加密配置，该配置通过使用具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3）来自动加密表。此加密适用于 S3 表存储桶中的所有表，而您无需支付任何费用。
如果您需要对加密密钥进行更多控制，例如管理密钥轮换和访问策略授予，则可以将表存储桶配置为使用具有 AWS Key Management Service（AWS KMS）密钥的服务器端加密（SSE-KMS）。AWS KMS 中的安全控制可帮助您满足与加密相关的合规性要求。有关 SSE-KMS 的更多信息，请参阅 [使用具有 AWS KMS 密钥的服务器端加密（SSE-KMS）](UsingKMSEncryption.md)。
## SSE-KMS 存储桶如何用于表和表存储桶
表存储桶中的 SSE-KMS 与通用存储桶中的 SSE-KMS 在以下几个方面有所不同：
+ 您可以为表存储桶和各个表指定加密设置。
+ 您只能将客户自主管理型密钥与 SSE-KMS 结合使用。不支持 AWS 托管式密钥。
+ 您必须向某些角色和 AWS 服务主体授予访问 AWS KMS 密钥的权限。有关更多信息，请参阅 [S3 表类数据存储服务 SSE-KMS 加密的权限要求](s3-tables-kms-permissions.md)。这包括向以下主体授予访问权限：
+ S3 维护主体：用于对加密的表执行表维护
+ S3 表类数据存储服务集成角色：用于在 AWS 分析服务中处理加密的表
+ 客户端访问角色：用于从 Apache Iceberg 客户端直接访问加密的表
+ S3 元数据主体：用于更新加密的 S3 元数据表
+ 加密的表使用表级别密钥，此类密钥可最大限度地减少向 AWS KMS 发出的请求数量，从而提高处理 SSE-KMS 加密表的成本效益。
**表存储桶的 SSE-KMS 加密**
创建表存储桶时，可以选择 SSE-KMS 作为默认加密类型，并选择将用于加密的特定 KMS 密钥。在该存储桶中创建的任何表都将自动从其表存储桶继承这些加密设置。您可以随时使用 AWS CLI、S3 API 或 AWS SDK 来修改或移除表存储桶上的默认加密设置。当您修改表存储桶上的加密设置时，这些设置仅适用于在该存储桶中创建的新表。而不更改先前存在的表的加密设置。有关更多信息，请参阅 [为表存储桶指定加密](s3-tables-kms-specify.md#specify-kms-table-bucket)。
**表的 SSE-KMS 加密**
您还可以选择使用不同的 KMS 密钥来加密单个表，而不管存储桶的默认加密配置如何。要为单个表设置加密，必须在创建表时指定所需的加密密钥。如果要更改现有表的加密，则需要使用所需密钥创建一个表，并将数据从旧表复制到新表。有关更多信息，请参阅 [为表指定加密](s3-tables-kms-specify.md#specify-kms-table)。
使用 AWS KMS 加密时，S3 表类数据存储服务会自动创建唯一的表级别数据密钥，用于加密与每个表关联的新对象。这些密钥在有限的时段内使用，最大限度地减少了在加密操作期间对额外 AWS KMS 请求的需求，并降低了加密成本。这类似于 [SSE-KMS 的 S3 存储桶密钥](bucket-key.md#bucket-key-overview)。
# 对表和表存储桶强制使用 SSE-KMS 并确定其范围
您可以使用 S3 表类数据存储服务基于资源的策略、KMS 密钥策略、基于 IAM 身份的策略或这些策略的任意组合，来强制对 S3 表和表存储桶使用 SSE-KMS。有关表的身份和资源策略的更多信息，请参阅 [S3 表类数据存储服务的访问管理](s3-tables-setting-up.md)。有关编写密钥策略的信息，请参阅《AWS Key Management Service Developer Guide》**中的 [Key policies](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html)。以下示例说明如何使用策略来强制执行 SSE-KMS。
## 使用表存储桶策略强制对所有表使用 SSE-KMS
这是表存储桶策略的示例，该策略禁止用户在特定的表存储桶中创建表，除非他们使用特定 AWS KMS 密钥对表进行加密。要使用此策略，请将*用户输入占位符*替换为您自己的信息：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EnforceKMSEncryption",
"Effect": "Deny",
"Principal": "*",
"Action": [
"s3tables:CreateTable"
],
"Resource": [
"arn:aws:s3tables:us-west-2:111122223333:bucket/example-table-bucket/*"
],
"Condition": {
"StringNotEquals": {
"s3tables:sseAlgorithm": "aws:kms",
"s3tables:kmsKeyArn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
}
}
]
}
```
------
## 要求用户将 SSE-KMS 加密与 IAM 策略结合使用
此 IAM 身份策略要求用户在创建或配置 S3 表类数据存储服务资源时使用特定的 AWS KMS 密钥进行加密。要使用此策略，请将*用户输入占位符*替换为您自己的信息：
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "RequireKMSKeyOnTables",
"Action": [
"s3tables:CreateTableBucket",
"s3tables:PutTableBucketEncryption",
"s3tables:CreateTable"
]
"Effect": "Deny",
"Resource": "*",
"Condition": {
"StringNotEquals": {
"s3tables:sseAlgorithm": "aws:kms",
"s3tables:kmsKeyArn": ""
}
}
}
]
}
```
## 使用 KMS 密钥策略将密钥的使用限制为特定的表存储桶
此示例 KMS 密钥策略仅让特定用户将密钥用于特定表存储桶中的加密操作。这种类型的策略对于在跨账户场景中限制对密钥的访问非常有用。要使用此策略，请将*用户输入占位符*替换为您自己的信息：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "Id",
"Statement": [
{
"Sid": "AllowPermissionsToKMS",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:root"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringLike": {
"kms:EncryptionContext:aws:s3:arn": "/*"
}
}
}
]
}
```
------
## 监控和审计表和表存储桶的 SSE-KMS 加密
要审计为 SSE-KMS 加密数据使用 AWS KMS 密钥的情况，您可以使用 AWS CloudTrail 日志。您可以深入了解自己的[加密操作](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#cryptographic-operations)，例如 `GenerateDataKey` 和 `Decrypt`。CloudTrail 支持多种[属性值](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_LookupEvents.html)来筛选您的搜索，包括事件名称、用户名和事件源。
可以使用 CloudTrail 事件跟踪 Amazon S3 表和表存储桶的加密配置请求。CloudTrail 日志中使用以下 API 事件名称：
+ `s3tables:PutTableBucketEncryption`
+ `s3tables:GetTableBucketEncryption`
+ `s3tables:DeleteTableBucketEncryption`
+ `s3tables:GetTableEncryption`
+ `s3tables:CreateTable`
+ `s3tables:CreateTableBucket`
**注意**
表存储桶不支持 EventBridge。
# S3 表类数据存储服务 SSE-KMS 加密的权限要求
当您对 S3 表存储桶中的表使用具有 AWS Key Management Service（AWS KMS）密钥的服务器端加密（SSE-KMS）时，您需要为账户中的不同身份授予权限。您的访问身份和 S3 表类数据存储服务维护主体至少需要具有访问您的密钥的权限，所需的其它权限取决于您的应用场景。
**所需权限**
要访问使用 KMS 密钥加密的表，您需要对该密钥具有以下权限：
+ `kms:GenerateDataKey`
+ `kms:Decrypt`
要对表使用 SSE-KMS，Amazon S3 表类数据存储服务维护服务主体 (`maintenance.s3tables.amazonaws.com`) 需要对密钥具有 `kms:GenerateDataKey` 和 `kms:Decrypt` 权限。
**其他权限**
根据您的应用场景，需要以下附加权限：
+ **AWS 分析服务集成的权限**：如果您在 AWS 分析服务中使用由 SSE-KMS 加密的表，则集成角色需要具有使用 KMS 密钥的权限。
+ **直接访问的权限**：如果您通过诸如 Amazon S3 表类数据存储服务 Iceberg REST 端点或适用于 Apache Iceberg 的 Amazon S3 表类数据存储服务目录之类的方法直接使用由 SSE-KMS 加密的表，则需要向客户端使用的 IAM 角色授予访问您的密钥的权限。
+ **S3 元数据表的权限**：如果您对 S3 元数据表使用 SSE-KMS 加密，则需要向 S3 元数据服务主体 (`metadata.s3.amazonaws.com`) 提供对 KMS 密钥的访问权限。这可让 S3 元数据更新加密的表，这样它们就能够反映您的最新数据更改。
**注意**
对于跨账户 KMS 密钥，您的 IAM 角色在密钥策略中同时需要密钥访问权限和显式授权。有关 KMS 密钥的跨账户权限的更多信息，请参阅《AWS Key Management Service Service Developer Guide》**中的 [Allowing external AWS accounts to use a KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-modifying-external-accounts.html#cross-account-console)。
**Topics**
+ [向 S3 表类数据存储服务维护服务主体授予对 KMS 密钥的权限](#tables-kms-maintenance-permissions)
+ [向 IAM 主体授予在集成的 AWS 分析服务中使用加密表的权限](#tables-kms-integration-permissions)
+ [向 IAM 主体授予直接使用加密表的权限](#tables-kms-direct-permissions)
+ [向 S3 元数据服务主体授予使用您的 KMS 密钥的权限](#tables-kms-metadata-permissions)
## 向 S3 表类数据存储服务维护服务主体授予对 KMS 密钥的权限
需要此权限才能创建通过 SSE-KMS 加密的表，并支持对加密的表进行自动表维护，例如压缩、快照管理和未引用文件移除。
**注意**
每当您发出请求来创建通过 SSE-KMS 加密的表时，S3 表类数据存储服务都会进行检查，以确保 `maintenance.s3tables.amazonaws.com` 主体有权访问您的 KMS 密钥。要执行此检查，需要在表存储桶中临时创建一个零字节对象，而[未引用文件移除](s3-table-buckets-maintenance.md#s3-table-bucket-maintenance-unreferenced)维护操作将自动移除该对象。如果您为加密指定的 KMS 密钥没有维护访问权限，则 createTable 操作将失败。
要授予对通过 SSE-KMS 加密的表的维护访问权限，您可以使用以下示例密钥策略。在此策略中，向 `maintenance.s3tables.amazonaws.com` 服务主体授予使用特定 KMS 密钥对特定表存储桶中的表进行加密和解密的权限。要使用此策略，请将*用户输入占位符*替换为您自己的信息：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EnableKeyUsage",
"Effect": "Allow",
"Principal": {
"Service": "maintenance.s3tables.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "arn:aws:kms:us-east-1:111122223333:key/key-id",
"Condition": {
"StringLike": {
"kms:EncryptionContext:aws:s3:arn":"/*"
}
}
}
]
}
```
------
## 向 IAM 主体授予在集成的 AWS 分析服务中使用加密表的权限
要在 AWS 分析服务中使用 S3 表，可以将表存储桶与 Amazon SageMaker 智能湖仓集成。这种集成支持 AWS 分析服务自动发现和访问表数据。有关集成的更多信息，请参阅[将 Amazon S3 表类数据存储服务与 AWS 分析服务集成](s3-tables-integrating-aws.md)。
当您在这些服务中使用通过 SSE-KMS 加密的表时，您使用的角色需要拥有使用 AWS KMS 密钥进行加密操作的权限。您可以将这些权限应用于在集成期间创建的 `S3TablesRoleForLakeFormation` 角色或您自己的 IAM 角色。
以下内联 IAM 策略示例可用于向 `S3TablesRoleForLakeFormation` 服务角色授予使用您账户中的特定 KMS 密钥进行加密操作的权限。要使用此策略，请将*输入占位符值*替换为您自己的信息。
```
{
"Sid": "AllowTableRoleAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/service-role/S3TablesRoleForLakeFormation"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": ""
}
```
## 向 IAM 主体授予直接使用加密表的权限
当您通过第三方或直接访问方法处理加密表时，必须向您使用的角色授予对 KMS 密钥的访问权限。以下示例说明如何通过 IAM 策略或 KMS 密钥策略授予访问权限。
------
#### [ IAM policy ]
将此内联策略附加到您的 IAM 角色，以支持访问 KMS 密钥。要使用此策略，请将*输入占位符值*替换为您自己的 KMS 密钥 arn。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowKMSKeyUsage",
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}
]
}
```
------
------
#### [ KMS key policy ]
将此内联策略附加到 KMS 密钥，以让指定的 AWS KMS 角色使用该密钥。要使用此策略，请将*输入占位符值*替换为您的 IAM 角色。
```
{
"Sid": "Allow use of the key",
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam:::role/"
]
},
"Action": [
"kms:Decrypt",
"kms:GenerateDataKey",
],
"Resource": "*"
}
```
------
## 向 S3 元数据服务主体授予使用您的 KMS 密钥的权限
要支持 Amazon S3 更新通过 SSE-KMS 加密的元数据表并对这些元数据表执行维护，您可以使用以下示例密钥策略。在此策略中，您可以让 `metadata.s3.amazonaws.com` 和 `maintenance.s3tables.amazonaws.com` 服务主体使用特定密钥对特定表存储桶中的表进行加密和解密。要使用此策略，请将*用户输入占位符*替换为您自己的信息：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "EnableKeyUsage",
"Effect": "Allow",
"Principal": {
"Service": [
"maintenance.s3tables.amazonaws.com",
"metadata.s3.amazonaws.com"
]
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
"Condition": {
"StringLike": {
"kms:EncryptionContext:aws:s3:arn":"/*"
}
}
}
]
}
```
------
# 在表存储桶中指定具有 AWS KMS 密钥的服务器端加密（SSE-KMS）
默认情况下，所有 Amazon S3 表存储桶都配置了加密，所有在表存储桶中创建的新表都会自动静态加密。具有 Amazon S3 托管式密钥的服务器端加密（SSE-S3）是每个表存储桶的默认加密配置。如果您要指定不同的加密类型，可以使用具有 AWS Key Management Service（AWS KMS）密钥的服务器端加密（SSE-KMS）。
可以在 `CreateTableBucket` 或 `CreateTable` 请求中指定 SSE-KMS 加密，也可以在 `PutTableBucketEncryption` 请求中设置表存储桶中的默认加密配置。
**重要**
要支持对通过 SSE-KMS 加密的表和表存储桶进行自动维护，您必须向 maintenance.s3tables.amazonaws.com 服务主体授予使用 KMS 密钥的权限。有关更多信息，请参阅 [S3 表类数据存储服务 SSE-KMS 加密的权限要求](s3-tables-kms-permissions.md)。
## 为表存储桶指定加密
在创建新的表存储桶时，您可以指定 SSE-KMS 作为默认加密类型，有关示例，请参阅[创建表存储桶](s3-tables-buckets-create.md)。创建表存储桶后，您可以使用 REST API 操作、AWS SDK 和 AWS Command Line Interface（AWS CLI）来指定将 SSE-KMS 用作默认加密设置。
**注意**
当您将 SSE-KMS 指定为默认加密类型时，用于加密的密钥必须支持访问 S3 表类数据存储服务维护服务主体。如果维护服务主体没有访问权限，您将无法在该表存储桶中创建表。有关更多信息，请参阅 [向 S3 表类数据存储服务维护服务主体授予对 KMS 密钥的权限](s3-tables-kms-permissions.md#tables-kms-maintenance-permissions)。
### 使用 AWS CLI
要使用以下示例 AWS CLI 命令，请将*用户输入占位符*替换为您自己的信息。
```
aws s3tables put-table-bucket-encryption \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket; \
--encryption-configuration '{
"sseAlgorithm": "aws:kms",
"kmsKeyArn": "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}' \
--region us-east-1
```
您可以使用 [DeleteTableBucketEncryption](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTableBucketEncryption.html) API 操作移除表存储桶的默认加密设置。移除加密设置后，在表存储桶中创建的新表将使用默认的 SSE-S3 加密。
## 为表指定加密
在使用查询引擎、REST API 操作、AWS SDK 和 AWS Command Line Interface（AWS CLI）创建新表时，可以对该表应用 SSE-KMS 加密。您在创建表时指定的加密设置优先于表存储桶的默认加密设置。
**注意**
对表使用 SSE-KMS 加密时，用于加密的密钥必须支持 S3 表类数据存储服务维护服务主体访问该表。如果维护服务主体没有访问权限，您将无法创建表。有关更多信息，请参阅 [向 S3 表类数据存储服务维护服务主体授予对 KMS 密钥的权限](s3-tables-kms-permissions.md#tables-kms-maintenance-permissions)。
****所需的权限****
创建加密表需要以下权限
+ `s3tables:CreateTable`
+ `s3tables:PutTableEncryption`
## 使用 AWS CLI
以下 AWS CLI 示例使用基本架构创建一个新表，并使用客户自主管理型 AWS KMS 密钥对其进行加密。要使用该命令，请将*用户输入占位符* 替换为您自己的信息。
```
aws s3tables create-table \
--table-bucket-arn "arn:aws:s3tables:Region:ownerAccountId:bucket/amzn-s3-demo-table-bucket" \
--namespace "mydataset" \
--name "orders" \
--format "ICEBERG" \
--encryption-configuration '{
"sseAlgorithm": "aws:kms",
"kmsKeyArn": "arn:aws:kms:Region:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
}' \
--metadata '{
"iceberg": {
"schema": {
"fields": [
{
"name": "order_id",
"type": "string",
"required": true
},
{
"name": "order_date",
"type": "timestamp",
"required": true
},
{
"name": "total_amount",
"type": "decimal(10,2)",
"required": true
}
]
}
}
}'
```
数据保护指在数据传输（数据发往和离开 Amazon S3 时）和处于静态（数据存储在 Amazon S3 数据中心的磁盘上时）期间保护数据。S3 表类数据存储服务始终通过 HTTPS 使用传输层安全性（1.2 及更高版本）来保护传输中数据。为保护 S3 表存储桶中的静态数据，您具有以下选项：
**具有 Amazon S3 托管密钥的服务器端加密（SSE-S3）**
默认情况下，所有 Amazon S3 表存储桶都配置了加密。服务器端加密的默认选项是使用 Amazon S3 托管式密钥（SSE-S3）。这种加密对您来说是免费的，并且适用于 S3 表存储桶中的所有表，除非您指定了另一种加密形式。每个对象都使用唯一的密钥来进行加密。作为额外的保护措施，SSE-S3 使用定期轮换的根密钥加密密钥本身。SSE-S3 使用可用的最强数据块密码之一 [即 256 位高级加密标准（AES-256）] 来加密您的数据。
**具有 AWS KMS 密钥的服务器端加密（SSE-KMS）**
可以选择将表存储桶或表配置为使用具有 AWS Key Management Service（AWS KMS）密钥的服务器端加密（SSE-KMS）。AWS KMS 中的安全控制可帮助您满足与加密相关的合规性要求。SSE-KMS 可让您通过执行以下操作来更好地控制加密密钥：
+ 创建、查看、编辑、监控、启用或禁用、轮换以及安排删除 KMS 密钥。
+ 定义控制如何使用和谁可以使用 KMS 密钥的策略。
+ 在 AWS CloudTrail 中跟踪密钥使用情况，以验证 KMS 密钥是否得到正确使用。
S3 表类数据存储服务支持在 SSE-KMS 中使用客户自主管理型密钥来加密表。不支持 AWS 托管式密钥。有关对 S3 表和表存储桶使用 SSE-KMS 的更多信息，请参阅[在表存储桶中使用具有 AWS KMS 密钥的服务器端加密（SSE-KMS）](s3-tables-kms-encryption.md)。
# S3 表类数据存储服务的访问管理
在 S3 表类数据存储服务中，资源包括表存储桶及其包含的表。默认情况下，创建资源的 AWS 账户的根用户（资源拥有者）和该账户中具有必要权限的 AWS Identity and Access Management（IAM）用户可以访问他们创建的资源。资源拥有者指定还有谁可以访问该资源以及支持他们对该资源执行哪些操作。Amazon S3 具有各种访问管理工具，您可以使用这些工具向其他人授予对您的 S3 资源的访问权限。如果已将表与 AWS Amazon SageMaker 智能湖仓集成，则还可以使用 Lake Formation 管理对表和命名空间的精细访问。以下主题概述了 S3 表类数据存储服务的资源、IAM 操作和条件键。它们还提供了 S3 表类数据存储服务的基于资源和基于身份的策略的示例。
**Topics**
+ [资源](#s3-tables-resources)
+ [S3 表类数据存储服务的操作](#s3-tables-actions)
+ [S3 表类数据存储服务的条件键](#s3-tables-conditionkeys)
+ [S3 表类数据存储服务的基于 IAM 身份的策略](s3-tables-identity-based-policies.md)
+ [S3 表类数据存储服务的基于资源的策略](s3-tables-resource-based-policies.md)
+ [适用于 S3 表类数据存储服务的 AWS 托管式策略](s3-tables-security-iam-awsmanpol.md)
+ [使用 SQL 语义授予访问权限](s3-tables-sql.md)
+ [使用 Lake Formation 管理对表或数据库的访问权限](grant-permissions-tables.md)
## 资源
S3 表类数据存储服务资源包括表存储桶及其包含的表。
+ 表存储桶：表存储桶专为表而设计，与通用 S3 存储桶中自行管理的表相比，可提供更高的每秒事务数（TPS）和更好的查询吞吐量。表存储桶具有与 Amazon S3 通用存储桶相同的耐久性、可用性、可扩展性和性能特征。
+ 表 - 表存储桶中的表以 Apache Iceberg 格式存储。您可以在支持 Iceberg 的查询引擎中使用标准 SQL 查询这些表。
表和表存储桶的 Amazon 资源名称（ARN）包含 `s3tables` 命名空间、AWS 区域、AWS 账户 ID 和存储桶名称。要访问表和表存储桶并对其执行操作，必须使用以下 ARN 格式：
+ 表格 ARN 格式：
`arn:aws:s3tables:us-west-2:111122223333:bucket/amzn-s3-demo-bucket/table/demo-tableID`
## S3 表类数据存储服务的操作
在基于身份的策略或基于资源的策略中，您可以定义对于特定 IAM 主体支持或拒绝哪些 S3 表类数据存储服务操作。表操作对应于存储桶和表级 API 操作。所有操作都是唯一 IAM 命名空间的一部分：`s3tables`。
当您在策略中使用一项操作时，通常会允许或拒绝使用具有相同名称的 API 操作。但在某些情况下，单个操作可控制对多个 API 操作的访问。例如，`s3tables:GetTableData` 操作包括对于 `GetObject`、`ListParts` 和 `ListMultiparts` API 操作的权限。
以下是表存储桶支持的操作。您可以在 IAM 策略或资源策略的 `Action` 元素中指定以下操作。
| Action | 说明 | 访问级别 | 跨账户访问 |
| --- | --- | --- | --- |
| s3tables:CreateTableBucket | 授予创建表存储桶的权限 | Write | 否 |
| s3tables:GetTableBucket | 授予检索表存储桶 ARN、表存储桶名称和创建日期的权限。 | Write | 是 |
| s3tables:ListTableBuckets | 授予列出此账户中所有表存储桶的权限 | Read | 否 |
| s3tables:CreateNamespace | 授予在表存储桶中创建命名空间的权限 | Write | 是 |
| s3tables:GetNamespace | 授予检索命名空间详细信息的权限 | Read | 是 |
| s3tables:ListNamespaces | 授予列出表存储桶上所有命名空间的权限。 | Read | 是 |
| s3tables:DeleteNamespace | 授予删除表存储桶中命名空间的权限 | Write | 是 |
| s3tables:DeleteTableBucket | 授予删除存储桶的权限 | Write | 是 |
| s3tables:PutTableBucketPolicy | 授予添加或替换存储桶策略的权限 | Permissions Management | 否 |
| s3tables:GetTableBucketPolicy | 授予检索存储桶策略的权限 | Read | 否 |
| s3tables:DeleteTableBucketPolicy | 授予删除存储桶策略的权限 | Permissions Management | 否 |
| s3tables:GetTableBucketMaintenanceConfiguration | 授予检索表存储桶的维护配置的权限 | Read | 是 |
| s3tables:PutTableBucketMaintenanceConfiguration | 授予添加或替换表存储桶的维护配置的权限 | Write | 是 |
| s3tables:PutTableBucketEncryption | 授予添加或替换表存储桶的加密配置的权限 | Write | 否 |
| s3tables:GetTableBucketEncryption | 授予检索表存储桶的加密配置的权限 | Read | 否 |
| s3tables:DeleteTableBucketEncryption | 授予删除表存储桶的加密配置的权限 | Write | 否 |
表支持以下操作：
| Action | 说明 | 访问级别 | 跨账户访问 |
| --- | --- | --- | --- |
| s3tables:GetTableMaintenanceConfiguration | 授予检索表的维护配置的权限 | Read | 是 |
| s3tables:PutTableMaintenanceConfiguration | 授予添加或替换表的维护配置的权限 | Write | 是 |
| s3tables:PutTablePolicy | 授予添加或替换表策略的权限 | Permissions Management | 否 |
| s3tables:GetTablePolicy | 授予检索表策略的权限 | Read | 否 |
| s3tables:DeleteTablePolicy | 授予删除表策略的权限 | Permissions management | 否 |
| s3tables:CreateTable | 授予在表存储桶中创建表的权限 | Write | 是 |
| s3tables:GetTable | 授予检索表信息的权限 | Read | 是 |
| s3tables:GetTableMetadataLocation | 授予检索表根指针（元数据文件）的权限 | Read | 是 |
| s3tables:ListTables | 授予列出表存储桶中的所有表的权限 | Read | 是 |
| s3tables:RenameTable | 授予更改表名称的权限 | Write | 是 |
| s3tables:UpdateTableMetadataLocation | 授予更新表根指针（元数据文件）的权限 | Write | 是 |
| s3tables:GetTableData | 授予读取存储在表存储桶中的表元数据和数据对象的权限 | Read | 是 |
| s3tables:PutTableData | 授予写入存储在表存储桶中的表元数据和数据对象的权限 | Write | 是 |
| s3tables:GetTableEncryption | 授予检索表的加密设置的权限 | Write | 否 |
| s3tables:PutTableEncryption | 授予将加密添加到表的权限 | Write | 否 |
| s3tables:DeleteTable | 授予从表存储桶中删除表的权限 | Write | 是 |
为了执行表级读取和写入操作，S3 表类数据存储服务支持如 `GetObject` 和 `PutObject` 等 Amazon S3 API 操作。下表提供了对象级操作的列表。在授予对表的读写权限时，您可以使用以下操作。
| Action | S3 对象 API |
| --- | --- |
| s3tables:GetTableData | GetObject, ListParts, HeadObject |
| s3tables:PutTableData | PutObject, CreateMultipartUpload, CompleteMultipartUpload, UploadPart, AbortMultipartUpload |
例如，如果用户拥有 `GetTableData` 权限，则他们可以读取与该表关联的所有文件，例如其元数据文件、清单、清单列表文件和 parquet 数据文件。
## S3 表类数据存储服务的条件键
S3 表类数据存储服务支持 [AWS 全局条件上下文条件键](https://docs.aws.amazon.com//IAM/latest/UserGuide/reference_policies_condition-keys.html)。
此外，S3 表类数据存储服务定义以下可以在访问策略中使用的条件键。
| 条件键 | 说明 | 类型 |
| --- | --- | --- |
| s3tables:tableName | 按表存储桶中表的名称筛选访问权限。您可以使用 `s3tables:tableName` 条件键来编写 IAM 或表存储桶策略，以限制用户或应用程序仅可访问符合此名称条件的表。 请务必注意，如果您使用 `s3tables:tableName` 条件键来控制访问权限，则表名称的更改可能会影响这些策略。 示例值："s3tables:tableName":"department\$1" | String |
| s3tables:namespace | 按在表存储桶中创建的命名空间筛选访问权限。 您可以使用 `s3tables:namespace` 条件键编写 IAM、表或表存储桶策略，以限制用户或应用程序对作为特定命名空间一部分的表的访问权限。*示例值：*`"s3tables:namespace":"hr" ` 请务必注意，如果您使用 `s3tables:namespace` 条件键来控制访问权限，那么命名空间的更改可能会影响这些策略。 | String |
| s3tables:SSEAlgorithm | 按用于加密表的服务器端加密算法筛选访问权限。 您可以使用 `s3tables:SSEAlgorithm` 条件键编写 IAM、表或表存储桶策略，以限制用户或应用程序只能访问使用特定加密类型加密的表。*示例值：*`"s3tables:SSEAlgorithm":"aws:kms" ` 请务必注意，如果您使用 `s3tables:SSEAlgorithm` 条件键来控制访问权限，那么加密的更改可能会影响这些策略。 | String |
| s3tables:KMSKeyArn | 按用于加密表的密钥的 AWS KMS 密钥 ARN 筛选访问权限 您可以使用 `s3tables:KMSKeyArn` 条件键来编写 IAM、表或表存储桶策略，以限制用户或应用程序只能访问使用特定 KMS 密钥加密的表。 请务必注意，如果您使用 `s3tables:KMSKeyArn` 条件键来控制访问权限，则更改 KMS 密钥可能会影响这些策略。 | ARN |
# S3 表类数据存储服务的基于 IAM 身份的策略
默认情况下，用户和角色不拥有创建或修改表和表存储桶的权限。他们也无法通过 s3 控制台、AWS Command Line Interface（AWS CLI）或 Amazon S3 REST API 执行任务。要创建和访问表存储桶和表，AWS Identity and Access Management（IAM）管理员必须向 IAM 角色或用户授予必要的权限。要了解如何使用这些示例 JSON 策略文档创建基于 IAM 身份的策略，请参阅 *IAM 用户指南*中的 [创建 IAM 策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html)。
以下主题包括基于 IAM 身份的策略示例。要使用以下示例策略，请将*用户输入占位符* 替换为您自己的信息。
**Topics**
+ [示例 1：支持创建和使用表存储桶的访问权限](#example-1-s3-tables-identity-based-policies)
+ [示例 2：支持在表存储桶中创建和使用表的访问权限](#example-2-s3-tables-identity-based-policies)
## 示例 1：支持创建和使用表存储桶的访问权限
**.**
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowBucketActions",
"Effect": "Allow",
"Action": [
"s3tables:CreateTableBucket",
"s3tables:PutTableBucketPolicy",
"s3tables:GetTableBucketPolicy",
"s3tables:ListTableBuckets",
"s3tables:GetTableBucket"
],
"Resource": "arn:aws:s3tables:us-east-1:111122223333:bucket/*"
}
]
}
```
------
## 示例 2：支持在表存储桶中创建和使用表的访问权限
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowBucketActions",
"Effect": "Allow",
"Action": [
"s3tables:GetTableBucket",
"s3tables:ListTables",
"s3tables:CreateTable",
"s3tables:PutTableData",
"s3tables:GetTableData",
"s3tables:GetTable",
"s3tables:GetTableMetadataLocation",
"s3tables:UpdateTableMetadataLocation",
"s3tables:GetNamespace",
"s3tables:CreateNamespace",
"s3tables:ListNamespaces"
],
"Resource": [
"arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket",
"arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket/table/*"
]
}
]
}
```
------
# S3 表类数据存储服务的基于资源的策略
S3 表类数据存储服务提供了基于资源的策略，用于管理对表存储桶和表的访问权限：表存储桶策略和表策略。可以使用表存储桶策略在表存储桶、命名空间或表级授予 API 访问权限。附加到表存储桶的权限可以应用于存储桶中的所有表，也可以应用于存储桶中的特定表，具体取决于策略定义。可以使用表策略在表级授予权限。
当 S3 表类数据存储服务收到请求时，它首先验证请求者是否拥有必要的权限。它对所有相关访问策略、用户策略和基于资源的策略（IAM 用户策略、IAM 角色策略、表存储桶策略和表策略）进行评估，以决定是否对该请求进行授权。例如，如果表存储桶策略授予用户对存储桶中的表执行所有操作（包括 `DeleteTable`）的权限，但单个表的表策略拒绝所有用户执行 `DeleteTable` 操作，则该用户无法删除该表。
以下主题包括表和表存储桶策略的示例。要使用这些策略，请将*用户输入占位符* 替换为您自己的信息。
**注意**
每个授予修改表的权限的策略都应包括供 `GetTableMetadataLocation` 访问表根文件的权限。有关更多信息，请参阅 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableMetadataLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableMetadataLocation.html)。
每次对表执行写入或删除活动时，都要在访问策略中包含对 `UpdateTableMetadataLocation` 的权限。
我们建议使用表存储桶策略来管理对存储桶级操作的访问权限，并使用表策略来管理对表级操作的访问权限。如果您想在多个表中定义相同的权限集，那么我们建议使用表存储桶策略。
**Topics**
+ [示例 1：表存储桶策略支持对账户中的存储桶执行 `PutBucketMaintenanceConfiguration` 的访问权限](#table-bucket-policy-1)
+ [示例 2：支持对存储在 `hr` 命名空间中的表进行读取（SELECT）访问的表存储桶策略](#table-bucket-policy-2)
+ [示例 3：支持用户删除表的表策略](#table-bucket-policy-3)
## 示例 1：表存储桶策略支持对账户中的存储桶执行 `PutBucketMaintenanceConfiguration` 的访问权限
以下示例表存储桶策略通过支持访问 `PutBucketMaintenanceConfiguration`，可让 IAM `data steward` 删除账户中所有存储桶的未引用对象。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/datasteward"
},
"Action": [
"s3tables:PutTableBucketMaintenanceConfiguration"
],
"Resource": "arn:aws:s3tables:us-east-1:111122223333:bucket/*"
}
]
}
```
------
## 示例 2：支持对存储在 `hr` 命名空间中的表进行读取（SELECT）访问的表存储桶策略
以下示例表存储桶策略支持 Jane（来自 AWS 账户 ID `123456789012` 的用户）访问存储在表存储桶的 `hr` 命名空间中的表。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:user/Jane"
},
"Action": [
"s3tables:GetTableData",
"s3tables:GetTableMetadataLocation"
],
"Resource": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket/table/*",
"Condition": {
"StringLike": {
"s3tables:namespace": "hr"
}
}
}
]
}
```
------
## 示例 3：支持用户删除表的表策略
以下示例表策略支持 IAM 角色 `data steward` 删除表。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "DeleteTable",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/datasteward"
},
"Action": [
"s3tables:DeleteTable",
"s3tables:UpdateTableMetadataLocation",
"s3tables:PutTableData",
"s3tables:GetTableMetadataLocation"
],
"Resource": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket/table/tableUUID"
}
]
}
```
------
# 适用于 S3 表类数据存储服务的 AWS 托管式策略
AWS 托管式策略是由 AWS 创建和管理的独立策略。AWS 托管式策略旨在为许多常见使用案例提供权限，以便您可以开始为用户、组和角色分配权限。
请记住，AWS 托管式策略可能不会为您的特定使用案例授予最低权限，因为它们可供所有 AWS 客户使用。我们建议通过定义特定于使用案例的[客户管理型策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#customer-managed-policies)来进一步减少权限。
您无法更改 AWS 托管式策略中定义的权限。如果 AWS 更新在 AWS 托管式策略中定义的权限，则更新会影响该策略所附加到的所有主体身份（用户、组和角色）。当新的 AWS 服务 启动或新的 API 操作可用于现有服务时，AWS 最有可能更新 AWS 托管式策略。
有关更多信息，请参阅《*IAM 用户指南*》中的 [AWS 托管式策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)。
## AWS 托管式策略：AmazonS3TablesFullAccess
您可以将 `AmazonS3TablesFullAccess` 策略附加到 IAM 身份。此策略授予支持完全访问 Amazon S3 表类数据存储服务的权限。有关此策略的更多信息，请参阅“[https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonS3TablesFullAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonS3TablesFullAccess.html)”。
## AWS 托管式策略：AmazonS3TablesReadOnlyAccess
您可以将 `AmazonS3TablesReadOnlyAccess` 策略附加到 IAM 身份。此策略授予支持对 Amazon S3 表类数据存储服务进行只读访问的权限。有关此策略的更多信息，请参阅“[https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonS3TablesReadOnlyAccess.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonS3TablesReadOnlyAccess.html)”。
## AWS 托管式策略：AmazonS3TablesLakeFormationServiceRole
您可以将 `AmazonS3TablesLakeFormationServiceRole` 策略附加到 IAM 身份。此策略授予支持 AWS Lake Formation 服务角色访问 S3 表类数据存储服务的权限。AWS KMS 权限用于支持 Lake Formation 访问加密的表。有关此策略的更多信息，请参阅“[https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonS3TablesLakeFormationServiceRole.html](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/AmazonS3TablesLakeFormationServiceRole.html)”。
## Amazon S3 表类数据存储服务对 AWS 托管式策略的更新
查看有关自 Amazon S3 表类数据存储服务开始跟踪更改以来，对 S3 表类数据存储服务的 AWS 托管式策略的更新的详细信息。
| 更改 | 描述 | 日期 |
| --- | --- | --- |
| Amazon S3 表类数据存储服务更新了 `AmazonS3TablesFullAccess`。 | S3 表类数据存储服务更新了名为 `AmazonS3TablesFullAccess` 的 AWS 托管策略。此更新将授予向 S3 表类数据存储服务复制服务传递角色的权限。 | 2025 年 12 月 2 日 |
| Amazon S3 表类数据存储服务添加了 `AmazonS3TablesLakeFormationServiceRole`。 | S3 表类数据存储服务添加了一个名为 `AmazonS3TablesLakeFormationServiceRole` 的新 AWS 托管式策略。此策略授予支持 Lake Formation 服务角色访问 S3 表类数据存储服务的权限。 | 2025 年 5 月 19 日 |
| Amazon S3 表类数据存储服务添加了 `AmazonS3TablesFullAccess`。 | S3 表类数据存储服务添加了一个名为 `AmazonS3TablesFullAccess` 的新 AWS 托管式策略。此策略授予支持完全访问 Amazon S3 表类数据存储服务的权限。 | 2024 年 12 月 3 日 |
| Amazon S3 表类数据存储服务添加了 `AmazonS3TablesReadOnlyAccess`。 | S3 表类数据存储服务添加了一个名为 `AmazonS3TablesReadOnlyAccess` 的新 AWS 托管式策略。此策略授予支持对 Amazon S3 表类数据存储服务进行只读访问的权限。 | 2024 年 12 月 3 日 |
| Amazon S3 表类数据存储服务开始了跟踪更改。 | Amazon S3 表类数据存储服务为其 AWS 托管式策略开始了跟踪更改。 | 2024 年 12 月 3 日 |
# 使用 SQL 语义授予访问权限
可以通过在表和表存储桶策略中使用 SQL 语义来授予对表的权限。可以使用的 SQL 语义的示例为 `CREATE`、`INSERT`、`DELETE`、`UPDATE` 和 `ALTER`。下表提供了与 SQL 语义关联的 API 操作的列表，您可以使用这些操作向用户授予权限。
S3 表类数据存储服务部分支持使用 SQL 语义的权限。例如，`CreateTable` API 仅在表存储桶中创建一个空表。您需要额外的权限（例如 `UpdateTableMetadata`、`PutTableData` 和 `GetTableMetadataLocation`），才能设置表架构。这些额外权限还意味着您还授予用户在表中插入行的权限。如果您希望纯粹基于 SQL 语义来管理访问权限，那么我们建议您使用 [AWS Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/what-is-lake-formation.html) 或任何与 S3 表类数据存储服务集成的第三方解决方案。
| 表级活动 | IAM 操作 |
| --- | --- |
| SELECT | s3tables:GetTableData, s3tables:GetTableMetadataLocation |
| CREATE | s3tables:CreateTable, s3tables:UpdateTableMetadataLocation, s3tables:PutTableData, s3tables:GetTableMetadataLocation, |
| INSERT | s3tables:UpdateTableMetadataLocation, s3tables:PutTableData, s3tables:GetTableMetadataLocation |
| UPDATE | s3tables:UpdateTableMetadataLocation, s3tables:PutTableData, s3tables:GetTableMetadataLocation |
| ALTER,RENAME | s3tables:UpdateTableMetadataLocation, s3tables:PutTableData, s3tables:GetTableMetadataLocation, s3tables:RenameTable |
| DELETE,DROP | s3tables:DeleteTable, s3tables:UpdateTableMetadataLocation, s3tables:PutTableData, s3tables:GetTableMetadataLocation |
**注意**
从表存储桶中删除表需要 `s3tables:DeleteTable` 权限。此权限可让您永久移除表及其所有关联数据和元数据。请谨慎使用此权限，因为删除操作无法撤消。
# 使用 Lake Formation 管理对表或数据库的访问权限
在表存储桶与 AWS 分析服务集成后，Lake Formation 将管理对表的访问，并要求向每个 IAM 主体（用户或角色）授权对分析服务执行操作。Lake Formation 使用其自己的权限模型（Lake Formation 权限），该模型可以对数据目录资源进行精细的访问控制。
有关更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Overview of Lake Formation permissions](https://docs.aws.amazon.com//lake-formation/latest/dg/lf-permissions-overview.html)。
AWS Lake Formation 中有两种主要类型的权限：
1. 元数据访问权限控制着在数据目录中创建、读取、更新和删除元数据数据库和表的能力。
1. 基础数据访问权限控制着对数据目录资源指向的基础 Amazon S3 位置读取和写入数据的能力。
Lake Formation 结合使用自己的权限模型和 IAM 权限模型，来控制对数据目录资源和基础数据的访问权限：
+ 为了使访问数据目录资源或基础数据的请求取得成功，请求必须通过由 IAM 和 Lake Formation 进行的权限检查。
+ IAM 权限控制对 Lake Formation 和 AWS Glue API 以及资源的访问权限，而 Lake Formation 权限控制对数据目录资源、Amazon S3 位置和基础数据的访问权限。
Lake Formation 权限仅适用于授予这些权限的区域，并且主体必须由数据湖管理员或其它具有必要权限的主体授权，才能获得 Lake Formation 权限。
**注意**
如果您是执行表存储桶集成的用户，则您已经拥有对表的 Lake Formation 权限。如果您是唯一将访问表的主体，则可以跳过此步骤。您只需向其它 IAM 主体授予对表的 Lake Formation 权限即可。这可让其它主体在运行查询时访问该表。有关更多信息，请参阅 [授予对表或数据库的 Lake Formation 权限](#grant-lf-table)。
## 授予对表或数据库的 Lake Formation 权限
您可以通过 Lake Formation 控制台或 AWS CLI，向主体授予对表存储桶中表或数据库的 Lake Formation 权限。
**注意**
当您将对数据目录资源的 Lake Formation 权限授予外部账户或直接授予其他账户中的 IAM 主体时，Lake Formation 会使用 AWS Resource Access Manager (AWS RAM) 服务共享该资源。如果被授权者账户与授予者账户在同一个组织中，则被授权者立即可以使用共享资源。如果被授权者账户不在同一个组织中，则 AWS RAM 会向被授权者账户发送邀请，以便其接受或拒绝资源授权。然后，要使共享资源可用，被授权者账户中的数据湖管理员必须使用 AWS RAM 控制台或 AWS CLI 接受邀请。有关跨账户数据共享的更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Cross-account data sharing in Lake Formation](https://docs.aws.amazon.com/lake-formation/latest/dg/cross-account-permissions.html)。
------
#### [ Console ]
1. 打开 AWS Lake Formation 控制台（网址为 [https://console.aws.amazon.com/lakeformation/](https://console.aws.amazon.com/lakeformation/)），并以数据湖管理员身份登录。有关如何创建数据湖管理员的更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Create a data lake administrator](https://docs.aws.amazon.com/lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)。
1. 在导航窗格中，选择**数据权限**，然后选择**授予**。
1. 在**授予权限**页面的**主体**下，执行以下操作之一：
+ 对于 Amazon Athena 或 Amazon Redshift，选择 **IAM 用户和角色**，然后选择您用于查询的 IAM 主体。
+ 对于 Amazon Data Firehose，选择 **IAM 用户和角色**，然后选择您创建的服务角色以流式传输到表中。
+ 对于 Quick，选择 **SAML 用户和组**，然后输入 Quick 管理员用户的 Amazon 资源名称（ARN）。
+ 要访问 AWS Glue Iceberg REST 端点，请选择 **IAM 用户和角色**，然后选择您为客户端创建的 IAM 角色。有关更多信息，请参阅 [为客户端创建 IAM 角色](s3-tables-integrating-glue-endpoint.md#glue-endpoint-create-iam-role)。
1. 在 **LF 标签或目录资源**下，选择**命名 Data Catalog 资源**。
1. 对于**目录**，请选择您在集成表存储桶时创建的子目录，例如 `account-id:s3tablescatalog/amzn-s3-demo-bucket`。
1. 对于**数据库**，选择您创建的 S3 表存储桶命名空间。
1. （可选）对于**表**，请选择您在表存储桶中创建的 S3 表。
**注意**
如果您要在 Athena 查询编辑器中创建新表，请不要选择表。
1. 请执行以下操作之一：
+ 如果您在之前的步骤中指定了表，请为**表权限**选择 **Super**。
+ 如果您未在之前的步骤中指定表，请转到**数据库权限**。对于跨账户数据共享，您不能选择 **Super** 来向另一个主体授予对数据库的所有权限。而是应选择更精细的权限，例如**描述**。
1. 选择**授权**。
------
#### [ CLI ]
1. 务必要以数据湖管理员身份运行以下 AWS CLI 命令。有关更多信息，请参阅《AWS Lake Formation Developer Guide》**中的 [Create a data lake administrator](https://docs.aws.amazon.com//lake-formation/latest/dg/initial-lf-config.html#create-data-lake-admin)。
1. 运行以下命令，向 IAM 主体授予对 S3 表存储桶中表的 Lake Formation 权限以访问该表。要使用此示例，请将 *`user input placeholders`* 替换为您自己的信息。
```
aws lakeformation grant-permissions \
--region us-east-1 \
--cli-input-json \
'{
"Principal": {
"DataLakePrincipalIdentifier": "user or role ARN, for example, arn:aws:iam::account-id:role/example-role"
},
"Resource": {
"Table": {
"CatalogId": "account-id:s3tablescatalog/amzn-s3-demo-bucket",
"DatabaseName": "S3 table bucket namespace, for example, test_namespace",
"Name": "S3 table bucket table name, for example test_table"
}
},
"Permissions": [
"ALL"
]
}'
```
------
# S3 表类数据存储服务的 VPC 连接
S3 表类数据存储服务中的所有表均采用 Apache Iceberg 格式，并由两种类型的 S3 对象组成。这两种类型的对象是存储数据的数据文件，以及跟踪有关不同时间点的数据文件信息的元数据文件。所有表存储桶、命名空间和表操作（例如 `CreateNamespace`、`CreateTable` 等）均通过 S3 表类数据存储服务端点 (`s3tables.region.amazonaws.com`) 路由，而读取或写入数据和元数据文件的所有对象级操作都将继续通过 S3 服务端点 (`s3.region.amazonaws.com`) 路由。
为访问 S3 表类数据存储服务，Amazon S3 通过使用 AWS PrivateLink 支持两种类型的 VPC 端点：网关端点和接口端点。网关端点是您在路由表中指定的网关，用于通过 AWS 网络从 VPC 访问 S3。接口端点通过私有 IP 地址，使用 VPC 对等连接或 AWS Transit Gateway 将请求从您的 VPC 内、本地或其它 AWS 区域中的 VPC 路由到 Amazon S3，从而扩展网关端点的功能。
要从 VPC 访问 S3 表类数据存储服务，我们建议创建两个 VPC 端点（一个用于 S3，另一个用于 S3 表类数据存储服务）。可以创建网关或接口端点来将文件（对象）级操作路由到 S3，并创建接口端点来将存储桶和表级操作路由到 S3 表。可以使用 S3 为文件级请求创建和使用 VPC 端点。有关更多信息，请参阅《AWS PrivateLink 用户指南》**中的 [Gateway endpoints](https://docs.aws.amazon.com/vpc/latest/privatelink/gateway-endpoints.html)。
要了解有关使用 AWS PrivateLink 为 S3 表类数据存储服务创建和使用端点的更多信息，请参阅以下主题。要创建 VPC 接口端点，请参阅《AWS PrivateLink Guide》**中的 [Create a VPC endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws)。
**Topics**
+ [为 S3 表类数据存储服务创建 VPC 端点](#s3-tables-endpoints)
+ [使用 AWS CLI 通过端点访问表存储桶和表](#s3-tables-endpoints-cli-sdks)
+ [使用查询引擎时配置 VPC 网络](#s3-tables-query-engine)
+ [使用双堆栈端点访问表和表存储桶](#s3-tables-dual-stack-endpoints)
+ [在 VPC 网络中限制对 S3 表类数据存储服务的访问权限](#s3-tables-VPC-policy)
## 为 S3 表类数据存储服务创建 VPC 端点
当您创建 VPC 端点时，S3 表类数据存储服务会生成两种类型的特定于端点的 DNS 名称：区域和可用区。
+ 区域 DNS 名称采用以下格式：`VPCendpointID.s3tables.AWSregion.vpce.amazonaws.com`。例如，对于 VPC 端点 ID `vpce-1a2b3c4d`，生成的 DNS 名称将类似于 `vpce-1a2b3c4d-5e6f.s3tables.us-east-1.vpce.amazonaws.com`
+ 可用区 DNS 名称采用以下格式：`VPCendpointID-AvailabilityZone.s3tables.AWSregion.vpce.amazonaws.com`。例如，对于 VPC 端点 ID `vpce-1a2b3c4d-5e6f.`，生成的 DNS 名称将类似于 `vpce-1a2b3c4d-5e6f-us-east-1a.s3tables.us-east-1.vpce.amazonaws.com`
可用区 DNS 名称包括您的可用区。如果您的架构隔离了可用区，则可以使用可用区 DNS 名称。可以从 S3 公有 DNS 域解析端点特定的 S3 DNS 名称。
还可以使用私有 DNS 选项来简化通过 VPC 端点路由 S3 流量的过程，并协助您充分利用应用程序可用的最低成本网络路径。私有 DNS 将 S3 表类数据存储服务的公有端点（例如 `s3tables.region.amazonaws.com`）映射到 VPC 中的私有 IP。可以使用私有 DNS 选项来路由区域 S3 流量，而无需更新 S3 客户端以使用接口端点的端点特定的 DNS 名称。
## 使用 AWS CLI 通过端点访问表存储桶和表
可以使用 AWS Command Line Interface（AWS CLI）通过接口端点访问表存储桶和表。使用 AWS CLI，`aws s3` 命令通过 Amazon S3 端点路由流量。`aws s3tables` AWS CLI 命令使用 Amazon S3 表类数据存储服务端点。
`s3tables` VPC 端点的示例为 `vpce-0123456afghjipljw-nmopsqea.s3tables.region.vpce.amazonaws.com`
`s3tables` VPC 端点不包含存储桶名称。可以使用 `aws s3tables` AWS CLI 命令访问 `s3tables` VPC 端点。
`s3` VPC 端点的示例为 `amzn-s3-demo-bucket.vpce-0123456afghjipljw-nmopsqea.s3.region.vpce.amazonaws.com`
可以使用 `aws s3` AWS CLI 命令访问 `s3` VPC 端点。
### 使用 AWS CLI
要使用 AWS CLI 通过接口端点访问表存储桶和表，请使用 `-region` 和 `--endpoint-url` 参数。要执行表存储桶和表级操作，请使用 S3 表类数据存储服务端点 URL。要执行对象级操作，请使用 Amazon S3 端点 URL。
在以下示例中，请将*用户输入占位符* 替换为您自己的信息。
**示例 1：使用端点 URL 列出账户中的表存储桶**
```
aws s3tables list-table-buckets --endpoint https://vpce-0123456afghjipljb-aac.s3tables.us-east-1.vpce.amazonaws.com —region us-east-1
```
**示例 2：使用端点 URL 列出存储桶中的表**
```
aws s3tables list-tables --table-bucket-arn arn:aws:s3tables:us-east-1:123456789301:bucket/amzn-s3-demo-bucket --endpoint https://vpce-0123456afghjipljb-aac.s3tables.us-east-1.vpce.amazonaws.com --region us-east-1
```
## 使用查询引擎时配置 VPC 网络
使用查询引擎时，请使用以下步骤配置 VPC 网络。
1. 要开始使用，您可以创建或更新 VPC。有关更多信息，请参阅[创建 VPC](https://docs.aws.amazon.com//vpc/latest/userguide/create-vpc.html#create-vpc-and-other-resources)。
1. 对于路由到 S3 表类数据存储服务的表和表存储桶级操作，请创建一个新的接口端点。有关更多信息，请参阅[使用接口 VPC 端点访问 AWS 服务](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html#create-interface-endpoint-aws)。
1. 对于路由到 Amazon S3 的所有对象级操作，请创建网关端点或接口端点。有关网关端点的更多信息，请参阅 [Create a gateway endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/vpc-endpoints-s3.html#create-gateway-endpoint-s3)。
1. 接下来，配置数据资源并启动 Amazon EMR 集群。有关更多信息，请参阅 [Getting started with Amazon EMR](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-gs.html)。
1. 然后，可以通过从 VPC 端点中选择 DNS 名称，来提交带有额外配置的 Spark 应用程序。例如 `spark.sql.catalog.ice_catalog.s3tables.endpoint` 和 `https://interface-endpoint.s3tables.us-east-1.vpce.amazonaws.com`。有关更多信息，请参阅 [Submit work to your Amazon EMR cluster](https://docs.aws.amazon.com/emr/latest/ManagementGuide/emr-gs.html#emr-getting-started-manage)。
## 使用双堆栈端点访问表和表存储桶
S3 表类数据存储服务支持将双堆栈连接用于 AWS PrivateLink。除了 IPv4 协议之外，双堆栈端点还支持您使用互联网协议版本 6（IPv6）访问 S3 表存储桶，具体取决于网络支持的协议版本。您可以使用以下命名约定通过双堆栈端点访问 S3 存储桶：
```
s3tables..api.aws
```
在尝试在 VPC 中通过 IPv6 访问 S3 表和表存储桶之前，您应该了解以下事项：
+ 用于访问表的客户端和您的 S3 客户端都必须启用了双堆栈。
+ 默认情况下，未为 VPC 安全组启用 IPv6 入站。要支持 IPv6 访问，您需要添加一条新规则，以支持 HTTPS（TCP 端口 443）访问您的安全组。有关更多信息，请参阅《Amazon EC2 用户指南》**中的[https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/changing-security-group.html#add-remove-security-group-rules](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/changing-security-group.html#add-remove-security-group-rules)。
+ 如果您的 VPC 未分配 IPv6 CIDR，则需要手动将 IPv6 CIDR 数据块添加到 VPC。有关更多信息，请参阅《AWS PrivateLink 用户指南》**中的[https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6-add.html](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6-add.html)。
+ 如果您使用 IP 地址筛选 IAM 策略，则必须对这些策略进行更新才能处理 IPv6 地址。有关使用 IAM 管理访问权限的更多信息，请参阅 [Amazon S3 的身份和访问管理](https://docs.aws.amazon.com/AmazonS3/latest/userguide/security-iam.html)。
要创建将双堆栈端点用于 S3 表类数据存储服务的新 VPC 端点，请使用示例 CLI 命令：
```
aws ec2 create-vpc-endpoint \
--vpc-id vpc-id \
--service-name com.amazonaws.aws-region.s3tables \
--subnet-ids subnet-1 subnet-2 \
--vpc-endpoint-type Interface \
--ip-address-type dualstack \
--dns-options "DnsRecordIpType=dualstack" \
--security-group-ids sg-id \
--region aws-region
```
有关创建 VPC 端点的更多信息，请参阅《VPC User Guide》中的 [https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html](https://docs.aws.amazon.com/vpc/latest/privatelink/create-interface-endpoint.html)。
如果您的网络支持 IPv6，并且您想更新您的 VPC 以启用 IPv6，则可以使用以下 CLI 命令：
```
aws ec2 modify-vpc-endpoint \
--vpc-endpoint-id vpce-id \
--ip-address-type dualstack \
--dns-options "DnsRecordIpType=dualstack" \
--region aws-region
```
## 在 VPC 网络中限制对 S3 表类数据存储服务的访问权限
与基于资源的策略类似，可以向 VPC 端点附加端点策略，来控制对表和表存储桶的访问权限。在以下示例中，接口端点策略限制为仅可访问特定的表存储桶。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "Policy141511512309",
"Statement": [
{
"Sid": "Access-to-specific-bucket-only",
"Principal": "*",
"Action": "s3tables:*",
"Effect": "Allow",
"Resource": [
"arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket",
"arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket/*"
]
}
]
}
```
------
# S3 表类数据存储服务的安全注意事项和限制
以下列表描述了 S3 表类数据存储服务不支持或限制哪些安全和访问控制特性和功能。
+ 不支持公有访问策略。用户无法修改存储桶或表策略来支持公有访问。
+ 不支持用于访问与表关联的对象的预签名 URL。
+ 不支持通过 HTTP 发出的请求。对于通过 HTTP 发出的任何请求，Amazon S3 都会自动以 HTTP 重定向作为响应，从而将请求升级到 HTTPS。
+ 使用 REST API 向接入点发出请求时，必须使用 AWS 签名版本 4。
+ 通过互联网协议版本 6（IPv6）发出的请求仅适用于通过表存储端点执行对象级操作，而不适用于表级和存储桶级操作。
+ 表存储桶和表访问策略的大小限制为 20 KB。
# S3 表类数据存储服务的日志记录和监控
监控是维护 Amazon S3 表类数据存储服务的可靠性、可用性和性能的重要组成部分。我们建议从表存储桶的表中收集监控数据，以便更轻松地调试出现的多点故障。
AWS 提供了多种工具来监控 S3 表类数据存储服务资源并对潜在的事件作出响应。
**Amazon CloudWatch 警报**
使用 Amazon CloudWatch 警报，您可以在指定时间段内监控某个指标。如果指标超过给定阈值，则会向 Amazon SNS 主题或 AWS Auto Scaling 策略发送通知。CloudWatch 警报将不会调用操作，因为这些操作处于特定状态。而是必须在状态已改变并在指定的若干个时间段内保持不变后才调用。有关更多信息，请参阅 [使用 Amazon CloudWatch 监控指标](cloudwatch-monitoring.md)。
**AWS CloudTrail 日志**
CloudTrail 提供了用户、角色或 AWS 服务在 Amazon S3 中所执行操作的记录。使用 CloudTrail 收集的信息，您可以确定向 Amazon S3 发出了什么请求、发出请求的 IP 地址、何人发出的请求、请求的发出时间以及其他详细信息。有关更多信息，请参阅 [使用 AWS CloudTrail 记录 Amazon S3 API 调用](cloudtrail-logging.md)。
**Topics**
+ [使用 AWS CloudTrail 对 S3 表类数据存储服务进行日志记录](s3-tables-logging.md)
+ [使用 Amazon CloudWatch 监控指标](s3-tables-cloudwatch-metrics.md)
# 使用 AWS CloudTrail 对 S3 表类数据存储服务进行日志记录
Amazon S3 与 AWS CloudTrail 集成，后者是一项提供由用户、角色或 AWS 服务所采取操作的记录的服务。CloudTrail 将 Amazon S3 的所有 API 调用作为事件捕获。借助通过 CloudTrail 收集的信息，您可以确定向 Amazon S3 发出哪些请求、发出请求的 IP 地址、请求的发出时间以及其它详细信息。当 Amazon S3 中发生受支持的事件活动时，该活动将记录在 CloudTrail 事件中。可以使用 AWS CloudTrail 跟踪来记录 S3 表类数据存储服务的管理事件和数据事件。有关更多信息，请参阅《AWS CloudTrail User Guide》**中的 [Amazon S3 CloudTrail events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html) 和 [What is AWS CloudTrail?](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html)
## S3 表类数据存储服务的 CloudTrail 管理事件
管理事件提供对您 AWS 账户内的资源所执行管理操作的相关信息。
默认情况下，CloudTrail 会记录 S3 表类数据存储服务的管理事件。S3 表类数据存储服务的 CloudTrail 管理事件的 `eventsource` 为 ` s3tables.amazonaws.com`。当您设置 AWS 账户时，CloudTrail 管理事件默认处于启用状态。以下 API 操作由 CloudTrail 跟踪并记录为管理事件。
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_CreateNamespace.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_CreateNamespace.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_CreateTable.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_CreateTable.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_CreateTableBucket.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_CreateTableBucket.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteNamespace.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteNamespace.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTable.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTableBucket.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTableBucket.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTableBucketPolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTableBucketPolicy.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTablePolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_DeleteTablePolicy.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetNamespace.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetNamespace.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTable.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTable.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableBucket.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableBucket.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableBucketMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableBucketMaintenanceConfiguration.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableBucketPolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableBucketPolicy.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableMaintenanceConfiguration.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableMaintenanceJobStatus.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableMaintenanceJobStatus.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableMetadataLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTableMetadataLocation.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTablePolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_GetTablePolicy.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_ListNamespaces.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_ListNamespaces.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_ListTableBuckets.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_ListTableBuckets.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_ListTables.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_ListTables.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_PutTableBucketMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_PutTableBucketMaintenanceConfiguration.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_PutTableMaintenanceConfiguration.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_PutTableMaintenanceConfiguration.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_PutBucketPolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_PutBucketPolicy.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_PutTablePolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_PutTablePolicy.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_RenameTable.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_RenameTable.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_UpdateTableMetadataLocation.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_s3TableBuckets_UpdateTableMetadataLocation.html)
有关 CloudTrail 管理事件的更多信息，请参阅《AWS CloudTrail User Guide》**中的 [Logging management events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html)。
## S3 表类数据存储服务维护的 CloudTrail 管理事件
S3 将自动维护操作作为 `TablesMaintenanceEvent` 管理事件记录到 CloudTrail 中。这些事件发生在诸如压缩和快照到期之类的操作期间。有关 S3 表维护的更多信息，请参阅[表维护](s3-tables-maintenance.md)。
### 如何识别维护事件
您可以通过以下属性值识别 CloudTrail 日志中的 S3 表类数据存储服务维护事件：
+ `eventSource: s3tables.amazonaws.com`
+ `eventType: AwsServiceEvent`
+ `eventName: TablesMaintenanceEvent`
+ `userAgent: maintenance.s3tables.amazonaws.com`
+ `activityType:`
+ `IcebergCompaction`（对于压缩）
+ `IcebergSnapshotManagement`（对于快照到期）
有关压缩维护事件的示例，请参阅[示例 - 表维护管理事件的 CloudTrail 日志文件](s3-tables-log-files.md#example-ct-log-s3tables-3)。
## S3 表类数据存储服务的 CloudTrail 数据事件
数据事件提供对资源或在资源中执行的资源操作的信息。默认情况下，CloudTrail 跟踪不记录数据事件，但您可以将跟踪配置为记录数据事件。
在 CloudTrail 中记录跟踪的数据事件时，您将选择或指定资源类型。S3 表类数据存储服务有两种资源类型：`AWS::S3Tables::Table` 和 `AWS::S3Tables::TableBucket`。
以下数据事件记录到 CloudTrail。
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_AbortMultipartUpload.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateMultipartUpload.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_ListParts.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_UploadPart.html)
有关 CloudTrail 数据事件的更多信息，请参阅《AWS CloudTrail User Guide》**中的 [Logging data events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html)。
有关 S3 表类数据存储服务的 CloudTrail 事件的更多信息，请参阅以下主题：
**Topics**
+ [S3 表类数据存储服务的 CloudTrail 管理事件](#s3-tables-management-events)
+ [S3 表类数据存储服务维护的 CloudTrail 管理事件](#s3-tables-maintenance-events)
+ [S3 表类数据存储服务的 CloudTrail 数据事件](#s3-tables-data-events)
+ [S3 表类数据存储服务的 AWS CloudTrail 数据事件日志文件示例](s3-tables-log-files.md)
# S3 表类数据存储服务的 AWS CloudTrail 数据事件日志文件示例
AWS CloudTrail 日志文件包括有关所请求 API 操作的信息、操作的日期和时间和请求参数等。本主题为 S3 表类数据存储服务的 CloudTrail 数据事件提供示例日志文件。
**Topics**
+ [示例 - `GetObject` 数据事件的 CloudTrail 日志文件](#example-ct-log-s3tables)
+ [示例 - 表维护管理事件的 CloudTrail 日志文件](#example-ct-log-s3tables-3)
+ [示例 - `PutObject` 数据事件的 CloudTrail 日志文件](#example-ct-log-s3tables-2)
## 示例 - `GetObject` 数据事件的 CloudTrail 日志文件
下面的示例显示了一个 CloudTrail 日志文件示例，该示例演示了 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) API 操作。
```
{
"eventVersion": "1.11",
"userIdentity": {
"type": "IAMUser",
"principalId": "123456789012",
"arn": "arn:aws:iam::111122223333:user/"myUserName",
"accountId": "111122223333",
"accessKeyId": "AKIAIOSFODNN7EXAMPLE",
"userName":"myUserName"
},
"eventTime": "2024-11-22T17:12:25Z",
"eventSource": "s3tables.amazonaws.com",
"eventName": "GetObject",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "[aws-cli/2.18.5]",
"requestParameters": {
"Host": "tableWarehouseLocation.s3.us-east-1.amazonaws.com",
"key": "product-info.json"
},
"responseElements": null,
"additionalEventData": {
"SignatureVersion": "SigV4",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"bytesTransferredIn": 0,
"AuthenticationMethod": "AuthHeader",
"xAmzId2": "q6xhNJYmhg",
"bytesTransferredOut": 28441
},
"requestID": "07D681123BD12AED",
"eventID": "f2b287f3-0df1-1234-a2f4-c4bdfed47657",
"readOnly": true,
"resources": [{
"accountId": "111122223333",
"type": "AWS::S3Tables::TableBucket",
"ARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket1"
}, {
"accountId": "111122223333",
"type": "AWS::S3Tables::Table",
"ARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-bucket/table/111aa1111-22bb-33cc-44dd-5555eee66ffff"
}],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "444455556666",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "tableWarehouseLocation.s3.us-east-1.amazonaws.com"
}
}
```
## 示例 - 表维护管理事件的 CloudTrail 日志文件
以下是 CloudTrail 日志文件示例，该示例演示了 S3 在自动表维护过程中执行的表压缩的维护事件。有关表维护事件的更多信息，请参阅 [S3 表类数据存储服务维护的 CloudTrail 管理事件](s3-tables-logging.md#s3-tables-maintenance-events)
```
{
"eventVersion": "1.11",
"userIdentity": {
"type": "AWSService",
"invokedBy": "maintenance.s3tables.amazonaws.com"
},
"eventTime": "2025-09-18T20:13:14Z",
"eventSource": "s3tables.amazonaws.com",
"eventName": "TablesMaintenanceEvent",
"awsRegion": "us-east-1",
"sourceIPAddress": "maintenance.s3tables.amazonaws.com",
"userAgent": "maintenance.s3tables.amazonaws.com",
"requestParameters": null,
"responseElements": null,
"eventID": "b8f96329-ef5c-32b5-94f6-eeed9061ea32",
"readOnly": false,
"resources": [
{
"accountId": "111122223333",
"type": "AWS::S3Tables::TableBucket",
"ARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket"
},
{
"accountId": "111122223333",
"type": "AWS::S3Tables::Table",
"ARN": "arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket/table/7ff7750e-23b3-481e-a90a-7d87d423d336"
}
],
"eventType": "AwsServiceEvent",
"managementEvent": true,
"recipientAccountId": "111122223333",
"sharedEventID": "62a57826-a66e-479b-befa-0e65663ee9e8",
"serviceEventDetails": {
"activityType": "icebergCompaction"
},
"eventCategory": "Management"
}
```
## 示例 - `PutObject` 数据事件的 CloudTrail 日志文件
下面的示例显示了一个 CloudTrail 日志文件示例，该示例演示了 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html) API 操作。
```
{
"eventVersion": "1.11",
"userIdentity": {
"type": "IAMUser",
"principalId": "123456789012",
"arn": "arn:aws:iam::444455556666:user/"myUserName",
"accountId": "444455556666",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName":"myUserName"
},
"eventTime": "2024-11-22T17:12:25Z",
"eventSource": "s3tables.amazonaws.com",
"eventName": "PutObject",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "[aws-cli/2.18.5]",
"requestParameters": {
"Host": "tableWarehouseLocation.s3.us-east-1.amazonaws.com",
"key": "product-info.json"
},
"responseElements": {
"x-amz-server-side-encryption": "AES256",
"x-amz-version-id": "13zAFMdccAjt3MWd6ehxgCCCDRdkAKDw"
},
"additionalEventData": {
"SignatureVersion": "SigV4",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"bytesTransferredIn": 28441,
"AuthenticationMethod": "AuthHeader",
"xAmzId2": "q6xhCJYmhg",
"bytesTransferredOut": 0
},
"requestID": "28d2faaf-1234-4649-997d-EXAMPLE72818",
"eventID": "694d604a-d190-1234-0dd1-EXAMPLEe20c1",
"readOnly": false,
"resources": [{
"accountId": "444455556666",
"type": "AWS::S3Tables::TableBucket",
"ARN": "arn:aws:s3tables:us-east-1:444455556666:bucket/amzn-s3-demo-bucket1"
}, {
"accountId": "444455556666",
"type": "AWS::S3Tables::Table",
"ARN": "arn:aws:s3tables:us-east-1:444455556666:bucket/amzn-s3-demo-bucket1/table/b89ec883-b1d9-4b37-9cd7-b86f590123f4"
}],
"eventType": "AwsApiCall",
"managementEvent": false,
"recipientAccountId": "111122223333",
"eventCategory": "Data",
"tlsDetails": {
"tlsVersion": "TLSv1.2",
"cipherSuite": "ECDHE-RSA-AES128-GCM-SHA256",
"clientProvidedHostHeader": "tableWarehouseLocation.s3.us-east-1.amazonaws.com"
}
}
```
# 使用 Amazon CloudWatch 监控指标
您可以使用 Amazon CloudWatch 指标来跟踪表的性能、检测表的异常情况和监控表的运行状况。有几组 CloudWatch 指标可以与 S3 表类数据存储服务结合使用。
**表和表存储桶的每日存储指标**
监控存储在表和表存储桶中的数据量，包括总大小（以字节为单位）和文件数。这些指标跟踪每个访问层的总存储字节数以及表存储桶、表和命名空间级别的文件计数。适用于 S3 表类数据存储服务的存储指标每天报告一次并提供给所有客户，无需额外费用。
**表维护指标**
监控 Amazon S3 对您的表执行的自动维护操作，例如压缩。这些指标跟踪在维护活动期间处理的字节数和文件数。适用于 S3 表类数据存储服务的维护指标每天报告一次并提供给所有客户，无需额外费用。
**请求指标**
监控 S3 表类数据存储服务请求，以快速识别运行问题并对其采取措施。可以选择为各个表存储桶启用这些 CloudWatch 指标。S3 表类数据存储服务的请求指标每分钟报告一次，费率与 CloudWatch 自定义指标的相同。请求指标包括：
+ 数据面板操作计数（GET、PUT、HEAD、POST）
+ 传输的字节数
+ 延迟测量值
+ 错误率
**注意**
**最大努力 CloudWatch 指标传输**
系统将以最大努力传输 CloudWatch 指标。大多数具有请求指标的针对 Amazon S3 对象的请求会导致将数据点发送到 CloudWatch。
无法保证指标的完整性和及时性。可能返回特定请求的数据点，其时间戳晚于实际处理请求的时间。1 分钟的数据点在通过 CloudWatch 提供之前可能会延迟，或者根本不会提供该数据点。您可以通过 CloudWatch 请求指标近乎实时地了解有关存储桶流量性质方面的信息。这并不意味着会完整记录所有请求。根据此特征的最大努力性质，在账单和成本管理控制面板提供的报告中可能有一个或多个访问请求不会出现在存储桶指标中。
# 指标与维度
以下各表列出了 S3 表类数据存储服务发送到 Amazon CloudWatch 的存储指标和维度。
**注意**
**最大努力 CloudWatch 指标传输**
系统将以最大努力传输 CloudWatch 指标。大多数具有请求指标的针对 Amazon S3 对象的请求会导致将数据点发送到 CloudWatch。
无法保证指标的完整性和及时性。可能返回特定请求的数据点，其时间戳晚于实际处理请求的时间。1 分钟的数据点在通过 CloudWatch 提供之前可能会延迟，或者根本不会提供该数据点。您可以通过 CloudWatch 请求指标近乎实时地了解有关存储桶流量性质方面的信息。这并不意味着会完整记录所有请求。根据此特征的最大努力性质，在账单和成本管理控制面板提供的报告中可能有一个或多个访问请求不会出现在存储桶指标中。
## CloudWatch 中表存储桶的每日存储指标
`AWS/S3/Tables` 命名空间包括以下每日存储指标，这些指标免费提供，无需额外费用。您可以按表存储桶、表或命名空间名称筛选这些指标。
**每日存储指标**
| 指标名称 | 说明 | 单位 | 统计数据 | 粒度 |
| --- | --- | --- | --- | --- |
| 总存储桶存储空间 | 表存储桶中的所有表使用的存储空间量（以字节为单位） | 字节 | 总和 | 每天 |
| 总文件数 | 存储在表存储桶中的所有文件的总数 | 计数 | 总和 | 每天 |
## 表维护指标
`AWS/S3/Tables` 命名空间包括以下表维护指标，这些指标免费提供，无需额外费用。您可以按表存储桶、表或命名空间名称筛选这些指标。
**表维护指标**
| 指标名称 | 说明 | 单位 | 统计数据 | 粒度 |
| --- | --- | --- | --- | --- |
| CompactionBytesProcessed | 表压缩操作期间处理的字节数 | 字节 | 总和 | 每天 |
| CompactionObjectsCount | 表压缩操作期间处理的对象数量 | 计数 | 总和 | 每天 |
## CloudWatch 中表和表存储桶的请求指标
`AWS/S3/Tables` 命名空间包括以下请求指标，这些指标的费率与 CloudWatch 自定义指标的相同。您可以按表存储桶、表或命名空间名称筛选这些指标。
**请求指标**
| 指标名称 | 说明 | 单位 | 统计数据 | 粒度 |
| --- | --- | --- | --- | --- |
| 所有请求计数 | 向表存储桶发出的 HTTP 请求的总数。 | 计数 | 总和 | 1 分钟 |
| Get 请求计数 | 为从表中检索对象而发出的 HTTP GET 请求的数量 | 计数 | 总和 | 1 分钟 |
| Put 请求计数 | 为向表中添加对象而发出的 HTTP PUT 请求的数量 | 计数 | 总和 | 1 分钟 |
| Head 请求计数 | 为从表中检索元数据而发出的 HTTP HEAD 请求的数量 | 计数 | 总和 | 1 分钟 |
| Post 请求计数 | 对表发出的 HTTP POST 请求的数量 | 计数 | 总和 | 1 分钟 |
| UpdateTableMetadataLocation 请求计数 | 为更新表元数据位置而发出的请求的数量 | 计数 | 总和 | 1 分钟 |
| GetTableMetadataLocation 请求计数 | 为检索表元数据位置而发出的请求的数量 | 计数 | 总和 | 1 分钟 |
| BytesDownloaded | 为表请求下载的字节数 | 字节 | 总和 | 1 分钟 |
| BytesUploaded | 为表请求上传的字节数 | 字节 | 总和 | 1 分钟 |
| 4xxErrors | 返回的 HTTP 4xx 客户端错误状态代码的计数 | 计数 | 总和 | 1 分钟 |
| 5xxErrors | 返回的 HTTP 5xx 服务器错误状态代码的计数 | 计数 | 总和 | 1 分钟 |
| FirstByteLatency | 从收到完整请求到开始返回响应的每请求时间。 | 毫秒 | 总和 | 1 分钟 |
| TotalRequestLatency | 从收到第一个字节到发送最后一个字节的已用每请求时间。 | 毫秒 | 总和 | 1 分钟 |
## CloudWatch 中的 S3 表类数据存储服务维度
下列维度用于筛选 S3 表类数据存储服务指标。
**S3 表类数据存储服务维度**
| 维度名称 | 说明 | 示例值 |
| --- | --- | --- |
| TableBucketName | Amazon S3 表存储桶的名称 | my-table-bucket |
| Namespace | 表存储桶中包含一个或多个表的命名空间 | my-department |
| TableName | 命名空间中特定表的名称 | transactions |
# 访问 CloudWatch 指标
可以使用 CloudWatch 控制台、AWS CLI 或 CloudWatch API 来监控 S3 表类数据存储服务指标。本节介绍如何使用这些不同的方法访问指标。
## 使用 S3 控制台
1. 登录 AWS 管理控制台并在 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 中打开 Amazon S3 控制台。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在存储桶列表中，选择存储桶的名称，该存储桶包含您要查看其指标的表。
1. 选择**指标**选项卡。
1. 在任意指标窗格中选择**在 CloudWatch 中查看**，以导航到 CloudWatch 控制台并查看 `AWS/S3/Tables` 命名空间中的可用指标。
## 使用 AWS CLI
要使用 AWS CLI 列出 S3 表类数据存储服务的指标，请使用 `list-metrics` 命令并将 `--namespace` 参数设置为 `AWS/S3/Tables`：
```
aws cloudwatch list-metrics --namespace AWS/S3/Tables
```
要获取特定 S3 表类数据存储服务指标的统计数据，请使用 `get-metric-statistics` 命令。例如：
```
aws cloudwatch get-metric-statistics \
--namespace AWS/S3/Tables \
--metric-name TotalBucketStorage \
--dimensions Name=TableBucketName,Value=MyTableBucket \
--start-time 2025-03-01T00:00:00 \
--end-time 2025-03-02T00:00:00 \
--period 86400 \
--statistics Average
```
## 最佳实践
+ 检索指标时，请根据指标的粒度设置期间值。对于每日指标（如存储指标），请使用 86400 秒（24 小时）。对于分钟级指标（如请求指标），请使用 60 秒。
+ 适当地使用维度将指标筛选到所需范围（表存储桶、命名空间或单个表级别）。
+ 考虑使用指标数学来创建更符合您的监控需求的派生指标。
## 相关资源
+ [Amazon CloudWatch 概念](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html)
+ [使用 Amazon CloudWatch 控制面板](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html)
# 管理 CloudWatch 指标
默认情况下，对所有 Amazon S3 表和表存储桶启用存储指标。您可以通过控制台、AWS Command Line Interface（AWS CLI）或 AWS SDK 启用或禁用其他请求指标。
## 先决条件
+ 需要 `s3table:PutTableBucketMetricsConfiguration` IAM 权限
**注意**
S3 表类数据存储服务请求指标的费率与 CloudWatch 自定义指标的费率相同。
## 使用 AWS 管理控制台
启用或禁用其它指标
1. 登录 AWS 管理控制台并在 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 中打开 Amazon S3 控制台。
1. 在左侧导航窗格中，选择**表存储桶**。
1. 在存储桶列表中，选择表存储桶的名称，该存储桶包含您要请求其指标的表。
1. 选择**指标**选项卡。
1. 从“请求指标”面板中，选择**编辑**。
1. 选择**已启用**或**已禁用**，然后选择**保存更改**。
## 使用 AWS CLI
这些示例说明如何使用 AWS CLI 为表存储桶启用或禁用请求指标。要使用这些命令，请将*用户输入占位符*替换为您自己的信息。
**Example ：为表存储桶启用请求指标：**
```
aws s3tables put-table-bucket-metrics-configuration \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket
```
**Example ：为表存储桶禁用请求指标：**
```
aws s3tables delete-table-bucket-metrics-configuration \
--table-bucket-arn arn:aws:s3tables:us-east-1:111122223333:bucket/amzn-s3-demo-table-bucket
```