CData 端口

Version 23.4.8843


CData 端口


CData 端口利用 CData Software 的行业标准连接。CData 端口直接与 CData ADO.NET 和 JDBC 驱动程序连接,从而实现与数百个云以及本地应用程序,数据库等的连接。

概述

CData 端口使用 CData 驱动程序将数据库操作转换为对特定目标数据源的 API 调用。因此云应用程序数据可当作一组虚拟表和存储过程。

必须为每个 CData 端口配置适当的 CData 驱动程序,才可以连接到目标数据源。建立连接后,端口支持创建输入映射输出映射,这些映射将确定用于与数据源的虚拟表进行交互的 XML 结构。

生成输入和输出映射后,XML 输入文件将自动转换为 API 调用并插入数据,并且通过 API 调用从数据源检索的数据将作为 XML 文件输出。

要开始使用 CData 端口,必须安装目标数据源的 CData 驱动程序。

安装 CData Driver

必须先为适当的数据源安装 ADO.NET 提供程序( Windows 版)或 JDBC 驱动程序( Java 版),然后才能与数据源建立连接。

ADO.NET

下载并运行 ADO.NET 提供程序的 CData 安装程序,CData 端口会识别提供程序,使其在端口下拉框设置中可选。

  • CData数据源列表中找到所需的数据源。单击数据源可以显示该数据源的页面。

  • 找到列出可用驱动程序类型的顶部工具栏,然后点击 ADO.NET

  • 点击下载按钮。

  • 下载 30 天试用版或完整的驱动程序(需要购买的许可证)。请通过 sales@kasoftware.cn 与知行软件团队联系,以获取驱动程序许可。

  • 运行下载的安装程序。

  • 重新启动知行之桥服务器,让 CData 端口可以检测到新的提供程序。

JDBC

为了使 CData 端口能够识别 JDBC 驱动程序,必须将其安装并放置在托管知行之桥的 Java 服务器的 lib 文件夹中。

  • CData数据源列表中找到所需的数据源。单击数据源可以显示该数据源的页面。

  • 找到列出可用驱动程序类型的顶部工具栏,然后单击 JDBC

  • 点击下载按钮。

  • 下载 30 天试用版或完整的驱动程序(需要购买的许可证)。请通过 sales@kasoftware.cn 与知行软件团队联系,以获取驱动程序许可。

  • 从下载的文件中提取并运行 setup.jar 文件。

  • 导航到驱动程序安装目录,并在 /lib/ 文件夹中找到驱动程序 .jar 文件和 .lic(许可)文件。

  • 将驱动程序 .jar 和 .lic 复制到托管知行之桥的 Java 服务器的 /lib/ 文件夹中。

  • 重新启动知行之桥服务器,让 CData 端口可以检测新驱动程序。

建立连接

提供适当的驱动程序之后,必须进行适当的连接设置才能访问应用程序的 API。端口将自动使用与所选云应用程序数据源相关的连接设置来调整设置选项卡。

认证

身份认证凭据和目标数据源有关。凭证可以直接从云应用程序中获取,然后将其包含在端口进行的 API 调用中。

OAuth 认证

某些数据源需要 OAuth 身份验证,必须使用端口设置面板中的连接按钮启动。此按钮会将浏览器定向到数据源的身份验证门户,在此必须授予 CData 驱动程序访问数据源的权限。知行之桥无法看到或存储在此门户中输入的凭证(该门户返回表示凭证的身份认证令牌,而不会暴露它们)。

知行之桥会存储使 OAuth 身份认证保持最新状态所需的 OAuth 令牌和刷新令牌,因此仅在首次连接到数据源时才需要通过 OAuth 门户提供凭据。

输入映射

CData 端口代表存储在目标云应用程序中的数据,就像数据存储在关系数据库中的表中一样。连接到数据源后,端口将在数据源中扫描可用的虚拟表和存储过程。输入映射表示对这些虚拟表之一的 INSERT/UPDATE。

输入映射格式为 XML,由 CData 端口处理与输入映射的 XML 结构匹配的文件,自动将文件转换为针对目标数据源的相应 INSERT 或 UPDATE 查询。

输入映射为 XML 部分中详细介绍了将 XML 转换为数据库查询的过程。从概念上讲,端口只是从 XML 元素中读取值,并在执行 INSERT/UPDATE 语句时使用。

创建输入映射

单击“添加映射”按钮(+)创建新的映射。从数据源中可用虚拟表的列表中选择目标表/视图,以打开映射编辑器面板。在映射编辑器中,选择应包含在 INSERT/UPDATE 中的虚拟表列。对于简单的 INSERT,这就是生成映射所需的全部。

创建输入映射后,可以通过单击映射名称旁边的“代码”(</>)按钮来查看其 XML 表示形式。

UPSERT

UPSERT 设置控制端口如何决定是 INSERT 还是 UPDATE。最常见的情况是将 UPSERT by: 设置为表的主键。使用此配置,端口将从输入的 XML 中读取主键值,查询数据库以查看该键是否已存在于表中,如果存在则更新记录,如果不存在则插入新记录。 UPSERT by: 可以设置为主键以外的列,但这可能会导致从数据库返回多条记录。在这种情况下,端口更新返回的第一条记录。

如果 执行此查询以选择 UPSERT 键: 设置为 SELECT 查询,则端口会将此查询的结果与输入 XML 进行比较,以确定是 INSERT 还是 UDPATE。当目标表的主键在输入 XML 中不可用,但可以通过引用另一列获取时,这将会很有帮助。

例如,假设需要使用主键 CustomerID 来执行 UPSERT 逻辑。输入 XML 没有 CustomerID,但它有唯一标识每个客户的 CustomerPhoneNumberCustomerIDUPSERT query可以设置为以下内容:

SELECT CustomerID FROM Customers WHERE CustomerPhoneNumber = @CustomerPhoneNumber

上述查询中的“@”语法表示查询值应从输入 XML 中的 CustomerPhoneNumber 元素读取。

端口将针对数据库运行此查询,如果已存在具有相同 CustomerPhoneNumber 的记录,则返回 CustomerID 值。然后,此 CustomerID 将用于更新记录(否则将插入新记录)。

INSERT

如果在输入映射中禁用了 UPSERT,则端口将自动将查询操作设置为 INSERT。端口将尝试为每个输入 XML 文件插入新记录,而不会查询数据源以查看记录是否已存在。

LOOKUP

某些列具有可用的 LOOKUP 选项。端口检测到这些列与数据库中的另一个表具有外键关系。如果启用了 LOOKUP,端口将在 INSERT 之前查询此外部表,并在 INSERT 中使用此返回值。 LOOKUP by: 字段决定将用于查询外部表的列。

例如,假设将采购订单 (PO) 插入到数据库中,其中“PO”表中的字段之一是内部的 CustomerID。假设输入 XML 将有一个 CustomerName 元素,但没有客户的内部 ID,而数据库中的另一个表“Customers”同时具有名称和 ID,因此可根据名称查找 ID 值。端口将识别 ‘PO’ 表的 CustomerID 列是外键,并为该列启用 LOOKUP。将 LOOKUP by: 设置为 CustomerName 指示端口使用如下语句查询“Customers”表:

SELECT CustomerID FROM Customers WHERE CustomerName = @CustomerName

上述查询中的“@”语法表示应查询值应从输入 XML 中的 CustomerName 元素中读取。

使用此配置,端口将首先从“Customers”中检索 CustomerID,然后在插入“PO”表时使用该值。

输入映射为 XML

输入映射用 XML 表示,具有以下结构:父元素表示要插入的虚拟表名称,子元素对应于目标表中的列名称。输入映射在 XML 的元素和数据源列之间建立连接,以便端口可以从输入的 XML 文件中读取值并在 INSERT 或 UPDATE 查询中使用。

以下 XML 是 “Students” 表的输入映射示例:

<Items>
    <Students action="insert">
        <StudentID key="true" />
        <Name/>
        <Grade type="int"/>
        <GPA/>
    </Students>
</Items>

在以上示例中, StudentIDNameGrade,和 GPA 是 “Students” 表中的列。当端口处理与该结构匹配的 XML 文件时,将自动将 XML 中的值插入 “Students” 表。以下是上述映射的示例 XML 输入文件:

<Items>
    <Students>
        <StudentID>12554</StudentID>
        <Name>Ferris Bueller</Name>
        <Year>11</Year>
        <GPA>1.8</GPA>
    </Students>
    <Students>
        <StudentID>12921</StudentID>
        <Name>Hermione Granger</Name>
        <Year>9</Year>
        <GPA>4.0</GPA>
    </Students>
</Items>

当端口处理上述输入文件时,将在 “Students” 表中插入或更新两个记录,每行是一个 Students

批量输入

CData 端口支持批处理,以提高插入大量数据时的性能。批处理通过是事务容量批处理容量这两个字段来设置的。当这些字段设置为正整数时,端口将在单次操作(批处理)中插入 [BatchInputSize]记录,并在单个连接(事务处理)中插入 [TransactionSize] 记录。

XML 输入文件可以包含比单个事务大小更多的记录,在这种情况下,端口将在多个事务中插入数据。

如果在批量插入过程中发生错误,端口将回滚事务并在失败的事务中缓存第一条记录的索引。重试输入文件时,只要缓存索引后的记录才会被插入到数据源中。

更新操作

默认情况下,输入映射将使用 INSERT 或 UPSERT 作为查询操作。与输入映射关联的操作在 XML 中显示为 table_name 元素的 “action” 属性,例如:

<Students action="insert">

当操作设置为 UPDATE 时,某些云应用程序数据源支持更好的性能。UPDATE 操作假定插入到数据源中的数据与已经存在的记录相关联。如果是这样,则可能希望尝试将 “action” 属性设置为 UPDATE,以尝试利用更好的后端性能:

<Students action="update">

请注意,Amazon Dynamo DB 数据源是一种特殊情况,其中后端数据处理包括 UPSERT 逻辑(换句话说,对不存在的记录的 UPDATE 调用将导致创建新记录)。当将数据插入 Amazon Dynamo DB 时,建议将 “action” 属性设置为 UPDATE,以更好的利用后端性能。

插入子表

输入映射支持通过单个映射插入到多个虚拟表中。当创建具有多个表的输入映射时,这些表之间应具有外键关系,即某个表是另一个表的子表。否则,请使用多个输入映射插入到不通过外键相关的表中。

要插入子表中,请首先创建一个以父表为目标的输入映射。然后,使用左上角的+添加按钮从输入映射编辑器中添加子表。从列表中选择适当的表,设计器将自动填充表的层次结构。选择子表中应包含在 “输入映射” 中的列。

REF

子表中的某些列将带有蓝色的 “REF” 标记,端口已检测到这些列对应于父表中的主键。在插入到父表之后,插入到子表之前,端口将在父表中查询刚插入的记录的主键。然后,端口将该值插入子表中。

当父表的主键由数据库生成时(例如 AUTOINCREMENT 键),这很有用。在这种情况下,此列不会作为输入 XML 传入,是端口直到将记录插入到父表中之后才知道该列的值。

在输入映射 XML 中, “ref” 属性表示一列可以被稍后引用,或者该列的值应从映射中的另一列读取。为了引用数据库生成的列的值(例如 AUTOINCREMENT 主键),列元素应包含一个 “ref” 属性,设置为保留值 LAST_INSERT_ID

<film action="upsert">
    <film_id key="true" upsert="film_id" ref="@@LAST_INSERT_ID" />

这表明 film_id 值将在插入后检索,并且可以稍后在映射中引用(通常在子表中)。要在以后引用此值,请将 “ref” 元素设置为 AUTOINCREMENT 列的名称:

<film_id key="true" ref="@film_id" />

在上面的示例中,film_id 是父表中主键的名称,也是子表中列的名称。“ref” 语法指示端口在插入后从父表中检索 film_id,并将该检索到的值用作子表中的 film_id 列。

LOOKUP

子表的 LOOKUP 逻辑与父表相同。有关更多详细信息,请参见创建输入映射中的 LOOKUP 部分。

子表 XML

插入父表和子表时,输入映射 XML 结构将是多层的。以下 XML 是两个由外键关联的表的输入映射示例:

<film action="upsert">
    <film_id key="true" upsert="film_id" ref="@@LAST_INSERT_ID" />
    <description />
    <language_id />
    <rating />
    <release_year type="date" />
    <title />
    <film_actor>
        <actor_id key="true" />
        <film_id key="true" ref="@film_id" />
        <last_update type="datetime" />
    </film_actor>
</film>

在上面的示例中,“film” 是父表,“film_actor” 是子表。film_id 列是 “film” 表的主键,是 “film_actor” 表中的外键。当数据库端口处理与该结构匹配的输入 XML 文件时,它将更新 “film” 和 “film_actor” 表,并确保链接两个记录的键相同。

输出映射

CData 端口代表存储在目标云应用程序中的数据,就像该数据存储在关系数据库中的表中一样。连接到数据源后,端口将在数据源中扫描可用的虚拟表和存储过程。输出映射表示从这些虚拟表进行 SELECT(查询)。

输出映射用 XML 表示,当 CData 端口从目标数据源中读取数据时,该数据作为 XML 文件输出。这些输出文件的结构和输出映射一致。将数据库响应转换为 XML 的过程在输入映射为 XML 部分进行了详细说明。

创建输出映射

单击“添加映射”按钮(+)创建新的映射。从数据库中可用表的列表中选择目标表/视图,以打开映射编辑器面板。在映射编辑器中,选择应在 SELECT 语句中返回的表列。对于简单的 SELECT,这就是生成映射所需的全部。

创建输入映射后,可以通过单击映射名称旁边的“执行”按钮(黑色播放按钮)来执行它代表的查询。另外,可以通过单击映射名称旁边的“代码”按钮(</>)来查看映射的 XML 表示形式。

输出过滤

映射编辑器包括一个“过滤器”面板,用于定义限制数据库返回的记录的规则。每个规则对应于结果 SELECT 查询中的 WHERE 语句,并将指定的列与指定的值进行比较; 仅具有匹配的列值的记录将被获取。

AND 和 OR 逻辑运算符组合在一起组成规则,并且在应用许多规则时,可以将规则分组在一起以保留操作顺序。

输出映射为XML

输出映射用 XML 表示,具有以下结构:父元素标识要从中进行 SELECT 的表,每个子元素对应于目标表中的一列。输出映射在数据库列和 XML 元素之间建立连接,以便端口可以从数据库结果中读取值并生成 XML 文档。

以下 XML 是 “Students” 表的输出映射示例:

<Items>
    <Students selectQuery="SELECT * FROM `Students` WHERE `GPA` = 4.0">
        <StudentID key="true" />
        <Name/>
        <Grade type="int"/>
        <GPA/>
    </Students>
</Items>

在以上示例中,StudentID, Name, Grade, 和 GPA 是 “Students” 表中的列。执行输出映射后,端口将运行指定的 selectQuery 并为返回的每个记录生成一个 XML 文档。以下是上述映射的示例 XML 输出文件:

<Items>
    <Students>
        <StudentID>12921</StudentID>
        <Name>Hermione Granger</Name>
        <Year>9</Year>
        <GPA>4.0</GPA>
    </Students>
</Items>

批量输出

当查询输出时,端口可以配置为支持将记录一起批量输出到单个文档中。 最大记录数 设置可用于控制单个消息中应包含多少条记录,批处理大小 设置可用于指示单个批处理组中应包含多少个批处理消息。

请注意,如果在 SELECT 期间发生错误并且启用 batchResults,则可能更难确定由于该错误未返回的记录。

重写SELECT查询

输出映射XML显示将针对目标数据库运行的 SELECT 查询。端口基于输出映射中的设置创建此查询,但是如果需要对查询进行更详细的控制,则可以手动覆盖该查询。

只需编辑与数据库表共享名称的元素的 “selectQuery” 属性,并将其设置为任意 SELECT 查询。

只处理新添加或变更记录

可以将输出映射配置为仅检索最近更新或添加的记录。端口可以使用两种方法来检测哪些记录是新记录或已修改记录。

第一种方法需要一个 DateTime 列,该列表示记录的最后修改时间;第二种方法需要一个列,该列显式存储一个值,该值表示是否应处理记录。

使用最后修改时间

在“映射编辑器”中,展开面板底部的高级设置。如果检测到 DateTime 列,则该选项可用于只处理新添加或变更记录。将此设置为适当的 DateTime 列,该列表示记录的最后修改时间。

使用自定义列

可以将输出映射配置为更新表中的列,获取从数据库中成功提取的记录。可以将其与过滤器规则结合使用,该过滤器规则仅 SELECT 尚未被获取的记录(或应再次获取)。

要在处理后启用列更新,请展开映射编辑器底部的高级设置。启用只处理新添加或变更记录,然后指定应更新哪一列以及应在此列中更新的值。

例如,输出映射可以配置为在提取记录后将 Processed 列更新为 “1”。然后,可以应用筛选规则,该规则将记录限制为仅 Processed 不等于 1

在此示例中,当端口处理输出模板时,它将基于模板创建 SELECT 语句。该模板将执行 “SELECT Id, AccountId, Amount FROM INVOICE”,并基于该模板为结果集中的每个记录创建一个 XML 文件,并将这些文件放在此端口的 Output 文件夹中。

多表查询

输出映射支持使用单个映射查询多个表。当创建具有多个表的输出映射时,这些表之间应具有外键关系,即一个表是另一表的子表。否则,请使用多个输出映射,从无外键关联的表中进行选择。

要查询子表,首先创建针对父表的输出映射。然后,使用左上角的+添加按钮从输出映射编辑器中添加子表。从表列表中选择适当的表,设计器将自动填充表的层次结构。选择子表中应包含在输出映射中的列。

接下来,应该将 WHERE 查询应用于子表映射,用来反映与父表的外键关系。

主从外键关系

通常,从父表和子表中进行 SELECT 时,仅当外键与父表中的主键匹配时,才会从子表中提取记录。

例如,假设一个输出映射从父表 “PurchaseOrders” 和子表 “PurchaseOrderLineItems” 中提取采购订单数据。从 “PurchaseOrders” 中提取的每个记录(订单)也应提取与该订单关联的订单行。这两个表通过某一列关联,例如,PONumber 列是 “PurchaseOrders” 表的主键,也是 “PurchaseOrdersLineItems” 表外键。仅当订单项的 PONumber 与从父表中提取的订单的 PONumber 相匹配时,才应从子表中提取订单项记录。

要在知行之桥的输出映射中建立此关系,请将新的“过滤器”添加到子表映射中,并进行如下配置:

  • 在第一个(左侧)下拉列表中,选择子表的列,该列是父表的外键。在上面的示例中,这将是 “PurchaseOrderLineItems” 表的 PONumber 列。
  • 在中间(运算符)下拉列表中,选择 “equal”
  • 在最后一个(右侧)输入框中,首先使用右侧的下拉箭头选择 “REF”。之后,输入框应包含$前缀,表明它正在引用父表中的列
  • 使用最后一个(右侧)下拉列表选择应与子表的外键匹配的父表列。在上面的示例中,这将是 “PurchaseOrders” 表的 PONumber

主从输出映射 XML

包含父表和子表的输出映射的 XML 具有层次结构,以反映父子关系。父表的 SELECT 查询和子表的 SELECT 查询都将包含在 XML 中:

<PuchaseOrders selectQuery="SELECT * FROM `PurchaseOrders` ">
  <PONumber key="true"/>
  <AccountId/>
  <Amount/>
  <AppliedAmount/>
  <Balance/>
  <BillingCity/>
  <BillingCountry/>
  <BillingLine1/>
  <BillingPostalCode/>
  <BillingState/>
  <InvoiceLineItem selectQuery="SELECT * FROM `PurchaseOrderLineItems` WHERE `PONumber` = ${PONumber}">
    <Id key="true"/>
    <PONumber/>
    <ItemAmount/>
    <ItemName/>
    <ItemQuantity/>
  </InvoiceLineItem>
</PurchaseOrders>

子表查询中的 “${PONumber}” 语法表示该值将引用父表中的一列(PONumber 列)。

如果从 “PurchaseOrderLineItems” 表中提取了多个记录,则 InvoiceLineItem 元素(及其所有子元素)将在输出 XML 中多次出现。

输入/输出映射

一些数据库操作需要输入并且生成输出。输入/输出映射提供了一种为同一数据库操作为输入文件和输出文件设置 XML 模式的方法。

创建输入/输出映射

输入/输出映射使用与输入映射和输出映射相同的方法创建。每个映射针对一个特定的存储过程,映射编辑器向导可以查看存储过程的预期参数。

输入参数

存储过程的输入参数由数据库系统定义,因此不需要在映射编辑器中进行配置来选择相关的输入参数。系统公布的任何参数都显示在映射编辑器中,并且不能取消选择或以其他方式配置这些参数。

输入/输出映射为 XML

一旦创建了输入/输出映射,就会生成一个 XML 模板来匹配所需的输入参数,并生成一个 XML 模板来处理来自存储过程的输出。

输入 XML

输入文件的 XML 模板遵循与输入映射的 XML 模板相同的原则;匹配模板 XML 结构的文件将被解释为数据库操作的输入。有关更多详细信息,请参阅 Input Mappings as XML 部分。

输出 XML

存储过程的输出不是由数据库系统预先定义的。因此,可能需要提供输入参数的测试集,以便端口可以调用过程并检测输出的结构。

要提供一组示例输入,请使用映射编辑器右上角的 显示示例输入 按钮。在结果模态中提供一组测试输入后,端口将显示它接收到的输出的 XML 结构。复制此 XML 结构或使用 保存样本数据 按钮在应用程序的其他方面使用此 XML 结构,例如 XML Map 端口模板。