安装并配置 Openflow Connector for Oracle

备注

此连接器受 Snowflake 连接器条款 的约束。

备注

除标准连接器服务条款外，Openflow Connector for Oracle 还需遵守其他服务条款。有关更多信息，请参阅 Openflow Connector for Oracle 附录。

本主题介绍安装和配置 Openflow Connector for Oracle 连接器的步骤。

作为数据工程师，执行以下任务以安装和配置连接器：

安装连接器

要安装连接器，请以数据工程师身份执行以下操作：

  1. 导航到 Openflow“Overview”页面。在 Featured connectors 部分中，选择 View more connectors。

  2. 在 Openflow 连接器页面上，找到连接器并选择 Add to runtime。

  3. 在 Select runtime 对话框中，从 Available runtimes 下拉列表中选择您的运行时，然后点击 Add。

    备注

    在安装连接器之前，请确保在 Snowflake 中为连接器创建了数据库和架构，用于存储引入的数据。

  4. 使用您的 Snowflake 账户凭据对部署进行身份验证，并在系统提示时选择 Allow，以允许运行时应用程序访问您的 Snowflake 账户。连接器安装过程需要几分钟才能完成。

  5. 使用您的 Snowflake 账户凭据进行运行时身份验证。

此时将显示 Openflow 画布，其中添加了连接器进程组。

配置连接器

要配置连接器，请以数据工程师身份执行以下操作：

  1. 右键点击已添加的运行时，然后选择:ui:Parameters。

  2. 填充所需的参数值。

    有关所需参数值的详细信息，请参阅以下部分：

    • Snowflake 目标参数：选择使用 时默认使用的角色和仓库。用于与 Snowflake 建立连接。

    • Oracle 引入参数：选择使用 时默认使用的角色和仓库。用于指定要复制的表。

    • Oracle 源参数：选择使用 时默认使用的角色和仓库。用于定义从 Oracle 下载的数据的配置。

Snowflake 目标参数

参数

描述

必填

目标数据库

用于永久保存数据的数据库。它必须已经存在于 Snowflake 中。名称区分大小写。对于未加引号的标识符，请以大写形式提供名称。

是

Snowflake 身份验证策略

使用以下方式时：

  • Snowflake Openflow 部署 或 BYOC：使用 SNOWFLAKE_MANAGED_TOKEN。此令牌由 Snowflake 自动管理。BYOC 部署必须预先配置了 :ref:` 运行时角色 <label-deployment_byoc_setup_runtime_role>` 才能使用 SNOWFLAKE_MANAGED_TOKEN。

  • BYOC： 或者，BYOC 可以使用 KEY_PAIR 作为身份验证策略的值。

是

Snowflake 账户标识符

使用以下方式时：

  • 会话令牌身份验证策略：必须为空。

  • KEY_PAIR：Snowflake 账户名称格式为 [organization-name]-[account-name]，数据将永久保存在其中。

是

Snowflake 连接策略

使用 KEY_PAIR 时，请指定连接到 Snowflake 的策略：

  • STANDARD （默认值）：使用标准的公共路由连接到 Snowflake 服务。

  • PRIVATE_CONNECTIVITY：使用与支持的云平台（如 AWS PrivateLink）关联的专用地址进行连接。

仅在使用 BYOC 且配合 KEY_PAIR 时才需要，否则将被忽略。

Snowflake 私钥

使用以下方式时：

  • 会话令牌身份验证策略：必须为空。

  • KEY_PAIR：必须是用于身份验证的 RSA 私钥。

    RSA 密钥必须按照 PKCS8 标准进行格式化，并具有标准的 PEM 头尾标记。请注意，必须定义 Snowflake 私钥文件或 Snowflake 私钥。

否

Snowflake 私钥文件

使用以下方式时：

  • 会话令牌身份验证策略：私钥文件必须为空。

  • KEY_PAIR：上传包含用于向 Snowflake 进行身份验证的 RSA 私钥的文件，该文件应根据 PKCS8 标准格式化，并包含标准的 PEM 页眉和页脚。头标记行以 -----BEGIN PRIVATE 开头。选中 Reference asset 复选框以上传私钥文件。

否

Snowflake 私钥密码

使用以下方式时：

  • 会话令牌身份验证策略：必须为空。

  • KEY_PAIR：提供与 Snowflake 私钥文件关联的密码。

否

Snowflake 角色

使用以下方式时：

  • 会话令牌身份验证策略：使用分配给运行时的 Snowflake 角色，或授予该 Snowflake 角色的子角色。您可以在 Openflow UI 中找到运行时的 Snowflake 角色：展开运行时的 More Options [⋮] 按钮并选择 Set Snowflake role。

  • KEY_PAIR 身份验证策略：使用为您的服务用户配置的有效角色。

是

Snowflake 用户名

使用以下方式时：

  • 会话令牌身份验证策略：必须为空。

  • KEY_PAIR：提供用于连接到 Snowflake 实例的用户名。

是

超大值处理策略

确定连接器在复制期间如何处理超过内部大小限制 (16 MB) 的值。可能的值：

  • **故障表**（默认值）：该表将被标记为永久失败，并停止该表的复制。

  • 设置 Null：在目标表中将该值替换为 NULL。当允许丢弃超过大小限制的数据以防止表复制中断时，可使用此选项。

否

Snowflake 仓库

用于运行查询的 Snowflake 仓库。

是

Oracle 引入参数

参数

描述

包括表名

以逗号分隔的完全限定表路径列表。必须使用完全限定格式指定表：数据库.架构.表名 (DATABASE_NAME.SCHEMA_NAME.TABLE_NAME)。

例如：MYPDB.SALES.CUSTOMERS, MYPDB.SALES.ORDERS

包括表正则表达式

用于匹配表路径的正则表达式，以便自动包含现有表和新表。则表达式模式必须符合由三部分组成的命名约定：DATABASE_NAME.SCHEMA_NAME.TABLE_NAME。

例如：使用 MYPDB\.SALES\..* 匹配 MYPDB 数据库内 SALES 架构中的所有表。

筛选器 JSON

一个 JSON 数组，用于根据正则表达式模式包含特定表的特定列。

合并任务计划 CRON

一个 CRON 表达式，用于定义何时触发从日志表到目标表的合并操作。例如：使用 * * * * * ? 进行连续合并。

对象标识符解析

指定源对象标识符（如架构、表和列名）在 Snowflake 中的存储和查询方式。此设置将决定您是否必须在 SQL 查询中使用双引号。

:emph:` 选项 1：默认，不区分大小写（推荐）。

  • Transformation：所有标识符都将转换为大写。例如：My_Table 变为 MY_TABLE。

  • 查询：SQL 查询不区分大小写，且不需要使用 SQL 双引号。

    例如：SELECT * FROM my_table; 返回的结果与 SELECT * FROM MY_TABLE; 相同。

备注

如果预计数据库对象不包含混合大小写的名称，Snowflake 建议使用此选项。

选项 2：区分大小写。

  • Transformation：保留原始大小写。例如，My_Table 保持为 My_Table。

  • 查询：SQL 查询必须使用双引号，以精确匹配数据库对象的大小写。例如 SELECT * FROM "My_Table";。

重要

连接器引入开始后，请勿更改此设置。在引入开始后更改此设置会破坏现有的引入流程。如果必须更改，请创建一个新的连接器实例。

快照提取策略

确定快照加载的提取策略：

  • SEQUENTIAL_BY_PRIMARY_KEY （默认值）：使用按主键顺序检索的固定大小批次。

  • CONCURRENT_BY_ROWID：将表拆分为受物理行 ID 范围约束的块，并并行检索每个块。

Oracle 源参数

参数

描述

必填

Oracle 连接 URL

到 DB 的数据库连接的 JDBC URL。URL 必须指定包含要复制数据的目标容器（PDB 或 CDB）。例如：jdbc:oracle:thin@<host>:<port>/YOUR_DB_NAME，其中 YOUR_DB_NAME 是您的 PDB 或 CDB 名称。

启用 SSL 后，请使用 TCPS 协议，例如 jdbc:oracle:thin:@tcps://<host>:<tcps_port>/YOUR_DB_NAME。

备注

连接器在单个数据库/容器内工作。请确保 JDBC URL 直接指向包含待复制表的容器。

是

Oracle 用户名

有权访问 XStream 服务器的连接用户的用户名。

是

Oracle 密码

有权访问 XStream 服务器的连接用户的密码。

是

Oracle SSL 模式

控制与 Oracle 数据库连接的 SSL 加密。

  • **DISABLED ** 是默认值：连接时不使用 SSL。

  • VERIFY_CA：使用 SSL 连接。验证服务器证书是否由受信任的证书颁发机构颁发。

  • VERIFY_IDENTITY：使用 SSL 连接。验证 CA 证书，并确保服务器主机名与证书的主题相匹配。

当设置为 VERIFY_CA 或 VERIFY_IDENTITY 时，还必须提供 Oracle Wallet Filename 参数。

是

Oracle Wallet Filename

上传包含 Oracle 自动登录钱包的文件 (cwallet.sso)。该钱包必须包含用于 SSL 连接的受信任服务器证书。

有关创建钱包的信息，请参阅 配置 SSL 连接（可选）。

当 SSL 模式不是 DISABLED 时为必填项。

Oracle 数据库处理器倍增系数

核心处理器许可系数，如 Oracle 处理器核心系数表 (https://www.oracle.com/contracts/docs/processor-core-factor-table-070634.pdf) 中所述。

仅嵌入式许可证需要

Oracle 数据库处理器核心

Oracle 数据库处理器核心数。

仅嵌入式许可证需要

XStream 计费确认

许可协议的确认

仅嵌入式许可证需要

XStream 输出服务器名称

Oracle 中必须已存在的 XStream 服务器的名称。

是

XStream 输出服务器 URL

用于 XStream 的数据库连接的 JDBC URL，必须使用 OCI 驱动程序。例如：jdbc:oracle:oci:@<host>:<port>/SID。

启用 SSL 后，请使用 TCPS 协议，例如 jdbc:oracle:oci:@tcps://<host>:<tcps_port>/SID。

备注

启用 SSL 模式后，连接器会自动将 SSL_SERVER_DN_MATCH 和 MY_WALLET_DIRECTORY 添加到 XStream URL 中。您无需手动添加这些内容。

是

重新启动表复制

处于 FAILED 状态的表（例如，由于缺少主键或不支持的架构更改）不会自动重新启动。如果表进入 FAILED 状态，或者您需要从头开始重新启动复制，请按照以下步骤将该表移除并重新添加到复制中。

备注

如果失败是由源表中的问题（如缺少主键）引起的，请在继续之前先在源数据库中解决该问题。

  1. 从流参数中移除表：在“引入参数”上下文中，从 Included Table Names 中移除该表，或修改 Included Table Regex 使该表不再被匹配。

  2. 验证表是否已移除：

    1. 在 Openflow 运行时画布中，右键点击处理器组并选择 Controller Services。

    2. 在列出控制器服务的表中，找到 Table State Store 行，点击该行右侧的三个垂直点，然后选择 View State。

    重要

    在继续操作之前，您必须等到该表的状态从该列表中完全移除。在此配置更改完成之前，请勿继续。

  3. 清理目标：一旦表的状态显示为已完全移除，请手动在 Snowflake 中 DROP 目标表。请注意，在快照阶段，连接器不会覆盖现有的目标表；如果表仍然存在，复制将再次失败。（可选）如果不再需要日志表和流，也可以将其移除。

  4. 重新添加表：更新 Included Table Names 或 Included Table Regex 参数以再次包含该表。

  5. 验证重启：使用前面给出的说明检查 Table State Store。表的状态应显示为 NEW，然后转换为 SNAPSHOT_REPLICATION，最后变为 INCREMENTAL_REPLICATION。

运行流

  1. 右键点击“飞机”图标并选择 Enable all Controller Services。

  2. 右键点击导入的进程组并选择 Start。连接器开始数据引入。

后续步骤

  • （可选）:doc:设置不使用快照的增量复制 <incremental-replication>。

  • 监控流量。