Google Cloud Storage

支持的管道类型:

  •  Data Collector

Google Cloud Storage目标端将数据写入Google Cloud Storage中的对象。您可以使用其他目标写入Google BigQuery,Google Bigtable和Google Pub/Sub。

目标端为写入Google Cloud Storage的每批数据创建一个对象。

使用Google Cloud Storage目标端,您可以配置存储桶和通用前缀来定义在何处写入对象。您可以使用分区前缀来指定要写入的分区。您可以为对象名称配置前缀,为阶段配置时间基准和数据时区。当使用除整个文件以外的任何数据格式时,您还可以为对象名称配置后缀,并在写入Google Cloud Storage之前使用gzip压缩数据。

目标端可以为事件流生成事件。有关事件框架的更多信息,请参见《数据流触发器概述》。

凭据

在写入Google Cloud Storage之前,Google Cloud Storage目标端必须将凭据传递给Google Cloud Storage。配置目标端以从Google应用程序默认凭据或Google Cloud服务帐户凭据文件中检索凭据。

默认凭据提供程序

配置为使用Google应用程序默认凭据时,目标端将检查GOOGLE_APPLICATION_CREDENTIALS环境变量中定义的凭据文件 。如果环境变量不存在,并且Data Collector在Google Cloud Platform(GCP)中的虚拟机(VM)上运行,则目标端使用与虚拟机实例关联的内置服务帐户。

有关默认凭据的更多信息,请参阅Google Developer文档中的Google Application默认凭据。

完成以下步骤以在环境变量中定义凭据文件:

  1. 使用Google Cloud Platform Console或 gcloud命令行工具创建Google服务帐户,并使您的应用程序使用该帐户进行API访问。

    例如,要使用命令行工具,请运行以下命令:

    gcloud iam service-accounts create my-account
    gcloud iam service-accounts keys create key.json --iam-account=my-account@my-project.iam.gserviceaccount.com
  2. 将生成的凭据文件存储在Data Collector计算机上。
  3. GOOGLE_APPLICATION_CREDENTIALS 环境变量添加到适当的文件,并将其指向凭据文件。

    使用安装类型所需的方法来修改环境变量。

    如下设置环境变量:

    export GOOGLE_APPLICATION_CREDENTIALS="/var/lib/sdc-resources/keyfile.json"
  4. 重新启动Data Collector以启用更改。
  5. 在该阶段的“Credentials选项卡上, 为凭据提供者选择“Default Credentials Provider”。

服务帐户凭据(JSON)

配置为使用Google Cloud服务帐户凭据文件时,目标端将检查目标端属性中定义的文件。

完成以下步骤以使用服务帐户凭据文件:

  1. 生成JSON格式的服务帐户凭据文件。

    使用Google Cloud Platform Console或gcloud命令行工具来生成和下载凭据文件。有关更多信息,请参阅Google Cloud Platform文档中的生成服务帐户凭据。

  2. 将生成的凭证文件存储在Data Collector计算机上。

    最佳做法是将文件存储在 Data Collector资源目录$SDC_RESOURCES中 。

  3. 在该阶段的“Credentials选项卡上,为凭证提供者选择“Service Account Credentials File,然后输入凭证文件的路径。

分区前缀

您可以使用分区前缀按分区组织对象。您可以使用分区前缀来写入现有分区或根据需要创建新分区。当分区前缀中指定的分区不存在时,目标端将创建该分区。

您可以为分区前缀指定确切的分区名称,也可以使用计算结果为分区名称的表达式。

例如,要基于Country字段中的数据写入分区,可以使用以下表达式作为分区前缀: ${record:value('/Country')}

使用此表达式,目标将根据记录中的Country数据将记录写入分区,并为尚无分区的国家创建分区。

如果在表达式中使用datetime变量,请确保为该阶段配置时间基准。

时间基准,数据时区和基于时间的分区前缀

时间基准和数据时区包括Google Cloud Storage目标端将记录写入基于时间的分区前缀所用的时间。如果配置的分区前缀不包含基于时间的功能,则可以忽略时间基准属性。

当分区前缀包含日期时间变量(例如${YYYY()}${DD()})或包含计算结果为日期时间值的表达式 (例如${record:value("/Timestamp")})时,它具有时间分量。

有关日期时间变量的详细信息,请参见日期时间变量。

您可以使用以下时间作为时间基础:

处理时间
当您将处理时间用作时间基准时,目标端将根据处理时间和配置的分区前缀执行写操作。处理时间是默认情况下与运行管道的Data Collector关联的时间。您可以通过配置数据时区属性来指定其他时区。要将处理时间用作时间基准,请使用以下表达式:

${time:now()}

这是默认的时间基准。

记录时间
当您使用与记录关联的时间作为时间基准时,您可以在记录中指定日期字段。目标端根据与记录关联的日期时间写入数据,并调整为“Data Time Zone”属性指定的值。
要使用与记录关联的时间,请使用一个表达式,该表达式调用一个字段并解析为日期时间值,例如 ${record:value("/Timestamp")}

例如,假设您使用以下datetime变量定义Partition Prefix属性:

logs-${YYYY()}-${MM()}-${DD()}

如果使用处理时间作为时间基准,则目标端将根据其处理每个记录的时间将记录写入分区。如果使用与数据相关联的时间(例如事务时间戳记),那么目标端将根据该时间戳记将记录写入分区。如果不存在分区,则目标端将创建所需的分区。

对象名称

Google Cloud Storage目标端会为每批写入的数据创建一个对象或文件。对象通常使用以下命名约定:

<prefix>-<UUID>

您配置对象名称前缀。例如: sdc-c9a2db16-b5d0-44cb-b3f5-d0781cced760

您可以选择为所有数据格式(整个文件除外)配置一个对象名称后缀。配置后缀时,后缀将在一段时间后添加到对象名称中,如下所示:

<prefix>-<UUID>.<optional suffix>

例如:sdc-c9a2db16-b5d0-44cb-b3f5-d0781cced760.txt

整个文件名

使用整个文件数据格式时,对象名称前缀是可选的。整个文件是基于“File Name Expression”属性命名的。如果配置对象名称前缀,则整个文件的命名如下:

<prefix>-<results of the file name expression>

事件生成

Google Cloud Storage目标端可以生成可在事件流中使用的事件。启用事件生成后,每次目标端完成写入对象或完成流式传输整个文件时,Google Cloud Storage都会生成事件记录。

Google Cloud Storage事件可以任何逻辑方式使用。例如:

  • 使用电子邮件执行程序在收到事件后发送自定义电子邮件。

    有关示例,请参阅案例研究:发送电子邮件。

  • 具有用于存储事件信息的目标端。

    有关示例,请参见案例研究:事件存储。

有关数据流触发器和事件框架的更多信息,请参见数据流触发器概述。

事件记录

由Google Cloud Storage目标端生成的事件记录具有以下与事件相关的记录头属性。记录头属性存储为字符串值:

记录头属性 描述
sdc.event.type 事件类型。使用以下类型之一:

  • GCS Object Written-当目标端完成对对象的写入时生成。
  • wholeFileProcessed-在目标端完成流式传输整个文件时生成。
sdc.event.version 整数,指示事件记录类型的版本。
sdc.event.creation_timestamp 阶段创建事件的时间戳记。

Google Cloud Storage目标端可以生成以下类型的事件记录:

Object written
当目标端完成对对象的写入时,它会生成一个对象写入事件记录。
对象写的事件记录的sdc.event.type记录头属性设置为GCS Object Written,包括以下字段:

字段 描述
bucket 对象所在的存储桶。
objectKey 写入的对象键名称。
recordCount 写入对象的记录数。
Whole file processed
目标端在完成流式传输整个文件时会生成一个事件记录。整个文件事件记录的 sdc.event.type记录头属性设置为 wholeFileProcessed,包括以下字段:

字段 描述
sourceFileInfo 关于已处理的原始整个文件的属性映射。

属性名称取决于源系统提供的信息。

targetFileInfo 关于写入目标端系统的整个文件的属性映射。这些属性包括:

  • bucket-写入整个文件的存储桶。
  • objectKey-写入的对象键名称。
checksum 为写入文件生成的校验和。

仅当您将目标端配置为在事件记录中包括校验和时才包括。

checksumAlgorithm 用于生成校验和的算法。

仅当您将目标端配置为在事件记录中包括校验和时才包括。

数据格式

Google Cloud Storage目标端根据您选择的数据格式将数据写入Google Cloud Storage。您可以使用以下数据格式:

Avro
目标根据Avro模式写入记录。您可以使用以下方法之一来指定Avro模式定义的位置:
  • In Pipeline Configuration – 使用您在阶段配置中提供的模式。
  • In Record Header – 使用avroSchema记录头属性中包含的模式。
  • Confluent Schema Registry – 从Confluent Schema Registry检索模式。Confluent Schema Registry是Avro模式的分布式存储层。您可以配置目标以通过模式ID或主题在Confluent Schema Registry中查找模式。

    如果在阶段或记录头属性中使用Avro模式,则可以选择配置目标以向Confluent Schema Registry注册Avro模式。

目标端在每个文件中都包含模式定义。
您可以使用Avro支持的压缩编解码器压缩数据。使用Avro压缩时,请避免在目标端使用其他压缩属性。
Delimited
目标端将记录写为分隔数据。使用此数据格式时,根字段必须是list或list-map。

您可以使用以下分隔格式类型:

  • Default CSV-包含逗号分隔值的文件。忽略文件中的空行。
  • RFC4180 CSV-严格遵循RFC4180准则的逗号分隔文件。
  • MS Excel CSV -Microsoft Excel逗号分隔文件。
  • MySQL CSV -MySQL逗号分隔文件。
  • Tab-Separated Values -包含制表符分隔的值的文件。
  • PostgreSQL CSV -PostgreSQL逗号分隔文件。
  • PostgreSQL文本 -PostgreSQL文本文件。
  • Custom -使用用户定义的分隔符,转义符和引号字符的文件。
  • Multi Character Delimited-使用多个用户定义的字符分隔字段和行以及单个用户定义的转义和引号字符的文件。
JSON
目标端将记录写为JSON数据。您可以使用以下格式之一:

  • Array-每个文件都包含一个数组。在数组中,每个元素都是每个记录的JSON表示形式。
  • Multiple objects-每个文件都包含多个JSON对象。每个对象都是一条记录的JSON表示形式。
Protobuf
在每个文件中写入一批消息。
在描述符文件中使用用户定义的消息类型和消息类型的定义来在文件中生成消息。
有关生成描述符文件的信息,请参阅Protobuf数据格式先决条件。
SDC Record
目标端以SDC记录数据格式写入记录。
Text
目标端将数据从单个文本字段写入目标系统。配置阶段时,请选择要使用的字段。
您可以配置字符以用作记录分隔符。默认情况下,目标使用UNIX样式的行尾(\n)分隔记录。
当记录不包含选定的文本字段时,目标端可以将缺少的字段报告为错误或忽略该丢失的字段。默认情况下,目标端报告错误。
当配置为忽略缺少的文本字段时,目标端可以丢弃该记录或写入记录分隔符以为该记录创建一个空行。默认情况下,目标端丢弃记录。
Whole File
将整个文件流式传输到目标系统。目标端将数据写入阶段中定义的文件和位置。如果已经存在相同名称的文件,则可以将目标端配置为覆盖现有文件或将当前文件发送给错误文件。
写入的文件使用目标系统中定义的默认权限。
您可以配置目标端以生成写入文件的校验和,并将校验和信息传递到事件记录中的目标系统。
有关整个文件数据格式的更多信息,请参见整个文件数据格式。

配置Google Cloud Storage目标端

配置Google Cloud Storage目标端以将对象写入Google Cloud Storage。
  1. 在“Properties”面板的“General选项卡上,配置以下属性:
    一般属性 描述
    Name 阶段名。
    Description 可选说明。
    Required Fields 必须包含用于将记录传递到阶段的记录的数据的字段。

    提示:您可能包括阶段使用的字段。

    根据为管道配置的错误处理,处理不包括所有必填字段的记录。

    Preconditions 必须评估为TRUE的条件才能使记录进入处理阶段。单击 添加以创建其他前提条件。

    根据为该阶段配置的错误处理,处理不满足所有前提条件的记录。

    On Record Error 该阶段的错误记录处理:

    • Discard-放弃记录。
    • To Error-将记录发送到管道以进行错误处理。
    • Stop Pipeline-停止管道。对集群管道无效。
  2. 在“GCS”选项卡上,配置以下属性:
    GCS属性 描述
    Bucket 写入记录时要使用的存储桶。

    注意:存储桶名称必须符合DNS。有关存储区命名约定的更多信息,请参阅Google Cloud Storage文档。
    Common Prefix 确定对象写入位置的通用前缀。
    Partition Prefix 可选的分区前缀,用于指定要使用的分区。

    使用特定的分区前缀或定义一个计算结果为分区前缀的表达式。

    在表达式中使用datetime变量时,请确保为该阶段配置时间基准。

    Data Time Zone

    目标系统的时区。用于解析基于时间的分区前缀中的日期时间。

    Time Basis

    用于写入基于时间的存储桶或分区前缀的时间基准。使用以下表达式之一:

    • ${time:now()} – 将处理时间与指定的数据时区一起用作时间基准。
    • 调用一个字段并解析为日期时间值的表达式,例如 ${record:value(<date field path>)}。使用与记录关联的时间作为时间基准,并针对指定的数据时区进行调整。

    如果“Partition Prefix”属性没有时间分量,则可以忽略此属性。

    默认值为${time:now()}

    Object Name Prefix 定义目标端写入的对象名称的前缀。默认情况下,对象名称以“sdc”开头,如下所示:sdc-<UUID>

    整个文件数据格式不是必需的。

    Object Name Suffix 用于对象名称的后缀,例如txt或json。使用目标端时,目的地将添加一个句点和配置的后缀,如下所示:<object name>.<suffix>。

    您可以在后缀中包括句点,但不要以句点开头。不允许使用正斜杠。

    不适用于整个文件数据格式。

    Compress with Gzip 在写入Google Cloud Storage之前,先使用gzip压缩文件。

    不适用于整个文件数据格式。

  3. 在“Data Format选项卡上,配置以下属性:
    数据格式属性 描述
    Data Format 数据格式写入数据:

    • Avro
    • Delimited
    • JSON
    • Protobuf
    • SDC Record
    • Text
    • Whole File
  4. 对于Avro数据,在“Data Format选项卡上,配置以下属性:
    Avro属性 描述
    Avro Schema Location 写入数据时要使用的Avro模式定义的位置:

    • In Pipeline Configuration-使用您在阶段配置中提供的模式。
    • In Record Header-在avroSchema 记录头属性中使用模式 。仅在为所有记录定义avroSchema属性时使用。
    • Confluent Schema Registry-从Confluent Schema Registry检索模式。
    Avro Schema 用于写入数据的Avro模式定义。

    您可以选择使用该runtime:loadResource 函数来加载存储在运行时资源文件中的模式定义。

    Register Schema 向Confluent Schema Registry注册新的Avro模式。
    Schema Registry URLs 汇合的模式注册表URL,用于查找模式或注册新模式。要添加URL,请单击添加,然后以以下格式输入URL:

    http://<host name>:<port number>
    Basic Auth User Info 使用基本身份验证时连接到Confluent Schema Registry所需的用户信息。

    schema.registry.basic.auth.user.info使用以下格式从Schema Registry中的设置中输入密钥和机密 :

    <key>:<secret>
    提示: 要保护敏感信息(例如用户名和密码),可以使用运行时资源或凭据存储。
    Look Up Schema By 在Confluent Schema Registry中查找模式的方法:

    • Subject-查找指定的Avro模式主题。
    • Schema ID-查找指定的Avro模式ID。
    Schema Subject Avro模式可以在Confluent Schema Registry中进行查找或注册。

    如果要查找的指定主题具有多个模式版本,则目标对该主题使用最新的模式版本。要使用旧版本,请找到相应的模式ID,然后将“Look Up Schema By 属性设置为“Schema ID”。

    Schema ID 在Confluent Schema Registry中查找的Avro模式ID。
    Include Schema 在每个文件中包含模式。

    注意:省略模式定义可以提高性能,但是需要适当的模式管理,以避免丢失与数据关联的模式的跟踪。
    Avro Compression Codec 要使用的Avro压缩类型。

    使用Avro压缩时,请勿在目标中启用其他可用压缩。

  5. 对于分隔数据,在“Data Format选项卡上,配置以下属性:
    分隔属性 描述
    Delimiter Format 分隔数据的格式:

    • Default CSV-包含逗号分隔值的文件。忽略文件中的空行。
    • RFC4180 CSV-严格遵循RFC4180准则的逗号分隔文件。
    • MS Excel CSV -Microsoft Excel逗号分隔文件。
    • MySQL CSV -MySQL逗号分隔文件。
    • Tab-Separated Values -包含制表符分隔的值的文件。
    • PostgreSQL CSV -PostgreSQL逗号分隔文件。
    • PostgreSQL Text -PostgreSQL文本文件。
    • Custom -使用用户定义的分隔符,转义符和引号字符的文件。
    • Multi Character Delimited-使用多个用户定义的字符分隔字段和行以及单个用户定义的转义和引号字符的文件。
    Header Line 指示是否创建标题行。
    Replace New Line Characters 用配置的字符串替换换行符。

    在将数据写为单行文本时推荐使用。

    New Line Character Replacement 用于替换每个换行符的字符串。例如,输入一个空格以将每个换行符替换为一个空格。

    留空以删除新行字符。

    Delimiter Character 自定义分隔符格式的分隔符。选择一个可用选项,或使用“Other”输入自定义字符。

    您可以输入使用格式\ U A的Unicode控制符NNNN,其中N是数字0-9或字母AF十六进制数字。例如,输入\ u0000以将空字符用作分隔符,或输入\ u2028以将行分隔符用作分隔符。

    默认为竖线字符(|)。

    Escape Character 自定义分隔符格式的转义符。选择一个可用选项,或使用“Other”输入自定义字符。

    默认为反斜杠字符(\)。

    Quote Character 自定义分隔符格式的引号字符。选择一个可用选项,或使用“Other”输入自定义字符。

    默认为引号字符(””)。

    Charset 写入数据时使用的字符集。
  6. 对于JSON数据,在“Data Format”选项卡上,配置以下属性:
    JSON属性 描述
    JSON Content 写入JSON数据的方法:

    • JSON Array of Objects-每个文件都包含一个数组。在数组中,每个元素都是每个记录的JSON表示形式。
    • Multiple JSON Objects-每个文件包含多个JSON对象。每个对象都是记录的JSON表示形式。
    Charset 写入数据时使用的字符集。
  7. 对于protobuf数据,在“Data Format选项卡上,配置以下属性:
    Protobuf属性 描述
    Protobuf Descriptor File 要使用的描述符文件(.desc)。描述符文件必须位于Data Collector资源目录中$SDC_RESOURCES

    有关环境变量的更多信息,请参阅《 Data Collector环境配置》。有关生成描述符文件的信息,请参阅Protobuf数据格式先决条件。

    Message Type 写入数据时使用的消息类型的全限定名称。

    使用以下格式: <package name>.<message type>

    使用在描述符文件中定义的消息类型。

  8. 对于文本数据,在“Data Format选项卡上,配置以下属性:
    文本属性 描述
    Text Field Path 包含要写入的文本数据的字段。所有数据必须合并到指定字段中。
    Record Separator 用于分隔记录的字符。使用任何有效的Java字符串文字。例如,当写入Windows时,您可能会\r\n用来分隔记录。

    默认情况下,目标使用 \n

    On Missing Field 当记录不包含文本字段时,确定目标是将丢失的字段报告为错误还是忽略该丢失的字段。
    Insert Record Separator if No Text 当配置为忽略缺少的文本字段时,插入配置的记录分隔符字符串以创建一个空行。

    如果未选择,则丢弃没有文本字段的记录。

    Charset 写入数据时使用的字符集。
  9. 对于整个文件,在“Data Format选项卡上,配置以下属性:
    整个文件属性 描述
    File Name Expression

    用于文件名的表达式。

    有关如何根据输入文件名命名文件的提示,请参阅“写整个文件”。

    File Exists 当输出目录中已经存在同名文件时采取的措施。使用以下选项之一:

    • Send to Error-根据阶段错误记录处理来处理记录。
    • Overwrite-覆盖现有文件。
    Include Checksum in Events 在整个文件事件记录中包括校验和信息。

    仅在目标端生成事件记录时使用。

    Checksum Algorithm 生成校验和的算法。
  10. 在“Credentials选项卡上,配置以下属性:
    凭据属性 描述
    Project ID 要连接的项目ID。
    Credentials Provider 用于连接的凭据提供者:

    • 默认凭证提供者
    • 服务帐户凭证文件(JSON)
    Credentials File Path (JSON) 使用Google Cloud服务帐户凭据文件时,源端用于连接到Google Cloud Storage的文件的路径。凭据文件必须是JSON文件。

    输入相对于Data Collector资源目录$SDC_RESOURCES的路径,或输入绝对路径。