安装¶
要安装 Tagetik Data Loader，只需将文件 TagetikDataLoader
Tagetik Data Loader 版本 9 使用最新版本的 Apache Karaf 容器 4.4.7
其中包含两个目录：
- apache-karaf-<version>：包含 Apache Karaf 容器、Tagetik Data Loader jar 和默认 JDBC 驱动程序。 该目录可重命名为 apache-karaf。
- tgk-configuration-<version>：包含 Karaf 配置（/etc）的外置化，Tagetik Data Loader 的配置文件也位于其中。
配置¶
Tagetik Data Loader（TDL）需要配置一组参数，以使其正确且完整地运行：
- Java Home 配置
- 定义其他 Karaf 设置（内存等）
- 定义 Karaf 配置
- 常规配置以及与 CCH Tagetik 的连接配置
- 身份验证配置
- 日志配置
- 用于访问数据库的数据源配置
- 用于访问文件系统目录的路径配置
Java Home 配置¶
要配置 Java Home，必须访问位于
要使用的 JDK 版本为 17.0.12。Tagetik Data Loader 9 已使用 JDK17.0.12 构建并测试：原则上不反对升级到后续补丁，因为它们通常包含不会破坏兼容性的修复。但是，应注意 Tagetik Data Loader 不会预先针对 17.0.12 之后的每个 JDK 补丁进行测试。仅在响应特定请求或 JDK 更新后发现问题报告时才会进行此类测试。
例如 linux： export JAVA_HOME="/usr/lib/jvm/openjdk-17.0.12"
例如 windows set JAVA_HOME=C:\Progra~1\Java\openjdk-17.0.12
已测试并支持的 JDK 列表：
- Amazon Corrected 17.0.12
- Microsoft 17.0.12
- Oracle 17.0.12
- SapMachine 17.0.12
- IBM Semeru 17.0.12
- Liberica 17.0.12
- Temurin 17.0.12
定义其他 Java 和 Karaf 设置¶
要定义其他 Java 和 Karaf 设置，必须访问位于
例如 linux：
export JAVA_MIN_MEM=256M # JVM 的最小内存
export JAVA_MAX_MEM=1024M # JVM 的最大内存
export JAVA_PERM_MEM=128M # JVM 的最小永久内存
export JAVA_MAX_PERM_MEM=256M # JVM 的最大内存
例如 windows
set JAVA_MIN_MEM=256M # JVM 的最小内存
set JAVA_MAX_MEM=1024M # JVM 的最大内存
set JAVA_PERM_MEM=128M # JVM 的最小永久内存
set JAVA_MAX_PERM_MEM=256M # JVM 的最大内存
Karaf 配置定义¶
建议将 Karaf 配置从
例如 linux： export KARAF_ETC="/home/user/TagetikDataLoader/tgk-configuration"
例如 windows set KARAF_ETC=C:\Progra~1\TagetikDataLoader\tgk-configuration
常规设置以及与 CCH Tagetik 的连接¶
要配置 TDL 与 CCH Tagetik 的连接以及更改与其功能相关的某些参数，必须访问 Karaf 配置目录中的 tgk.properties.cfg 文件。
要配置的参数为：
- tgk.agent.polling.interval。指示 TDL 以什么间隔（以秒为单位）验证要接管的交易请求。建议不要设置低于 30 秒的值
- tgk.agent.tmpfolder。指示为 TDL 保留的用于保存数据操作所用临时资源的路径。如果未指定该参数，或指定的文件夹不存在，则 Tagetik Data Loader 使用 Karaf 的临时文件夹
/data/tmp 作为备用文件夹。强烈建议指定此参数，以避免依赖 Karaf 容器内的临时文件夹。 - tgk.agent.write.db.batchsize。指示在写入时同时发送到数据库以执行的语句数（默认 10000）
- tgk.agent.read.db.fetchsize。指示在读取阶段从数据库中同时检索的记录数（如果未指定，将使用所用 jdbc 驱动程序指定的默认值）。 注意：此参数的理想值可能因数据库供应商和所执行查询的复杂性而有很大差异。
- tgk.endpoint.address。CCH Tagetik 端点 URL（例如 https://alpha.saastagetik.com/prod）
如果安全数据传输处于活动状态，即 Tagetik Endpoint URL 的协议为 https，在缺少特定参数化的情况下，TDL 将使用正在使用的默认 JDK 信任库。如果希望指定自定义服务器证书，可以通过以下参数进行：
- tgk.server.ks.password。生成服务器端证书时选择的密码。必须按照 敏感数据的安全与加密 中指定的语法编写
- tgk.server.ks.path。服务器端证书的完整路径
如果 TDL 与 CCH Tagetik 之间的通信由代理服务器管理，还可以配置以下内容：
- tgk.proxy.server。指示代理服务器的 IP
- tgk.proxy.port。指示代理服务器端口
- tgk.proxy.user。指示访问代理服务器的用户
- tgk.proxy.password。指示上一个属性中定义的用户可用于访问代理服务器的密码。必须按照 敏感数据的安全与加密 中指定的语法编写
可以通过 PGP 算法启用 TDL 与 CCH Tagetik 之间交换数据的有效载荷加密。
为此，需要配置：
- tgk.pgp.publickey 指示包含公钥的文件的完整路径
- tgk.pgp.privatekey 指示包含私钥的文件的完整路径
- tgk.pgp. passphrase 指示使用私钥的密码短语。必须按照 敏感数据的安全与加密 中指定的语法编写
如果 Endpoint 仅用于读取数据，则只需配置公钥；如果仅用于写入数据，则只需配置密钥和密码短语。 如果 TDL 用于写入数据，则只需配置 TDL 上的私钥和密码短语以及 CCH Tagetik 上定义的 Endpoint 上的公钥。
还可以指定更多技术属性来指导 Tagetik Data Loader 的操作，这在分析不正确行为时特别有用。
- tgk.debug.polling.log.disabled：此布尔属性设置为 'true' 时，将禁用对未触发 TDL 操作的成功轮询请求的日志记录。失败的轮询请求（无论错误如何）以及所有其他 TDL 操作将继续被记录。因此，启用此属性会使 tagetik.log 文件变得不那么冗长。默认值为 'false'。
- tgk.debug.tmp.cleanup.disabled：此布尔属性设置为 'true' 时，将禁用对某些 TDL 操作生成的临时文件的自动删除。此选项是为诊断目的而引入的，允许分析有关失败操作生成的文件格式或内容的问题。默认值为 'false'。
警告：必须谨慎使用此属性，因为启用它可能会导致保留大量临时文件，从而可能造成相当大的磁盘空间占用。
示例 1 *（未指定自定义服务器证书的 HTTPS 安全传输）***
tgk.agent.polling.interval=30
tgk.agent.tmpfolder=/home/user/TagetikDataLoader/tgk-configuration/tmp/
tgk.agent.write.db.batchsize=10000
tgk.agent.read.db.fetchsize=
tgk.endpoint.address=https://tagetik.installation.url.com/tagetikcpm
tgk.server.ks.path=
tgk.server.ks.password=
示例 2 *（指定自定义服务器证书的 HTTPS 安全传输）***
tgk.agent.polling.interval=30
tgk.agent.tmpfolder=/home/user/TagetikDataLoader/tgk-configuration/tmp/
tgk.agent.write.db.batchsize=10000
tgk.agent.read.db.fetchsize=
tgk.endpoint.address=https://tagetik.installation.url.com/tagetikcpm
tgk.server.ks.path=/home/TDL/certificates/server.truststore
tgk.server.ks.password={TGK_ENCRYPT}server_side_certificate_password{TGK_ENCRYPT}
示例 3（HTTP 传输）
tgk.agent.polling.interval=30
tgk.agent.tmpfolder=/home/user/TagetikDataLoader/tgk-configuration/tmp/
tgk.agent.write.db.batchsize=10000
tgk.agent.read.db.fetchsize=
tgk.endpoint.address=http://tagetik.installation.url.com/tagetikcpm
示例 4（使用 PGP 传输）
tgk.agent.polling.interval=30
tgk.agent.tmpfolder=/home/user/TagetikDataLoader/tgk-configuration/tmp/
tgk.agent.write.db.batchsize=10000
tgk.agent.read.db.fetchsize=
tgk.endpoint.address=http://tagetik.installation.url.com/tagetikcpm
tgk.pgp.publickey=/home/user/TagetikDataLoade/publickey.asc
tgk.pgp.privatekey=/home/user/TagetikDataLoade/privatekey.asc
tgk.pgp.passphrase={TGK_ENCRYPT}123_pippo{TGK_ENCRYPT}
身份验证配置¶
要启用 TDL 与 CCH Tagetik 之间的通信，必须定义身份验证参数。它们位于 Karaf 配置目录中的 tgk.agent.cfg 文件中。
参数如下：
- tgk.agent.id。与 TDL 实例关联的唯一 ID。它在 Karaf 首次启动时自动生成。
- tgk.agent.secret。用于在 CCH Tagetik 上对 TDL 进行身份验证的 SecretKey。必须在 Karaf 首次启动后、ID 自动生成后定义，并且必须使用 敏感数据的安全与加密 中指定的语法定义
使用这两个参数，可以在 CCH Tagetik 上注册 TDL 并在每次请求时对其进行身份验证。
日志配置¶
TDL 日志系统不过是 Apache Karaf 日志系统的自定义。日志配置位于 Karaf 配置目录中的 org.ops4j.pax.logging.cfg 文件中，是一个标准的 Log4j 配置文件。
此文件包含以下带有指定值的部分：
Tagetik agent appender¶
log4j2.logger.tagetik.name = com.tagetik.cpm
log4j2.logger.tagetik.level=INFO
log4j2.logger.tagetik.additivity=false
log4j2.logger.tagetik.appenderRef.TagetikRollingFile.ref = TagetikRollingFile
log4j2.appender.tagetik.type = RollingRandomAccessFile
log4j2.appender.tagetik.name = TagetikRollingFile
log4j2.appender.tagetik.fileName = ${karaf.data}/log/tagetik.log
log4j2.appender.tagetik.filePattern = ${karaf.data}/log/tagetik.log.%i
log4j2.appender.tagetik.append = true
log4j2.appender.tagetik.layout.type = PatternLayout
log4j2.appender.tagetik.layout.pattern = ${log4j2.pattern}
log4j2.appender.tagetik.policies.type = Policies
log4j2.appender.tagetik.policies.size.type = SizeBasedTriggeringPolicy
log4j2.appender.tagetik.policies.size.size = 16MB
有关各种选项和要分配的值的含义，请参阅 Log4j 规范。
日志文件默认保存在
基于上述默认设置，TDL 日志文件名为 tagetik.log，并按日生成。此外，每天前一天生成的文件会通过添加由生成日期组成的后缀来重命名。
数据源配置¶
如果需要数据库操作，例如：
- 读取要传输到 CCH Tagetik 的数据
- 写入从 CCH Tagetik 提取的数据
TDL 要求在 Karaf 配置目录中创建并配置 tgk.datasource-
Karaf 配置文件夹（tgk-configuration）还包含 Tagetik Data Loader 官方支持的供应商模板。
对于使用 基本身份验证 的身份验证：
- SqlServer（JTDS 驱动程序）：_tgk.datasource-jtds_template.cfg
- SqlServer（Microsoft 驱动程序）：_tgk.datasource-microsoft_template.cfg
- Oracle：_tgk.datasource-oracle_template.cfg
- PostgreSQL：_tgk.datasource-postgresql_template.cfg
- SAP Hana：_tgk.datasource-hana_template.cfg
- IBM DB2：_tgk.datasource-db2_template.cfg
- Netsuite：_tgk.datasource-netsuite_template.cfg
- Snowflake：_tgk.datasource-snowflake-basicAuth_template.cfg
对于 Snowflake 供应商，身份验证还通过以下方式管理：
- Key Pair：_tgk.datasource-snowflake-keyPair_template.cfg
- OAuth2.0：_tgk.datasource-snowflake-oAuth_template.cfg
警告：关于使用 Key Pair 进行身份验证，请参阅 Snowflake 文档以了解证书生成和管理。
关于 OAuth2.0，仅接受授权类型 'client credentials'。
有关两种身份验证类型在 Snowflake 侧的配置和更多详细信息，请参阅 Snowflake 官方文档
数据源的密码类型字段（基本身份验证的 'password'，Snowflake 身份验证的 'private_key_pwd' 和 'oauthClientSecret'）必须（在定义和编辑时）按照 敏感数据的安全与加密 中指定的语法输入
添加自定义数据源¶
通过 Karaf 命令行中的 service:list DataSourceFactory 命令，可以显示已安装的 JDBC 驱动程序。
要添加新的 JDBC 驱动程序，需要：
- 将 [driver_name].jar 复制到
/lib/endorsed 文件夹中 - 从 Karaf 命令行运行 install -s wrap:file:./lib/endorsed/[driver_name].jar 命令
- 将与新数据源相关的 .cfg 文件添加到 Karaf 配置目录中（如上述文件）
- 重新启动 Karaf
同一供应商的两个 JDBC 驱动程序同时存在会导致运行时问题。如果需要安装新的 JDBC 驱动程序（例如：更高版本），则必须卸载先前的驱动程序。
路径配置¶
如果需要对文件进行操作，例如：
- 将文件传输到 CCH Tagetik
- 写入由 CCH Tagetik 生成的文件
TDL 要求在 Karaf 配置目录中创建并配置 tgk.repository.cfg 文件。
在其中，可以配置逻辑路径名称与实际绝对路径之间的映射列表。
语法是 *.properties 文件的典型语法，因此：
敏感数据的安全与加密¶
对于密钥库和数据源密码，存在一种加密值的机制。
要定义密码的值，必须使用以下语法：
保存配置文件后，Tagetik Data Loader 将自动加密该属性的值并在同一配置文件中替换它。
TDL 只能处理包含"ASCII 可打印字符"的密码，即 ASCII 字符 32 到 126，但以下例外：
- 字符 '$'（ASCII 36）不能用作密码的最后一个字符
- 字符 '\'（ASCII 92）不能用于密码中。
启动 Karaf¶
完成安装和配置后，可通过运行
作为操作系统服务启动¶
也可以通过从 Karaf 命令行执行命令 wrapper:install --name "TDL" --display "TDL" --description "TDL"，然后按以下方式将 Karaf 作为操作系统服务启动：
- Windows：在命令提示符中运行
/bin 目录中的 TDL-service.bat install 命令（或 karaf-service.bat install） - Linux：按照运行 wrapper:install 命令后显示的说明操作。