API 端口

API端口支持在知行EDI系统发布自定义API。 如果您正在寻找一个可以使用API的客户端，请改用REST端口。

总览

API接口将数据库中的表，视图和存储过程作为Web API公开。 API端口从目标数据库读取可用的表，视图和存储过程，然后可以将这些资源的任何子集公开为API资源。

API端口也可以用于公开自定义脚本接口。 对自定义脚本进行API调用时，将执行脚本以构建API响应。 自定义脚本是一种非常灵活的方法，可以提供知行EDI系统资源作为对Web请求的响应。

端口配置

本节包含所有可配置的端口属性。

连接

配置

API访问设置

API 接口	自定义API的发布网址。 访问指定资源时，请在此URL值后附加斜杠和资源名称。
API 文档	用于发布自定义API文档的URL。

连接

与数据库连接有关的设置。

数据源类型	连接的数据库类型。
设置格式	是指定一组单独的连接属性还是指定包含每个属性的单个连接字符串。
连接字符串	连接数据库的字符串格式， 仅在“设置格式”设置为“连接字符串”
服务器	托管数据库的服务器的主机名或IP地址。
端口	连接到数据库主机的端口。
数据库	要连接的数据库的名称。
用户	有权访问数据库的用户。
密码	指定用户的密码。

高级设置

根据设置的数据源类型自动生成高级设置。 有关高级设置的更多信息，请参见与数据源匹配的端口的文档（例如，当数据源类型为MySQL时，请参见MySQL端口文档以获取高级设置）。

其他设置

不同于先前类型的设置

日志信息	已处理文件的日志是否包括该文件副本。
保存到已发送文件夹	端口处理的文件是否应复制到端口的“Sent”文件夹。

资源

资源

端口公开的API资源列表。 每个资源都是根据连接的数据库中存在的表或视图中生成的， 新添加的资源会将新的数据库数据通过端口暴露给Web API调用。

函数

函数

端口公开的API 函数的列表。 每个函数都是根据连接的数据库中存在的存储过程中生成的， 新添加的函数会将新的数据库数据通过端口暴露给Web API调用。

用户

用户

授权对端口进行API调用的用户列表。 可以通过HTTP方法（GET，POST等），每小时的请求数以及并发请求数来限制用户， 还可以在“服务器”选项卡中按服务器管理API凭据。

服务器

受信任的IP地址

授权通过端口进行API调用的IP地址列表， 也可以在“用户”选项卡中按用户管理API凭据。

默认速率限制（每用户）

设置限制了允许的API请求数量。

每小时最大请求数	限制一个用户在一小时内可以发出的请求数。
并发请求数上限	限制用户可以发出的并发请求数。

跨域资源共享（CORS）

CORS提供跨域资源设置。

启用跨域资源共享（CORS）	是否启用CORS。
允许所有不带“ *”的域	如果启用，则域来源将不限于特定列表。
访问控制允许来源（Access-Control-Allow-Origin）	以逗号分隔的来源域列表，包含为HTTP响应标头。
访问控制允许凭证（Access-Control-Allow-Credentials）	跨域请求中是否允许使用用户凭据（例如Cookie），包含为HTTP响应标头。
访问控制允许方法（Access-Control-Allow-Methods）	以逗号分隔的方法列表，包含为HTTP响应标头。
访问控制允许标题（Access-Control-Allow-Headers）	以逗号分隔的标题列表，包含为HTTP响应标头。
访问控制最大年龄（Access-Control-Max-Age）	访问控制响应标头值可以缓存的最大持续时间。

OData

与OData功能支持有关的设置。

服务器端分页大小	OData请求返回的每页结果数。 当此选项设置为0时，将返回所有结果。
默认格式	客户端未指定格式时，默认使用该OData格式。
默认版本	客户端未指定格式时，默认使用该OData版本。
日期时间格式	返回的日期时间信息的格式。
基础 URL	OData接口的标准URL。 如果未指定，知行EDI系统将尝试根据传入的请求创建基础URL。

建立连接

在创建第一个API之前，您需要连接到数据存储。 知行EDI系统支持连接到关系数据库，文件存储和后端服务，例如其他API。

在连接页面上选择数据存储类型后，将为所选数据存储生成连接属性列表。 输入用于连接到数据存储所需信息，然后在此页面上保存更改。 单击测试连接以确保该应用程序已连接到目标数据存储。

注意：该应用程序包括一些常用数据库的驱动程序，但可能不包括其支持的所有数据源的驱动程序。 对于未附带的驱动程序，请确保按照以下说明针对您的服务器进行操作。

Windows版

在此计算机上安装ADO.NET提供程序，重新启动服务器，然后重试连接到数据存储。

Java版

将JDBC驱动程序复制到Java Web服务器的lib文件夹中。

构建您的第一个API

定义到数据源的连接后，您可以显示API的资源。 您可以使用管理控制台中的向导来生成用于读取和写入数据存储的架构。

显示数据库资源

可通过以下步骤将数据库建模为API：

• 单击资源>添加资源。
• 选择要建模为API的表。
• 选择要在资源中显示的列。

资源是在模式中定义的，可以在不从数据库重新生成的情况下轻松地对其进行修改或扩展。 您可以通过单击资源或在资源条目中的“编辑”来修改结构。 生成的结构包含架构的两个基本组件：

• 包含资源列定义的信息块
• 对应于HTTP方法和调用数据处理操作的方法

查询您的API

为API创建资源后，您可以将它们公开给授权的用户和IP地址。 ArcESB使用基于身份验证令牌的身份验证，并支持主要的身份验证方案。 单击“用户”选项卡以管理用户的身份验证令牌和权限。 要定义允许访问该应用程序的IP地址，请单击“服务器”选项卡。

现在，您可以在浏览器中查询API，如下面的示例查询和响应所示。

请求

响应

API管理

通过知行EDI系统，您可以创建和管理与其他应用程序集成的API。该API包含安全的Web服务，可以从任何应用程序，浏览器或智能设备远程访问。该API中的资源使用JSON格式的OData作为访问数据的默认REST协议。支持其他Web服务格式，包括OData（Atom），JSONP，SOAP，HTML 和 CSV。

您可以浏览API并在管理控制台中管理对它们的访问。单击导航栏上的API，以查看文档和访问API的示例，可以转到应用程序设置来管理API的连接设置，资源，用户和服务器设置。

本节包含与设计和管理API相关的主题。

API资源

资源是API中公开的对象，可以查询，创建，更新和删除。资源可以支持创建，读取，更新和删除（CRUD）全部操作，或者仅允许几个操作。本节介绍用于对应用程序公开的资源执行CRUD操作的HTTP方法。

GET

HTTP GET请求可用于从服务器检索单个资源或一组资源。 以下是对整个集合的示例请求：

响应示例：

POST

HTTP POST请求可用于创建新资源， 该请求必须包含创建资源所需的输入。 以下是示例请求：

响应示例：

PUT

HTTP PUT请求可用于更新资源，主键是必需的。 以下是示例请求：

响应示例：

DELETE

HTTP DELETE请求可用于删除资源，主键是必需的。 以下是示例请求

该响应仅包含204状态码。

覆盖HTTP方法

某些客户端可能无法为特定操作发出正确的HTTP方法。 您可以使用@x-http-method 字符串输入参数或 X-HTTP-Method HTTP标头来覆盖请求的HTTP方法。 例如，不支持HTTP PUT方法的客户端可以在X-HTTP-Method：PUT标头中包含GET请求，以发出对资源的更新请求。

筛选资源

您可以通过在URL指定要检索的资源集，使用HTTP GET请求检索所有资源，过滤资源，对资源进行排序以及限制从每个资源返回的数据。 例如，要检索所有Cars资源，请使用以下URL：

单个资源

检索单个资源时，需要在URL中指定该资源，并且加入要查询的资源主键。 例如：

某些资源可能具有多个主键，如下面的示例所示检索：

过滤条件

客户端应用程序可以基于请求中提供的过滤器检索多个资源。 例如，检索Make是“ Honda”的所有资源，如下所示：

支持以下逻辑运算符：

eq	等于
ne	不等于
gt	大于
ge	大于等于
lt	小于
le	小于等于
not	否定

您还可以使用 and 和 or 组合多个过滤器：

$filter 可以和startswith，endswith，toupper，tolower和contains 函数一起使用。 例如，以下请求将返回Make属性包含Honda字符串的资源：

select 属性

要检索属性的子集，请使用$select，如以下示例所示：

以上示例将返回与请求中过滤条件匹配的所有资源的Id 和Model 属性。

您也可以检索单个资源的某个单独的属性，如下：

排序

可以使用$orderby对资源进行排序，如以下示例所示：

以上示例返回的资源将按Model 升序排列，然后是Color 降序排列。

分页

服务端

本应用程序支持服务器端分页，可以在应用程序的“设置”>“服务器”部分中启用它。 当分页大小大于0并且请求返回的结果大于分页大小时，结果的下一页的URL包含在响应的@ odata.nextlink属性中，结果的最后一页不包含此属性。 该URL包含一个分页令牌，该令牌在接下来的两分钟内仍然有效。 例如，以下响应具有三个资源和一个@odata.nextLink属性，@odata.nextLink属性包含记录的下一页的URL：

客户端

知行EDI系统还支持使用$top，$skip和$count进行客户端分页。 您可以使用$top=n在结果中仅包含前n个资源。 例如，使用以下请求显示前十名“Cars”资源：

您可以使用$skip=n从结果中排除前n个资源，也可以将$top与$skip结合使用以实现客户端分页，但是$skip需始终在$top之前。 例如，以下两个查询检索两个页面中的前20个资源：

您还可以将参数$count设置为true以返回结果中的记录总数。 如果使用OData版本2.0或3.0，则可以将$inlinecount设置为所有页面。 参考以下示例：

将返回以下响应：

如上所示，响应中将返回满足过滤条件的总数以及单页结果。

仅使用总计

您只能检索与查询满足过滤条件的资源总数，如以下示例所示：

响应是返回满足过滤条件的资源总数。

API 函数

函数可用于扩展资源上的操作集并在服务器上执行不相关的函数。 函数必须作为HTTP POST请求执行。 以下是操作调用的示例：

以下是响应：

使用 URL参数作为入参

如果客户端不支持HTTP POST方法，则可以使用URL参数@x-http-method调用该函数。 然后可以将操作的输入指定为其他URL参数：

发现

基于OpenAPI规范，该应用程序的API已被完整记录并可发现。 可以从标准JavaScript，与OpenAPI兼容的应用程序或支持OData标准的任何应用程序中访问API。 以下各节说明如何使用这些标准来发现API。

服务文件

默认情况下，服务文档是JSON格式的所有API的简单清单。该服务文档是从服务根目录返回的，在该根目录中会列出所有请求，包括元数据请求。以下是服务根目录的示例：

要检索更多详细信息，请查看元数据URL。

元数据网址

该应用程序通过OData元数据文档URL向OData使用者公开其API的功能。元数据文档以XML格式返回，并包含列数据类型，资源键和其他信息。您可以通过将$metadata附加到服务根目录来访问完整的元数据资源，如以下示例所示：

要访问资源的元数据，请将$ metadata附加到资源的资源URL：

OpenAPI定义

将为您通过应用程序显示的数据源生成OpenAPI（Swagger）定义。

要获取Swagger定义，请将$swagger附加到服务根，如以下示例所示：

服务器响应

以下是服务器对API资源的典型响应列表，以及何时需要此类响应的描述。

200 OK	服务器已正确处理了请求。
201 Created	请求成功，指定资源由服务器创建。
204 No Content	如果请求的资源具有空值，或者服务应用了return = minimum首选项，则请求将返回此状态。
400 Bad Request	该请求无法理解或缺少必需的参数。
401 Unauthorized	用户未经身份验证或未授权访问此资源。
403 Forbidden	拒绝对此资源的访问。
404 Not Found	资源不存在。
405 Method Not Allowed	该资源不允许使用指定的HTTP方法。
429 Too Many Requests	用户在给定的时间内发送了太多请求，或者超过了并发请求的最大数量。
501 Not Implemented	服务器不支持满足请求所需的功能。 当服务器无法识别请求方法并且不支持任何资源时，将返回此响应。

用户数

知行EDI软件使用基于身份验证令牌的身份验证来控制每个用户对API的访问。身份验证令牌是用户通过其向API进行身份验证的随机生成的唯一标识符，身份验证令牌还代表用户的当前权限。

Authtokens使您可以使用任何主要的身份验证方案进行连接。例如，要使用HTTP Basic身份验证，请在User标头中设置用户名，并在Password标头中设置用户的相应身份验证。有关验证API的更多信息，请参见验证。

新增使用者

要添加用户，请到端口的“用户”选项卡，然后单击“添加”。在出现的对话框中，输入以下信息：

• 名称：输入要在HTTP身份验证中使用的用户名。
• 权限：选择允许用户访问的HTTP方法，GET，POST，PUT / PATCH / MERGE或DELETE。这些分别对应于SELECT，INSERT，UPDATE和DELETE语句。
• 最大请求数：输入此用户每小时的最大请求数。值0允许用户每小时无限制访问。
• 最大并发请求数：输入可以同时发送的最大请求数。值0允许用户无限制同时请求。请注意，特定于用户的设置将覆盖服务器范围的API限制设置。用户设置之一的空值使用服务器默认值。

配置用户数据库

默认情况下，知行EDI系统将用户信息存储在SQLite数据库中。您还可以将用户信息保存到您选择的数据库中。如果使用嵌入式服务器，请在Web.config的connectionStrings 元素中指定到缓存数据库的连接字符串。否则，请参考托管应用程序所在服务器的文档。

认证方式

您可以授权用户使用身份验证令牌访问API资源，提供HTTP身份验证中的身份验证令牌，如下所示。 您可以在管理控制台的“配置文件”>“安全性”选项卡上管理API用户和允许的IP地址。

在调用API之前，您还需要在配置文件>设置中允许特定的IP地址连接到API。 默认情况下，所有IP地址均受限制。

在基本身份验证中使用身份验证令牌

使用基本身份验证时，应将用户的身份验证令牌用作密码。

在HTTP标头中使用Authtokens

将HTTP标头x-rssbus-authtoken与所需的auth令牌一起添加为HTTP请求的一部分。

使用身份验证令牌作为查询字符串参数

您可以将auth令牌指定为@authtoken参数的值，该参数可以作为HTTP表单发布数据或查询参数的一部分提供。 但是，默认情况下，应用程序不支持在查询字符串参数中传递authtoken。

您可以通过在profile.cfg的“应用程序”部分中设置以下选项来启用此功能。

.NET .cfg文件位于应用程序根目录的data子文件夹中。

Java

在Java版本中，它位于数据目录中。 data目录的位置取决于您的操作系统：

• Windows：C:\ProgramData\RSSBus Connect
• Unix或Mac OS X：〜/rssbus

速率限制

可以为每个用户配置使用限制和服务器范围的默认值。

服务器默认值

要配置应用于所有用户的默认速率限制，请在端口的“服务器”选项卡，在此页面上可以配置以下选项：

• 最高每小时请求数：每个用户每小时允许的默认最大请求数。值为0时，默认情况下每小时允许无限制请求。
• 最高并发请求：每个用户允许的默认最大同时请求数。值0允许默认情况下无限制同时请求。

用户特定的限制

要为单个用户配置速率限制，请在端口的“用户”选项卡，选择一个用户，然后单击“编辑”，可以在对话框中配置以下选项：

• 权限： 选择允许用户访问的HTTP方法，GET，POST，PUT / PATCH / MERGE或DELETE。这些分别对应于SELECT，INSERT，UPDATE和DELETE语句。
• 最高请求（小时）： 输入每小时该用户允许的最大请求数。值为0时允许用户每小时无限制请求。
• 最高并发： 输入为此用户允许的最大同时请求数。值为0时允许用户无限制同时请求。

用户特定的速率限制将覆盖服务器默认值。用户设置中值为空的属性将使用服务器默认值。

CORS

可以在“服务器”选项卡上配置跨域资源共享（CORS）。 CORS允许基于浏览器的客户端连接到知行EDI系统。如果没有CORS，则基于浏览器的脚本将无法连接到知行EDI系统，因为浏览器实施了同源策略。此策略限制客户端脚本和文档在其来源之外加载资源，脚本的来源包括协议，主机和端口。

选择启用CORS的选项后，可以设置以下选项来配置CORS：

• 允许所有域都没有*：设置此选项时，应用程序通过在Access-Control-Allow-Origin标头中返回该源来允许客户端传递的任何源。
• Access-Control-Allow-Origin：输入应用程序将参与CORS的来源。应用程序在Access-Control-Allow-Origin标头中返回这些原点。设置为”时，应用程序允许任何来源，并在Access-Control-Allow-Origin标头中传递”。这适用于公共API。 设置为时，应用程序将允许任何来源，并在Access-Control-Allow-Origin标头中传递。这适用于公共API。
• Access-Control-Allow-Methods：输入以逗号分隔的允许方法列表。
• Access-Control-Allow-Headers：输入逗号分隔的标题列表，该列表可在脚本发出的请求中使用。
• Access-Control-Allow-Credentials：如果要要求客户端提供凭据，请将其设置为true。
• Access-Control-Max-Age：输入用户代理可以缓存预检请求的秒数。

其他格式

除了所有资源和操作均支持的默认JSON格式外，该API还支持以下格式：XML，JSONP，SOAP，RSS，HTML，CSV和TSV。

XML

您可以通过添加查询参数$format=atom或通过向请求添加带有值application/xml的HTTP Accept标头来请求XML（OData Atom）格式。 请参阅下面的示例请求和响应。

请求

响应

JSONP

您可以通过添加查询参数$callback=myCallback来请求JSONP格式，其中myCallback是您要包装JSON结果的函数的名称。 请参阅下面的示例请求和响应。

请求

响应

RSS

您可以通过在请求中添加查询参数@rss来请求RSS格式。 请参阅下面的示例请求和响应。

请求

响应

HTML

通过将查询参数@html添加到请求中，可以请求将API响应格式化为简单的，未样式化的HTML表。 请参阅下面的示例请求和响应。

请求

响应

CSV

您可以通过将查询参数@csv添加到请求中，将API响应格式设置为CSV数据。 请参阅下面的示例请求和响应。

请求

响应

TSV

您可以通过将查询参数@tsv添加到请求中，将API响应格式设置为TSV数据。 请参阅下面的示例请求和响应。

请求

响应

自定义您的API 从知行EDI系统“资源”选项卡，可以基于数据库中的表构建API，支持多种数据库。

API的资源是在易于扩展的基于文本的模式中定义的。 要编辑模式，请单击“资源”选项卡上表中资源旁边的“编辑”。

您还可以将自己的接口作为REST API写入文件和后端服务。 例如，您可以将XML作为Web服务。

模式定义

API的资源是通过编写基于文本的架构来定义的。模式以rsbScript编写，rsbScript是一种简单的配置语言，可让您定义资源的列。它还具有内置操作，使您可以读取和写入数据库，文件和后端服务。

除了这些数据处理原语之外，rsbScript是一种功能齐全的语言，具有条件，循环等构造。但是，如示例架构所示，对于大多数资源定义，您不需要使用这些功能。

下文描述了一个全功能的架构，该架构允许双向访问SQLite数据库中的表。您可以使用“设置”>“资源”选项卡上的向导为数据库表和存储过程生成类似的模式，还可以通过单击模式旁边的编辑来在此选项卡上编辑模式。

下文还详细介绍了通过编写自己的模式来读写其他数据源所需的所有组件。资源模式以.rsd文件编写；操作的模式以.rsb文件编写。该向导将这些文件放在应用程序根目录的API子文件夹中。您必须将自定义架构放在此文件夹中。

此外，下文还详细介绍了通过编写自己的模式来读写其他数据源所需的所有组件。.模式以.rsd文件编写的,;模式以.rsb文件编写。您需要将自定义架构放在应用程序根目录的api子文件夹中。

# 标记资源列

连接到数据库时，资源的列具有以下基本属性：

• 栏名
• 数据类型
• 列是否为主键。

在模式的rsb:info块内，您可以使用这些属性和其他属性标记资源的列。

获取数据

收到HTTP GET请求后，应用程序将执行模式的GET方法。通过这种方法，您可以调用应用程序的内置操作来处理数据检索请求。以下是使用HTTP GET的示例搜索请求：

前面的请求可以映射为下面的SQL查询：

在相应的GET方法中，数据库查询的结果通过rsb:push关键字推送到应用程序的HTTP响应中。您可以使用apiSelect操作对数据库执行搜索，排序，汇总和其他数据检索查询。

创建数据

收到POST请求后，应用程序将执行模式的POST方法，您可以在其中调用数据操作操作，例如insert。

可参考以下HTTP POST 示例：

前面的请求可以映射为下面的SQL查询：

在相应的POST方法中，可以使用apiInsert操作执行对数据库的插入。

请注意，某些数据库从INSERT语句返回数据,例如新生成记录的ID。如果要访问从插入返回的值，请像使用GET一样使用rsb:push关键字。

更新数据

收到PUT请求时，应用程序将执行模式的PUT方法，您可以在其中调用数据操作操作，例如更新。

可参考以下PUT请求： PUT http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars(’1000′) { “Model”: “Civic” }

前面的请求可以映射为下面的SQL查询：

在相应的PUT方法中，在调用操作之前验证所需的输入（主键），可以检查是否提供了输入，并使用rsb:validate关键字提醒用户。请注意，您可以指定脚本要处理的多个HTTP方法。

另外，请注意，由于更新通常不返回数据，因此使用rsb:call关键字来调用该操作。您可以调用apiUpdate操作来执行对数据库的更新。

删除数据

收到DELETE请求时，应用程序将执行模式的DELETE方法，您可以在其中调用删除操作。例如，考虑以下HTTP DELETE请求：

HTTP DELETE 请求：

前面的请求可以映射为下面的SQL查询：

在DELETE方法中，可以调用apiDelete操作来执行对数据库的删除。

模式示例

通过以下模式，可以对SQLite数据库中的Cars表进行读写访问，包含通过HTTP访问数据库所需的所有组件。

关键字参考

有关本节中使用的以下关键字的更多信息，请参见《rsbScript参考》：

• rsb:info
• rsb:set
• rsb:script
• rsb:validate
• rsb:call
• rsb:push

典型定制

数据源的资源在简单的，基于文本的模式中定义，并且易于扩展。 本节会介绍一些常用的修改。 要编辑架构，请单击设置>资源，然后单击要修改的资源旁边的编辑。

删除列

从rsb:info删除attr元素将从资源中删除该列。 这意味着API不会列出该列，此外缓存不包含该列。 请注意，删除要删除的列的整个XML元素很重要。

更改资源列的数据类型

要更改资源列的数据类型，请将xs:type属性更改为以下受支持的数据类型之一：

• string
• datetime
• boolean
• int
• long
• double

重命名资源列

要重命名资源列，请找到资源的元素，然后添加一个名为alias的属性，其中包含要为该列使用的新名称。请注意，您不能更改名称属性。该值必须保持一致，以便应用程序维护到基础数据源中正确列的映射。

下面的示例将“类型”列重命名为APIType：

…

重命名资源

您可以通过在应用程序根目录的API子文件夹中更改资源的.rsd文件的名称来重命名资源。请注意，rsb:info中的title属性必须与基础数据源中表的名称相同.

更改数据源连接

您可以在rsb:info中使用connection属性来更改任何给定资源的连接。这样可以轻松地从沙箱切换到生产实例。

您在管理控制台中对连接所做的任何更改都会被引用到rsb:info中相同连接的所有资源引用，如下所示。

注：文案部分图片及内容来源于网络，版权归原创作者所有，如有侵犯到您的权益，请您联系我们进行删除，给您带来困扰，我们深感抱歉。