# Amazon S3 连接
<a name="aws-glue-programming-etl-connect-s3-home"></a>

您可以使用 Amazon Glue for Spark 在 Amazon S3 中读取和写入文件。AmazonGlue for Spark 支持许多开箱即用的存储在 Amazon S3 中的常见数据格式，包括 CSV、Avro、JSON、Orc 和 Parquet。有关支持的数据格式的更多信息，请参阅 [Amazon Glue for Spark 中的输入和输出的数据格式选项](aws-glue-programming-etl-format.md)。每种数据格式可能支持不同的 Amazon Glue 功能集。有关功能支持的细节，请查阅您的数据格式页面。此外，您可以读取和写入存储在 Hudi、Iceberg 和 Delta Lake 数据湖框架中的版本控制文件。有关数据湖框架的更多信息，请参阅 [在 Amazon Glue ETL 任务中使用数据湖框架](aws-glue-programming-etl-datalake-native-frameworks.md)。

使用 Amazon Glue，您可以在写入时将 Amazon S3 对象分成文件夹结构，然后使用简单的配置按分区检索以提高性能。您还可以设置配置，以便在转换数据时将小文件分组在一起以提高性能。您可以在 Amazon S3 中进行读写 `bzip2` 和 `gzip` 存档。

**Topics**
+ [配置 S3 连接](#aws-glue-programming-etl-connect-s3-configure)
+ [Amazon S3 连接选项参考](#aws-glue-programming-etl-connect-s3)
+ [已弃用的数据格式连接语法](#aws-glue-programming-etl-connect-legacy-format)
+ [排除 Amazon S3 存储类](aws-glue-programming-etl-storage-classes.md)
+ [管理 Amazon Glue 中用于 ETL 输出的分区](aws-glue-programming-etl-partitions.md)
+ [以较大的组读取输入文件](grouping-input-files.md)
+ [适用于 Amazon S3 的 Amazon VPC 终端节点](vpc-endpoints-s3.md)

## 配置 S3 连接
<a name="aws-glue-programming-etl-connect-s3-configure"></a>

要在 Amazon Glue with Spark 作业中连接到 Amazon S3，需要具备一些先决条件：
+ Amazon Glue 作业必须拥有对相关 Amazon S3 存储桶的 IAM 权限。

在某些情况下，您需要配置其他先决条件：
+ 配置跨账户访问时，需要对 Amazon S3 存储桶进行适当的访问控制。
+ 出于安全考虑，您可以选择通过 Amazon VPC 路由您的 Amazon S3 请求。此方法可能会带来带宽和可用性方面的难题。有关更多信息，请参阅 [适用于 Amazon S3 的 Amazon VPC 终端节点](vpc-endpoints-s3.md)。

## Amazon S3 连接选项参考
<a name="aws-glue-programming-etl-connect-s3"></a>

指定与 Amazon S3 的连接。

由于 Amazon S3 管理文件而不是表，因此除了指定本文档中提供的连接属性外，您还需要指定有关文件类型的额外配置。您可以通过数据格式选项来指定此信息。有关格式选项的更多信息，请参阅 [Amazon Glue for Spark 中的输入和输出的数据格式选项](aws-glue-programming-etl-format.md)。您也可以通过与 Amazon Glue Data Catalog 集成来指定此信息。

有关连接选项和格式选项之间区别的示例，请考虑 [create\_dynamic\_frame\_from\_options](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_options) 方法如何采用 `connection_type`、`connection_options`、`format` 和 `format_options`。本节专门讨论提供给 `connection_options` 的参数。

`"connectionType": "s3"` 可使用以下连接选项：
+ `"paths"`：（必需）要从中读取数据的 Amazon S3 路径的列表。
+ `"exclusions"`：（可选）包含要排除的 Unix 样式 glob 模式的 JSON 列表的字符串。例如，`"[\"**.pdf\"]"` 会排除所有 PDF 文件。有关 Amazon Glue 支持的 glob 语法的更多信息，请参阅[包含和排除模式](https://docs.amazonaws.cn/glue/latest/dg/define-crawler.html#crawler-data-stores-exclude)。
+ `"compressionType"` 或 "`compression`"：（可选）指定数据压缩方式。使用适用于 Amazon S3 源的 `"compressionType"` 以及适用于 Amazon S3 目标的 `"compression"`。通常，如果数据有标准文件扩展名，则不需要指定。可能的值为 `"gzip"` 和 `"bzip2"`。特定格式可能支持其他压缩格式。有关功能支持的细节，请查阅数据格式页面。
+ `"groupFiles"`：（可选）当输入包含超过 50,000 个文件时，默认启用文件分组。当少于 50,000 个文件时，若要启用分组，请将此参数设置为 `"inPartition"`。当超过 50,000 个文件时，若要禁用分组，请将此参数设置为 `"none"`。
+ `"groupSize"`：（可选）目标组大小（以字节为单位）。默认值根据输入数据大小和群集大小进行计算。当少于 50,000 个输入文件时，`"groupFiles"` 必须设置为 `"inPartition"`，此选项才能生效。
+ `"recurse"`：（可选）如果设置为 true，则以递归方式读取指定路径下的所有子目录中的文件。
+ `"maxBand"`：（可选，高级）此选项控制 `s3` 列表可能保持一致的持续时间（以毫秒为单位）。当使用 `JobBookmarks` 来表明 Amazon S3 最终一致性时，将专门跟踪修改时间戳在最后 `maxBand` 毫秒内的文件。大多数用户不需要设置此选项。默认值为 900000 毫秒或 15 分钟。
+ `"maxFilesInBand"`：（可选，高级）此选项指定在最后 `maxBand` 秒内可保存的最大文件数量。如果超过此值，额外的文件将会跳过，且只能在下一次作业运行中处理。大多数用户不需要设置此选项。
+ `"isFailFast"`：（可选）此选项用于确定 Amazon Glue ETL 任务是否导致读取器解析异常。如果设置为 `true`，并且 Spark 任务的四次重试无法正确解析数据，则任务会快速失败。
+ `"catalogPartitionPredicate"`：（可选）用于读取。SQL `WHERE` 子句的内容。从具有大量分区的 Data Catalog 表中读取时使用。从 Data Catalog 索引中检索匹配的分区。与 `push_down_predicate` 一起使用，[create\_dynamic\_frame\_from\_catalog](aws-glue-api-crawler-pyspark-extensions-glue-context.md#aws-glue-api-crawler-pyspark-extensions-glue-context-create_dynamic_frame_from_catalog) 方法（以及其他类似方法）上的一个选项。有关更多信息，请参阅 [使用目录分区谓词进行服务器端筛选](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-cat-predicates)。
+ `"partitionKeys"`：（可选）用于写入。列标签字符串数组。AmazonGlue 将按照此配置的指定对您的数据进行分区。有关更多信息，请参阅 [写入分区](aws-glue-programming-etl-partitions.md#aws-glue-programming-etl-partitions-writing)。
+ `"excludeStorageClasses"`：（可选）用于读取。指定 Amazon S3 存储类的字符串数组。AmazonGlue 将根据此配置排除 Amazon S3 对象。有关更多信息，请参阅 [排除 Amazon S3 存储类](aws-glue-programming-etl-storage-classes.md)。

## 已弃用的数据格式连接语法
<a name="aws-glue-programming-etl-connect-legacy-format"></a>

某些数据格式可以使用特定的连接类型语法进行访问。此语法已被弃用。我们建议您改用 [Amazon Glue for Spark 中的输入和输出的数据格式选项](aws-glue-programming-etl-format.md) 中提供的 `s3` 连接类型和格式选项来指定格式。

### "connectionType": "orc"
<a name="aws-glue-programming-etl-connect-orc"></a>

指定与 Amazon S3 中以 [Apache Hive 优化的行列式（ORC）](https://cwiki.apache.org/confluence/display/Hive/LanguageManual+ORC)文件格式存储的文件的连接。

`"connectionType": "orc"` 可使用以下连接选项：
+ `paths`：（必需）要从中读取数据的 Amazon S3 路径的列表。
+ *（其他选项名称/值对）*：任何其他选项（包括格式化选项）将直接传递给 SparkSQL `DataSource`。

### "connectionType": "parquet"
<a name="aws-glue-programming-etl-connect-parquet"></a>

指定与 Amazon S3 中以 [Apache Parquet](https://parquet.apache.org/docs/) 文件格式存储的文件的连接。

`"connectionType": "parquet"` 可使用以下连接选项：
+ `paths`：（必需）要从中读取数据的 Amazon S3 路径的列表。
+ *（其他选项名称/值对）*：任何其他选项（包括格式化选项）将直接传递给 SparkSQL `DataSource`。