安装并配置 Openflow Connector for Oracle¶

备注

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

备注

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

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

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

安装连接器¶

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

导航到 Openflow“Overview”页面。在 Featured connectors 部分中，选择 View more connectors。
在 Openflow 连接器页面上，找到连接器并选择 Add to runtime。
在 Select runtime 对话框中，从 Available runtimes 下拉列表中选择您的运行时，然后点击 Add。

备注

在安装连接器之前，请确保在 Snowflake 中为连接器创建了数据库和架构，用于存储引入的数据。
使用您的 Snowflake 账户凭据对部署进行身份验证，并在系统提示时选择 Allow，以允许运行时应用程序访问您的 Snowflake 账户。连接器安装过程需要几分钟才能完成。
使用您的 Snowflake 账户凭据进行运行时身份验证。

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

配置连接器¶

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

右键点击已添加的运行时，然后选择:ui:Parameters。
填充所需的参数值。

有关所需参数值的详细信息，请参阅以下部分：
- Snowflake 目标参数：选择使用时默认使用的角色和仓库。用于与 Snowflake 建立连接。
- Oracle 引入参数：选择使用时默认使用的角色和仓库。用于指定要复制的表。
- Oracle 源参数：选择使用时默认使用的角色和仓库。用于定义从 Oracle 下载的数据的配置。

Snowflake 目标参数¶


参数	描述	必填
目标数据库	永久保存数据的数据库。它必须已经存在于 Snowflake 中。名称区分大小写。对于未加引号的标识符，请以大写形式提供名称。	是
目标模式的设计模式	永久保存数据的目标模式名称模式。如果这些模式不存在，连接器会创建这些模式。您可以使用以下可选变量，自定义每个引入表的模式： `${source.database.name}`：源表的数据库。 `${source.schema.name}`：源表的模式。 `${source.table.name}`：源表的名称。例如，对于限定名称为 `source_db.tenant_a.data` 的表，模式 `prefix_${source.database.name}_${source.schema.name}` 将解析为 `prefix_source_db_tenant_a`。要将所有表引入单个模式中，请提供不含任何变量的模式名称，例如 `destination_schema`。重要连接器开始引入数据后，请勿更改此设置。在引入开始后更改此设置会破坏现有的引入流程。如果必须更改，请创建一个新的连接器实例。	是
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 状态，或者您需要从头开始重新启动复制，请按照以下步骤将该表移除并重新添加到复制中。

备注

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

从流参数中移除表：在“引入参数”上下文中，从 Included Table Names 中移除该表，或修改 Included Table Regex 使该表不再被匹配。
验证表是否已移除：
1. 在 Openflow 运行时画布中，右键点击处理器组并选择 Controller Services。
2. 在列出控制器服务的表中，找到 Table State Store 行，点击该行右侧的三个垂直点，然后选择 View State。
重要

在继续操作之前，您必须等到该表的状态从该列表中完全移除。在此配置更改完成之前，请勿继续。
清理目标：一旦表的状态显示为已完全移除，请手动在 Snowflake 中 DROP 目标表。请注意，在快照阶段，连接器不会覆盖现有的目标表；如果表仍然存在，复制将再次失败。（可选）如果不再需要日志表和流，也可以将其移除。
重新添加表：更新 Included Table Names 或 Included Table Regex 参数以再次包含该表。
验证重启：使用前面给出的说明检查 Table State Store。表的状态应显示为 NEW，然后转换为 SNAPSHOT_REPLICATION，最后变为 INCREMENTAL_REPLICATION。

复制表中列的子集¶

连接器可以将每张表复制的数据筛选到已配置列的子集。无论排除情况如何，始终包含主键列。

要应用列筛选器，请将引入参数上下文中的 Column Filter JSON 参数设置为一个由筛选对象组成的 JSON 数组，其中每个表分别对应一个筛选器对象。

可以按名称或正则表达式模式包含或排除列。您可以对每张表应用一个条件，也可以合并多个条件，排除项的优先级始终高于包含项。

语法¶

数组中的每个对象都标识一个表，并指定要包含或排除的列。由于此连接器使用由三部分组成的完全限定名称（数据库、架构和表），因此每个对象除了架构和表字段外，还可以包含 database 或 databasePattern 字段。

[
    {
        "database": "<database>" | "databasePattern": "<regex>",
        "schema": "<schema>" | "schemaPattern": "<regex>",
        "table": "<table>" | "tablePattern": "<regex>",
        "included": ["<column>", "<column>"],
        "excluded": ["<column>", "<column>"],
        "includedPattern": "<regex>",
        "excludedPattern": "<regex>"
    }
]

以下规则适用：

使用 database、schema 和 table 进行精确名称匹配，或使用 databasePattern、schemaPattern 和 tablePattern 进行正则匹配。不能在同一对象中同时使用字段及其模式变体（例如，schema 和 schemaPattern 不能同时出现）。
必须至少提供 included、excluded、includedPattern 或 excludedPattern 之一。
当同时指定了包含和排除的筛选器时，排除项优先。
当多个筛选器与同一个表匹配时，将使用最后一个匹配的筛选器，精确匹配优先于基于模式的筛选器。
该值可以是对象数组，用于将不同的筛选器应用于不同的表。

示例¶

按名称包含特定列：

[
    {
        "database": "my_db",
        "schema": "dbo",
        "table": "orders",
        "included": ["account_id", "status", "created_at"]
    }
]

按名称排除特定列：

[
    {
        "database": "my_db",
        "schema": "dbo",
        "table": "orders",
        "excluded": ["internal_note", "debug_flag"]
    }
]

将包含模式与特定排除项相结合（例如，包含除 admin_email 以外的所有电子邮件列）：

[
    {
        "database": "my_db",
        "schema": "dbo",
        "table": "contacts",
        "includedPattern": ".*_email",
        "excluded": ["admin_email"]
    }
]

将数据库模式与确切的架构和表名称混合，以跨数据库应用筛选器：

[
    {
        "databasePattern": "prod_.*",
        "schema": "dbo",
        "table": "customers",
        "excluded": ["internal_note"]
    }
]

传递多个筛选器对象，以将不同的规则应用于不同的表：

[
    {"database": "my_db", "schema": "dbo", "table": "orders", "included": ["account_id", "status"]},
    {"database": "my_db", "schema": "dbo", "table": "customers", "excludedPattern": ".*_internal"}
]

运行流¶

右键点击“飞机”图标并选择 Enable all Controller Services。
右键点击导入的进程组并选择 Start。连接器开始数据引入。

后续步骤¶

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