自定义 API

Version 24.3.9111

Schema 定义
典型定制

自定义 API

知行之桥包含一个用于根据数据库中的表构建 API 的向导。从资源选项卡访问该向导。知行之桥支持多种数据库。

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

还可以编写自己的 Schema 作为 REST API 来显示文件和后端服务。例如，可以将 XML 显示为 Web 服务。

Schema 定义

的 API 资源是通过创作基于文本的 Schema 来定义的。 Schema 是用知行之桥 Script 编写的，这是一种简单的配置语言，允许定义资源的列。它还具有内置操作，使能够读取和写入数据库、文件和后端服务。有关详细信息，请参阅脚本。

除了这些数据处理原语之外，知行之桥脚本是一种功能齐全的语言，具有条件、循环等结构。但是，如示例模式所示，对于大多数资源定义，不需要使用这些功能。

以下部分描述了一个功能齐全的 Schema ，该 Schema 支持对 SQLite 数据库中的表进行双向访问。可以使用 设置 > 资源 选项卡上的向导为数据库表和存储过程生成类似的 Schema 。还可以通过单击 Schema 旁边的编辑在此选项卡上编辑 Schema 。

以下部分还详细介绍了通过编写自己的 Schema 来读取和写入其他数据源所需的所有组件。 Resource 的模式写入 .rsd 文件中； Actions 的 Schema 写入 .rsb 文件中。该向导将这些文件放置在应用程序根目录的 API 子文件夹中。必须将自定义 Schema 放置在此文件夹中。

标记 Resource 列

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

列名称
数据类型
该列是否为主键

在 Schema 的 arc:info 块内，可以使用这些属性和其他属性来标记资源的列。

<arc:info title="NorthwindOData" desc="Access the Cars database through REST APIs." connection="SQLiteCars">
  <attr name="ID"           key="true" xs:type="int"      />
  <attr name="Make"                    xs:type="string"   />
  <attr name="Model"                   xs:type="string"   />
  <attr name="Cost"                    xs:type="double"   />
  <attr name="CreatedDate"             xs:type="datetime" />
  <attr name="InStock"                 xs:type="boolean"  />
</arc:info> 

获取数据

当收到 HTTP GET 请求时，应用程序执行 Schema 的 GET 方法。在此方法中，可以调用应用程序的内置操作来处理数据检索请求。以下是使用 HTTP GET 的搜索请求示例：

GET api.rsc/Cars?$filter=Make eq 'Honda'

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

SELECT \* FROM Cars WHERE Make = 'Honda'

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

<arc:script method="GET" >
  <arc:push op="apiSelect"/>
</arc:script> 

发布数据

当收到 POST 请求时，应用程序执行 Schema 的 POST 方法，可以在其中调用数据操作操作，例如插入。

例如，考虑以下 HTTP POST 请求：

POST api.rsc/Cars
{
  "Model": "Civic",
  "Make": "Honda"
}

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

INSERT INTO (Model, Make) VALUES ('Civic', 'Honda')

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

<arc:script method="POST">
  <arc:push op="apiInsert"/>
</arc:script>

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

放入数据

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

例如，考虑以下 PUT 请求：

PUT http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000') 
{ 
  "Model": "Civic"
} 

前面的请求映射到下面的 SQL 语句：

UPDATE Cars SET Model = 'Civic' WHERE Id = '1000'

在相应的 PUT 方法中，在调用操作之前会验证所需输入的主键。可以检查是否提供了输入，并使用 arc:validate 关键字提醒用户。

注意：可以指定脚本处理的多个 HTTP 方法。

此外，由于更新通常不返回数据，因此使用 arc:call 关键字来调用操作。可以调用 apiUpdate 操作来执行数据库更新。

<arc:script method="PUT,MERGE,PATCH">
  <arc:validate attr="Id" desc="An Id is required to update." />
  <arc:call op="apiUpdate"/>
</arc:script> 

删除数据

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

DELETE api.rsc/Cars('1000')

上述请求对应以下 SQL 查询：

DELETE FROM Cars WHERE Id = '1000'

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

<arc:script method="DELETE">
  <arc:validate attr="Id" desc="An Id is required to delete." />
  <arc:call op="apiDelete"/>
</arc:script>

Schema 示例

以下 Schema 支持对 SQLite 数据库中的 Cars 表进行读写访问。它包含通过 HTTP 访问数据库所需的所有组件。

<arc:script xmlns:arc="http://arc..com/ns/arcScript/2">

  <!-- Define columns and the database connection in the arc:info block -->
  <arc:info title="case" description="Create, Update, Query, and Delete Cars." connection="SQLiteCars"> 
    <attr name="Id"             key="true" xs:type="string"   />
    <attr name="Year"                      xs:type="int"      />
    <attr name="Make"                      xs:type="string"   />
    <attr name="Model"                     xs:type="string"   />
    <attr name="DatePurchased"             xs:type="datetime" />
  </arc:info>

  <!-- The GET method is executed when an HTTP GET is received. You can configure data retrieval operations here. The results of processing are pushed to the schema's output. -->
  <arc:script method="GET">
    <arc:push op="apiSelect"/>
  </arc:script>

  <!-- The POST method is executed when an HTTP POST is received. You can configure insert operations here. Use arc:push to return the Id of the new record. -->
  <arc:script method="POST">
  <arc:validate attr="Make" desc="Make and Model are required to insert a Car."/>
  <arc:validate attr="Model" desc="Make and Model are required to insert a Car."/>
    <arc:push op="apiInsert"/>
  </arc:script>

  <!-- The PUT method is executed when an HTTP PUT is received. You can configure update operations here. Within the script block, the primary key is used to update the record. Updates typically do not return data, so arc:call is used to invoke the operation. -->
  <arc:script method="PUT,MERGE,PATCH">
    <arc:validate attr="Id" desc="Id is required to update."/>
    <arc:call op="apiUpdate"/>
  </arc:script>

  <!-- The DELETE method is executed when an HTTP DELETE is received. You can configure delete operations here. Within the script block, the primary key is used to delete the record. -->
  <arc:script method="DELETE">
    <arc:validate attr="Id" desc="Id is required to delete."/>
    <arc:call op="apiDelete"/>
  </arc:script>

</arc:script>

关键字参考

有关本节中使用的以下关键字的详细信息，请参阅 ArcScript 参考：

典型定制

本节介绍一些常见的 Schema 修改。要编辑 Schema ，请单击“设置 > 资源”，然后单击要修改的资源旁边的“编辑”。

删除一列

从 arc:info 中删除 attr 元素会从资源中删除该列。这意味着 API 不会列出该列，并且的缓存不包含该列。

注意：删除要删除的列的整个 XML 元素非常重要。

更改资源列的数据类型

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

string
datetime
boolean
int
long
double

重命名资源列

要重命名资源列，请找到资源的元素并添加包含新列名称的 alias 属性。

注意：无法更改 name 属性。该值必须保持一致，应用程序才能维护到基础数据源中正确列的映射。

下面的示例将 Type 列重命名为 APIType：

<arc:info>
  <attr name="Type" alias="APIsType" xs:type="string" columnsize="40" readonly="True" key="False" />
  ...
</arc:info> 

重命名资源

可以通过更改应用程序根目录的 API 子文件夹中资源的 .rsd 文件的名称来重命名资源。

注意：arc:info 中的标题属性必须与基础数据源中的表名称保持相同。

更改数据源连接

可以使用 arc:info 中的 connection 属性来更改任何给定资源的连接。这使得从沙箱切换到生产实例变得容易。

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

<arc:info title="case" description="Create, Update, Query, and Delete the SQLite Cars database." connection="SQLiteCars">
  ... 
</arc:info>