> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kintone 端口配置

> 将知行之桥连接至 Kintone，实现数据集成与同步。

Kintone 端口可通过推送或拉取 Kintone 数据，将 Kintone 集成到您的数据流中。

## 核心功能

* 集成云端业务应用平台，用于自定义应用程序数据管理
* 灵活的身份验证选项，包括密码、API 令牌（Token）或 OAuth
* 标准数据库操作（Select、Lookup、Upsert 和存储过程），用于数据操作

请按照以下步骤将 知行之桥 连接至 Kintone。

## 建立连接

要建立与 Kintone 的连接，请使用以下两种方法之一：

* 将 Kintone 端口添加到流中。然后，在**设置**选项卡上，单击**连接**下拉列表旁边的**新建**。
* 打开 知行之桥 **设置**页面，然后打开**连接**选项卡。单击**添加**，选择 **Kintone**，然后单击**下一步**。

> [!NOTE]
>
> * 登录流程仅在首次创建连接时需要。
> * 与 Kintone 的连接可在多个 Kintone 端口中重复使用。

## 输入连接设置

1. 输入连接信息：

   * **名称**：连接的静态名称，可根据需要设置。
   * **类型**：始终设置为 Kintone。
   * **连接**：用于连接的身份验证方案。选项为**密码**、**API 令牌**和 **OAuth**。
   * **URL**：您要连接的 Kintone 站点的 URL。

2. 输入所选身份验证方案的连接信息：

   * [密码](#密码)
   * [API 令牌](#api-令牌)
   * [OAuth](#oauth)

3. 在端口配置面板的**连接**下拉列表中选择新建的连接。

### 密码

1. 在**用户名**字段中，输入用于登录的用户名。

2. 在**密码**字段中，输入该用户的密码。

3. 如有需要，单击**高级**打开高级连接设置菜单。大多数情况下无需使用。

4. 单击**测试连接**，确认 知行之桥 可使用提供的信息连接至 Kintone。如果发生错误，请检查所有字段并重试。

5. 单击**添加连接**完成连接设置。

### API 令牌

1. 在 **ApiToken** 字段中，提供用于身份验证的 API 令牌。

2. 如有需要，单击**高级**打开高级连接设置菜单。大多数情况下无需使用。

3. 单击**测试连接**，确认 知行之桥 可使用提供的信息连接至 Kintone。如果发生错误，请检查所有字段并重试。

4. 单击**添加连接**完成连接设置。

### OAuth

1. 在 **OAuth Client Id** 字段中，输入您账户的客户端 ID。

2. 在 **OAuth Client Secret** 字段中，输入您账户的客户端密钥。

3. 如有需要，单击**高级**打开高级连接设置菜单。大多数情况下无需使用。

4. 单击**连接**。

5. 在打开的新标签页中，登录您的 Kintone 账户。如有提示，请授予访问权限。

6. 返回 知行之桥。

   * 若连接成功，单击**添加连接**。
   * 若连接失败，请检查您的 URL 和登录凭据，然后重试。

> [!NOTE]
>
> **高级**选项卡上还有特定于数据源的身份验证和配置选项。本文档未完整记录这些选项，但您可以在 我们网站的 [在线帮助文件](https://www.kasoftware.com/articles.html) 页面上找到数据源的详细信息。

## 选择操作

建立与 Kintone 的连接后，您必须选择 Kintone 端口要执行的操作。下表列出了每种操作及其在 知行之桥 流中的位置。

| 操作 | 说明 | 流中的位置 |
| - | - | - |
| [Upsert](/26.2/self-hosted/zh/connectors/kintone/kintone-upsert.md) | 插入或更新 Kintone 数据。默认情况下，如果 Kintone 中已存在记录，则使用输入中提供的值对 Kintone 中的现有数据执行更新。 | 结尾 |
| [Lookup](/26.2/self-hosted/zh/connectors/kintone/kintone-lookup.md) | 从 Kintone 检索值，并将其插入流中已存在的 知行之桥 消息。 **Lookup 查询**决定端口从 Kintone 检索的值，应将其格式化为针对 Kintone 表的 SQL 查询。 | 中间 |
| [Lookup 存储过程](/26.2/self-hosted/zh/connectors/kintone/kintone-lsp.md) | 将进入端口的数据作为存储过程的输入，然后将结果插入流中已存在的 知行之桥 消息。 您可以在**测试 Lookup** 对话框中单击**显示示例数据**按钮，为选定的存储过程提供示例输入并预览结果。 | 中间 |
| [Select](/26.2/self-hosted/zh/connectors/kintone/kintone-select.md) | 从 Kintone 检索数据并引入 知行之桥。 您可以使用**过滤器**面板向 Select 添加过滤条件。这些过滤器的功能类似于 SQL 中的 *WHERE* 子句。 | 开始 |
| [执行存储过程](/26.2/self-hosted/zh/connectors/kintone/kintone-esp.md) | 将进入端口的数据作为存储过程的输入，然后将结果传递至流的下游。 您可以在**测试执行存储过程**对话框中单击**显示示例数据**按钮，为选定的存储过程提供示例输入并预览结果。 | 中间 |

## 高级选项卡

**高级**选项卡上的许多设置是从您所使用的数据源动态加载的，因此本文档中不涵盖这些设置。您可以在 我们网站的 [在线帮助文件](https://www.kasoftware.com/articles.html) 页面上找到数据源的详细信息。

以下描述的选项适用于所有数据源。

### 消息

| 设置 | 说明 |
| - | - |
| **保存到已发送文件夹** | 勾选此项可将端口处理的文件复制到该端口的已发送文件夹。 |
| **已发送文件夹方案** | 指示端口按所选时间间隔对已发送文件夹中的消息进行分组。例如，**每周**选项指示端口每周创建一个新子文件夹，并将该周的所有消息存储在该文件夹中。空白设置表示端口将所有消息直接保存在已发送文件夹中。对于处理大量消息的端口，使用子文件夹有助于保持消息整洁并提升性能。 |

### 高级设置

\_高级设置\_是依赖任意数据库驱动程序（例如 Database、CData 和 API 端口）来连接各种数据源的端口的通用设置。

| 设置 | 说明 |
| - | - |
| **自动截断** | 启用后，端口会自动截断超出允许长度限制的字符串或二进制列值。 |
| **命令超时** | 命令执行的超时时间（以秒为单位）。 |
| **最后插入的 ID 查询** | 提供一个查询，用于检索最后插入记录的自增 ID。 |
| **日志级别** | 端口生成的日志的详细程度。请求支持时，请将其设置为 **Debug**。 |
| **本地文件命名方案** | 用于为端口输出的消息分配文件名的方案。您可以在文件名中动态使用宏，以包含标识符和时间戳等信息。有关更多信息，请参阅[宏](#宏)。 |
| **记录消息** | 勾选后，端口会在日志目录中的消息日志旁边保存消息副本。如果禁用此功能，您可能无法从**输入**或**输出**选项卡下载文件副本。 |
| **最大失败记录数** | 允许插入失败的最大记录数，以便继续处理。默认值 0 表示任何错误都会导致输入消息被标记为"错误"，未提交的事务将被回滚。值 -1 表示忽略所有错误，端口继续尝试插入后续记录。正值表示端口在达到阈值之前继续尝试插入记录。 |
| **输出文件格式** | 表示输出数据的格式。默认值（XML）使端口为每条处理的记录输出一个 XML 文件，同时可选择将多条记录合并为单个数据结构（取决于**最大记录数**的值）。CSV 和 TSV 选项以各自的文件格式输出数据。此选项不适用于包含子表的复杂表结构。 |
| **处理变更间隔单位** | 仅适用于 Select 操作。当在**设置**选项卡的 **Select 配置**的**高级**部分勾选**使用列 *columnname* 处理新记录或已更改记录**时，此选项控制如何解读**处理变更间隔**设置（例如，小时、天或周）。有关此设置和以下两项设置的详细信息，请参阅[仅处理新记录或已更改记录](/26.2/self-hosted/zh/connectors/kintone/kintone-ac.md#only-process-new-or-changed-records)。 |
| **处理变更间隔** | 当在**设置**选项卡的 **Select 配置**部分勾选**使用列 *columnname* 处理新记录或已更改记录**时，此选项控制 知行之桥 在第一次尝试时处理多少历史数据。例如，保持默认值 180（天）意味着 知行之桥 仅尝试处理最近 180 天内创建或修改的数据。 |
| **处理变更起始日期** | 当在**设置**选项卡的 **Select 配置**部分勾选**使用列 *columnname* 处理新记录或已更改记录**时，此选项控制要检索的数据的起始日期。 |
| **重置历史记录** | 重置勾选**使用列 *columnname* 处理新记录或已更改记录**时存储的缓存。 |
| **批量输入大小** | 如果数据源支持批处理，则批处理中的最大查询数。 |
| **批次大小** | 批次组中的最大批次消息数。 |
| **最大记录数** | 单个输出消息中包含的最大记录数。使用 -1 表示所有输出记录都放在一个文件中，使用 0 表示端口可根据配置的**输出文件格式**自行决定。默认情况下，XML 每条记录输出一个文件，而平面文件格式将所有记录包含在一个文件中。 |
| **事务大小** | 一个事务中的最大查询数。 |
| **处理延迟** | 放置在输入文件夹中的文件被延迟处理的时间（以秒为单位）。这是一个旧版设置。最佳做法是[使用文件端口](/26.2/self-hosted/zh/flows/designing-a-flow.md#interacting-with-the-local-file-system)来管理本地文件系统，而不是使用此设置。 |
| **插入空值** | 取消勾选时（默认），端口在构建 INSERT 和 UPDATE 语句时跳过空 XML 元素，导致数据库对 INSERT 语句使用默认列值，对 UPDATE 语句保持列值不变。勾选时，端口在 INSERT 和 UPDATE 语句中包含空 XML 元素，使用空字符串作为列的值。 |
| **插入 Null 值** | 取消勾选时（默认），端口在构建 INSERT 和 UPDATE 语句时跳过 null XML 元素（由 `xsi:nil="true"` 属性标示）。勾选时，端口在 INSERT 和 UPDATE 语句中包含 null XML 元素，使用 null 作为列的值。被视为 null 的情况包括：`Not exist`、`<element/>`、`<element xsi:nil="true"/>`、`<element xsi:nil="true"></element>`、`<element null="true"/>` 和 `<element null="true"></element>`。 |
| **Lookup 缓存** | 勾选**启用 Lookup 缓存**可在本地缓存中执行查询，然后再直接在数据源上执行（当缓存中未返回记录时）。取消勾选时（默认），查询直接在数据源上执行。以下 Lookup 缓存选项仅在勾选**启用 Lookup 缓存**时可用。 |
| **Lookup 缓存提供程序** | 指定用于连接缓存数据库的驱动程序。 |
| **Lookup 缓存连接字符串** | 设置后，端口使用此处指定的数据库进行缓存。 |
| **Lookup 缓存容差** | 指定端口应多久查询数据源一次以刷新缓存。与**容差单位**选项配合使用。 |
| **Lookup 缓存容差单位** | 选择**分钟**、**小时**或**天**。 |
| **日志子文件夹方案** | 指示端口按所选时间间隔对 `Logs` 文件夹中的文件进行分组。例如，**每周**选项指示端口每周创建一个新子文件夹，并将该周的所有日志存储在该文件夹中。空白设置表示端口将所有日志直接保存在 `Logs` 文件夹中。对于处理大量事务的端口，使用子文件夹有助于保持日志整洁并提升性能。 |

### 杂项

\_杂项设置\_用于特定使用场景。

| 设置 | 说明 |
| - | - |
| **其他设置** | 允许您以分号分隔的列表（例如 `setting1=value1;setting2=value2`）配置隐藏的端口设置。正常端口使用场景和功能通常不需要使用这些设置。 |

## 自动化选项卡

### 自动化设置

*与端口自动处理文件相关的设置。*

| 设置 | 说明 |
| - | - |
| **发送** | 到达端口的文件是否会自动发送。 |
| **重试间隔** | 重试失败发送之前的分钟数。 |
| **最大尝试次数** | 端口处理文件的最大次数。是否成功取决于是否收到服务器确认。如果将此值设置为 0，端口将无限期地重试文件。 |
| **接收** | 端口是否应自动查询数据源。 |
| **间隔** | 自动查询尝试之间的间隔。 |
| **每小时的分钟数** | 每小时计划的分钟偏移量。仅当上方间隔设置为\_每小时\_时适用。例如，如果此值设置为 5，自动化服务将在 1:05、2:05、3:05 等时间下载。 |
| **时间** | 应进行尝试的一天中的时间。仅当上方间隔设置为\_每天\_、\_每周\_或\_每月\_时适用。 |
| **天** | 应进行尝试的日期。仅当上方间隔设置为\_每周\_或\_每月\_时适用。 |
| **分钟** | 尝试下载前等待的分钟数。仅当上方间隔设置为\_分钟\_时适用。 |
| **Cron 表达式** | 表示 Cron 表达式的五位字符串，用于确定应在何时进行尝试。仅当上方间隔设置为\_高级\_时适用。 |

### 性能

*与端口资源分配相关的设置。*

| 设置 | 说明 |
| - | - |
| **最大工作线程数** | 从线程池中消耗的处理此端口文件的最大工作线程数。如果设置了此值，它将覆盖[高级设置](/26.2/self-hosted/zh/getting-started/administration/settings/advanced-settings.md)页面的[性能设置](/26.2/self-hosted/zh/getting-started/administration/settings/performance-settings.md)部分的默认设置。 |
| **最大文件数** | 分配给端口的每个线程发送的最大文件数。如果设置了此值，它将覆盖[高级设置](/26.2/self-hosted/zh/getting-started/administration/settings/advanced-settings.md)页面的[性能设置](/26.2/self-hosted/zh/getting-started/administration/settings/performance-settings.md)部分的默认设置。 |

## 警报选项卡

*与配置警报相关的设置。*

在执行服务级别协议（SLA）之前，您需要设置电子邮件警报以接收通知。默认情况下，知行之桥 使用[警报](/26.2/self-hosted/zh/getting-started/administration/settings/alerts.md)选项卡上的全局设置。要为此端口使用其他设置，请开启**覆盖全局设置**。

默认情况下，错误警报已启用，这意味着每当发生错误时都会发送电子邮件。要关闭它们，请取消勾选**启用**复选框。

输入**主题**（必填），然后可选地输入以逗号分隔的**收件人**电子邮件列表。

## SLA 选项卡

*与配置服务级别协议（SLA）相关的设置。*

SLA 允许您配置流中端口预期发送或接收的数量，并设置预期满足该数量的时间范围。当 SLA 未满足时，知行之桥 会发送电子邮件警告用户，并将 SLA 标记为\_存在风险\_，这意味着如果 SLA 很快未得到满足，它将被标记为\_违反\_。这给用户提供了介入的机会，以确定 SLA 未满足的原因并采取适当措施。如果在风险期结束时 SLA 仍未满足，SLA 将被标记为违反，并再次通知用户。

要定义 SLA，请开启**预期数量**，然后单击**设置**选项卡。

![Empty SLA configuration](https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/sla_empty.png?fit=max\&auto=format\&n=ilnLy7gsSdFqbKmI\&q=85\&s=9cd47a4173ed889fe20ff78de28190be)

* 如果您的端口有独立的发送和接收操作，请使用单选按钮指定 SLA 适用的方向。
* 在窗口的**至少期望**部分：
  * 设置您期望处理的最少事务数（数量）
  * 使用**每**字段指定时间范围
  * 指明 SLA 何时生效。如果选择**从...开始**，请填写日期和时间字段。
  * 勾选您希望 SLA 生效的星期几复选框。如有必要，使用下拉菜单选择**每天**。
* 在窗口的\*\*将状态设置为"存在风险"\*\*部分，指定 SLA 何时应被标记为存在风险。
  * 默认情况下，在 SLA 违反之前不会发送通知。要更改此行为，请勾选**发送"存在风险"通知**。

以下示例显示为端口配置的 SLA，该端口期望每天（周一至周五）接收 1000 个文件。如果在时间段结束前 1 小时尚未收到 1000 个文件，将发送存在风险通知。

![SLA 配置示例](https://mintcdn.com/qiao/ilnLy7gsSdFqbKmI/public/images/sla_defined.png?fit=max\&auto=format\&n=ilnLy7gsSdFqbKmI\&q=85\&s=33e5282b3f7970e3e1fef056825d7772)

> [!NOTE]
>
> 如有必要，您可以关闭 SLA 警报。这在维护窗口期间很有用。单击导航栏上的**设置**，然后导航至**警报 > 常规警报**。单击平板电脑和铅笔图标进行编辑，并取消勾选 **SLA 警报**设置。

## 宏

在文件命名策略中使用宏可以提高组织效率和对数据的上下文理解。通过在文件名中加入宏，您可以动态地包含标识符、时间戳和标头信息等相关信息，为每个文件提供有价值的上下文。这有助于确保文件名反映对您的组织重要的详情。

知行之桥 支持以下宏，所有宏均使用以下语法：`%Macro%`。

| 宏 | 说明 |
| - | - |
| ConnectorID | 解析为端口的 ConnectorID。 |
| Ext | 解析为端口当前处理文件的文件扩展名。 |
| Filename | 解析为端口当前处理文件的文件名（包含扩展名）。 |
| FilenameNoExt | 解析为端口当前处理文件的文件名（不含扩展名）。 |
| MessageId | 解析为端口输出的消息的 MessageId。 |
| RegexFilename:*pattern* | 将正则表达式模式应用于端口当前处理文件的文件名。 |
| Header:*headername* | 解析为端口当前处理消息上目标标头（`headername`）的值。 |
| LongDate | 解析为系统当前日期时间的长格式（例如，Wednesday, January 24, 2024）。 |
| ShortDate | 解析为系统当前日期时间的 yyyy-MM-dd 格式（例如，2024-01-24）。 |
| DateFormat:*format* | 解析为系统当前日期时间的指定格式（`format`）。有关可用的日期时间格式，请参阅[示例日期格式](/26.2/self-hosted/zh/scripting/date-formatters#date-formats-with-literal-characters)。 |
| Vault:*vaultitem* | 解析为指定保管库项目的值。 |
| Table | 解析为端口从中选择数据的表名。 |
| PK | 解析为从表中接收记录的主键值。 |
| Sequence | 根据端口接收的总记录数解析为四位数（例如，%Sequence% 在返回第五条记录时解析为 0005）。 |
| FileFormat | 解析为端口高级选项卡上指定的输出文件格式（XML、CSV 或 TSV）。 |

### 示例

某些宏（如 %Ext% 和 %ShortDate%）不需要参数，但其他宏需要。所有需要参数的宏均使用以下语法：`%Macro:argument%`

以下是需要参数的宏示例：

* %Header:headername%：其中 `headername` 是消息上标头的名称。
* %Header:mycustomheader% 解析为输入消息上设置的 `mycustomheader` 标头的值。
* %Header:ponum% 解析为输入消息上设置的 `ponum` 标头的值。
* %RegexFilename:pattern%：其中 `pattern` 是正则表达式模式。例如，`%RegexFilename:^([\w][A-Za-z]+)%` 匹配并解析为文件名中的第一个单词，且不区分大小写（`test_file.xml` 解析为 `test`）。
* %Vault:vaultitem%：其中 `vaultitem` 是[保管库](/26.2/self-hosted/zh/getting-started/administration/settings/global-settings-vault.md)中项目的名称。例如，`%Vault:companyname%` 解析为保管库中存储的 `companyname` 项目的值。
* %DateFormat:format%：其中 `format` 是可接受的日期格式（详情请参阅[示例日期格式](/26.2/self-hosted/zh/scripting/date-formatters#sample-date-formats)）。例如，`%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%` 解析为文件上的日期和时间戳。

您还可以创建更复杂的宏，如以下示例所示：

* 在一个文件名中组合多个宏：`%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%%EXT%`
* 在宏外包含文本：`MyFile_%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%`
* 在宏内包含文本：`%DateFormat:'DateProcessed-'yyyy-MM-dd_'TimeProcessed-'HH-mm-ss%`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.