跳到主要内容
版本：3.0.0

GcsFile

Google Cloud Storage 文件 Source 连接器

支持的引擎​

Spark
Flink
SeaTunnel Zeta

主要特性​

描述​

通过 Google Cloud Storage Hadoop 连接器读取 GCS 文件。格式解析、Schema 发现、列投影、文件切分和多表任务复用 SeaTunnel File Source 的现有实现。

bucket 必须是 gs://my-bucket 形式的存储桶 URI。path 是存储桶内的对象或前缀，例如 /data/orders。不要把对象路径写入 bucket。

依赖​

本连接器使用 com.google.cloud.bigdataoss:gcs-connector:hadoop3-2.2.33:shaded。该依赖采用 Apache License 2.0，并以 Java 8 为目标版本。shaded GCS Hadoop 库已打包到 connector-file-gcs 连接器 JAR 中。Spark 和 Flink 部署必须在驱动节点和所有工作节点提供兼容的 Hadoop 3 运行环境。

认证​

连接器支持以下认证方式：

  1. 应用默认凭据（ADC）：不配置 service_account_key_file。Hadoop GCS 连接器会从 GOOGLE_APPLICATION_CREDENTIALS 或 Google Cloud 运行环境绑定的服务账号获取凭据。
  2. 服务账号 JSON 文件：配置 service_account_key_file。该本地路径必须以相同位置存在于每个读取 GCS 的节点上。

显式配置的 service_account_key_file 优先于 hadoop_gcs_properties 中的同名 Hadoop 属性。

配置项​

名称类型是否必填默认值描述
pathstring是-bucket 内的对象或前缀路径，例如 /data/orders。
file_format_typestring是-文件格式：text、csv、parquet、orc、json、excel、xml、binary、markdown 或 pdf。
bucketstring是-GCS 存储桶 URI，例如 gs://my-bucket。
service_account_key_filestring否-每个工作节点上的服务账号 JSON 文件。省略时使用 ADC。
hadoop_gcs_propertiesmap否-额外的 fs.gs.* Hadoop 属性。显式连接器配置优先。
schemaconfig条件必填-text、json、excel、csv 和 xml 格式需要配置。参见 Schema 功能。
read_columnslist否-从数据源投影的列。
field_delimiterstring否text 为 \001，CSV 为 ,text 和 CSV 的字段分隔符，delimiter 是其别名。
row_delimiterstring否\ntext 文件的行分隔符。
skip_header_row_numberlong否0跳过 text 或 CSV 文件开头的行数。
encodingstring否UTF-8text、JSON、CSV 和 XML 的字符编码。
parse_partition_from_pathboolean否true从 /year=2026/month=08 形式的路径解析分区值。
recursive_file_scanboolean否true是否递归扫描子目录。
file_filter_patternstring否-文件名过滤模式。
filename_extensionstring否-文件扩展名过滤，例如 csv 或 .json。
compress_codecstring否none单个压缩文件的压缩编码。
archive_compress_codecstring否none归档压缩编码。
enable_file_splitboolean否false为未压缩的 text、CSV、JSON 和 Parquet 文件启用逻辑切分。
file_split_sizelong条件必填134217728enable_file_split=true 时的切分大小，单位为字节。
null_formatstring否-表示空值的文本。
quote_charstring否"CSV 引号字符。
escape_charstring否-CSV 转义字符。
sheet_namestring否-要读取的 Excel 工作表。
excel_enginestring否POIExcel 读取器：POI 或 EasyExcel。
poi_excel_max_file_sizelong否52428800POI 引擎可读取的最大 Excel 文件字节数。
xml_row_tagstring条件必填-表示一行数据的 XML 元素。
xml_use_attr_formatboolean条件必填-是否从 XML 属性读取值。
discovery_modestring否onceonce 或 continuous。连续发现当前要求 update 同步和 binary 格式。
scan_intervalstring否10S连续发现的轮询间隔。
start_modestring否earliestearliest 处理已有文件，latest 从后续变更开始。
sync_modestring否fullfull 或 update。update 当前仅支持 binary 格式。
target_pathstring条件必填-sync_mode=update 时必填，用于按相对路径比较对象。
target_hadoop_confmap否-比较目标文件系统的 Hadoop 配置。
update_strategystring否distcp更新比较策略：distcp 或 strict。
compare_modestring否len_mtimelen_mtime 或 checksum；checksum 要求 strict 策略。
update_compare_parallelismint否8目标元数据查询并行度，范围为 1 到 64。
update_compare_bulk_thresholdint否0正数表示达到阈值后使用批量目录列举；0 表示禁用。
post_sync_actionstring否none连续发现对象完成 checkpoint 后的动作：none、delete 或 backup。
backup_pathstring条件必填-post_sync_action=backup 时必填，且不能与源路径重叠。
retention_max_agestring否-SeaTunnel 备份对象的最大保留时间。
retention_check_intervalstring否1H备份保留扫描间隔。
common-options否-参见 Source 通用配置。

示例​

使用 ADC 读取 Parquet​

source {
  GcsFile {
    bucket = "gs://my-bucket"
    path = "/warehouse/orders"
    file_format_type = "parquet"
  }
}

使用服务账号读取 CSV​

source {
  GcsFile {
    bucket = "gs://my-bucket"
    path = "/landing/customers"
    file_format_type = "csv"
    service_account_key_file = "/opt/seatunnel/keys/gcs-reader.json"
    skip_header_row_number = 1
    schema {
      fields {
        id = long
        name = string
      }
    }
    hadoop_gcs_properties = {
      "fs.gs.project.id" = "my-project"
    }
  }
}

Changelog​

Change Log
ChangeCommitVersion
|[Feature][Connector-V2] Add Google Cloud Storage file sink (#12146)|https://github.com/apache/seatunnel/commit/72acda570|3.0.0| |[Feature][Connector-V2] Add Google Cloud Storage file source (#11967)|https://github.com/apache/seatunnel/commit/96d8e8d39|3.0.0|