REST API

Doubao 中英对照 REST API

Flowable REST 通用原则

安装与认证

Flowable 包含一个面向 Flowable 引擎的 REST API，可通过将 flowable-rest.war 文件部署到 Apache Tomcat 之类的 servlet 容器中来安装。此外，也可以在另一个 web 应用中使用它，方法是在你的应用中包含该 servlet（和/或其映射），并将所有 flowable-rest 依赖添加到 classpath。

默认情况下，Flowable 引擎会连接到内存中的 H2 数据库。你可以在 WEB-INF/META-INF/flowable-app 文件夹下的 flowable-app.properties 文件中更改数据库设置。REST API 使用 JSON 格式（http://www.json.org），并构建在 Spring MVC（http://docs.spring.io/spring/docs/current/spring-framework-reference/html/mvc.html）之上。

默认情况下，所有 REST 资源都要求一个具有 rest-access-api 权限的有效用户通过认证。如果希望任何有效用户都能调用 REST API，可以将 flowable.rest.app.authentication-mode 设置为 any-user（在旧版本 Flowable 中这是默认值）。

可以通过设置以下属性来配置一个能够访问 REST API 的默认用户：

flowable.rest.app.admin.user-id=rest-admin
flowable.rest.app.admin.password=test
flowable.rest.app.admin.first-name=Rest
flowable.rest.app.admin.last-name=Admin

REST 应用启动时，如果该用户不存在则创建它，否则获取它。该用户将被授予 access-rest-api 权限，默认访问 REST API 需要此权限。之后请勿忘记更改该用户的密码。如果未设置 flowable.rest.app.admin.user-id，则不会创建任何用户或权限。因此，在初始设置完成后，移除该属性并不会移除之前已配置的用户或权限。

使用基本 HTTP 访问认证，因此在执行请求时，你应始终包含一个 Authorization: Basic …== HTTP 头，或在请求 URL 中包含用户名和密码（例如 *http://username:password@localhost:8080/xyz*）。

我们建议你将基本认证与 HTTPS 结合使用。

配置

Flowable REST web 应用使用 Spring Java Configuration 来启动 Flowable Form 引擎，使用 Spring security 定义基本认证安全性，并定义用于特定变量处理的变量转换器。通过修改 flowable-app.properties 文件可以定义少量属性，该文件位于 WEB-INF/META-INF/flowable-app/flowable-app.properties 文件夹。如果需要更高级的配置选项，可以在 WEB-INF/classes 文件夹下的 flowable-custom-context.xml 文件中覆盖默认的 Spring bean（XML 方式）。该文件中已以注释形式给出了一个示例配置。这里也是覆盖默认 RestResponseFactory 的地方，方法是定义一个名为 restResponsefactory 的新 Spring bean，并为其使用你自定义的实现类。

在 Tomcat 中使用

由于 Tomcat 的默认安全属性，默认不允许转义的正斜杠（%2F 和 %5C）（会返回 400 结果）。这可能会影响部署资源及其 data-URL，因为该 URL 可能包含转义的正斜杠。

当遇到意外的 400 结果问题时，设置以下系统属性：

-Dorg.apache.tomcat.util.buf.UDecoder.ALLOW_ENCODED_SLASH=true

对于下文所述的 HTTP 请求，最佳实践是始终将 Accept 和 Content-Type（在 POST/PUT JSON 的情况下）头设置为 application/json。

方法与返回码

HTTP 方法与对应操作

方法	操作
GET	获取单个资源或获取资源集合。
POST	创建新资源。也用于执行请求结构过于复杂、无法放入 GET 请求查询 URL 的资源查询。
PUT	更新已有资源的属性。也用于对已有资源调用操作。
DELETE	删除已有资源。

HTTP 方法响应码

响应	描述
200 - Ok	操作成功，并已返回响应（GET 和 PUT 请求）。
201 - Created	操作成功，实体已创建并在响应体中返回（POST 请求）。
204 - No content	操作成功，实体已删除，因此不返回响应体（DELETE 请求）。
401 - Unauthorized	操作失败。该操作要求设置 Authentication 头。如果请求中已包含该头，则提供的凭据无效，或用户无权执行此操作。
403 - Forbidden	该操作被禁止，不应重试。这意味着是授权问题而非认证问题，即该操作不被允许。例如：删除属于正在运行流程的任务是不允许的，并且无论用户或流程/任务状态如何，都永远不允许。
404 - Not found	操作失败。未找到请求的资源。
405 - Method not allowed	操作失败。该方法不允许用于此资源。例如，尝试更新（PUT）一个部署资源将导致 405 状态。
409 - Conflict	操作失败。该操作导致对某资源的更新，而该资源已被另一操作更新，使得本次更新不再有效。也可能表示正在一个集合中创建资源，而该集合中已存在具有该标识符的资源。
415 - Unsupported Media Type	操作失败。请求体包含不支持的媒体类型。当请求体 JSON 包含无法转换的不支持内容类型时也会出现。

除非请求的是二进制内容（例如部署资源数据），否则 HTTP 响应的媒体类型始终为 application/json；此时使用该内容自身的媒体类型。

错误响应体

发生错误时（客户端和服务端均包括，即 4XX 和 5XX 状态码），响应体包含一个描述所发生错误的对象。下面是任务未找到时 404 状态的示例：

{
  "statusCode" : 404,
  "errorMessage" : "Could not find a task with id '444'."
}

请求参数

URL 片段

作为 URL 一部分的参数（例如 http://host/flowable-rest/process-api/repository/deployments/\{deploymentId} 中的 deploymentId 参数）需要被正确转义（参见 URL 编码或百分号编码）。

Rest URL 查询参数

作为查询字符串添加到 URL 中的参数（例如 http://host/flowable-rest/process-api/repository/deployments?name=Deployment 中使用的 name 参数）可以具有以下类型，并在相应的 REST API 文档中说明：

URL 查询参数类型

类型	格式
String	纯文本参数。可包含 URL 中允许的任何有效字符。对于 XXXLike 参数，字符串应包含通配符 %（需正确进行 URL 编码）。这使你可以指定 like 搜索的意图。例如，'Tas%' 匹配所有以 'Tas' 开头的值。
Integer	表示整数值的参数。只能包含数值型非小数，介于 -2.147.483.648 和 2.147.483.647 之间。
Long	表示 long 值的参数。只能包含数值型非小数，介于 -9.223.372.036.854.775.808 和 9.223.372.036.854.775.807 之间。
Boolean	表示布尔值的参数。可以为 true 或 false。除此之外的所有其他值都会导致 '405 - Bad request' 响应。
Date	表示日期值的参数。使用 ISO-8601 日期格式（参见维基百科上的 ISO-8601），同时使用时间和日期组件（例如 2013-04-03T23:45Z）。

JSON 请求体参数

JSON 参数类型

类型	格式
String	纯文本参数。对于 XXXLike 参数，字符串应包含通配符 %。这使你可以指定 like 搜索的意图。例如，'Tas%' 匹配所有以 'Tas' 开头的值。
Integer	表示整数值的参数，使用 JSON 数字。只能包含数值型非小数，介于 -2.147.483.648 和 2.147.483.647 之间。
Long	表示 long 值的参数，使用 JSON 数字。只能包含数值型非小数，介于 -9.223.372.036.854.775.808 和 9.223.372.036.854.775.807 之间。
Date	表示日期值的参数，使用 JSON 文本。使用 ISO-8601 日期格式（参见维基百科上的 ISO-8601），同时使用时间和日期组件（例如 2013-04-03T23:45Z）。

分页与排序

分页和排序参数可以作为查询字符串添加到 URL 中（例如 http://host/flowable-rest/process-api/repository/deployments?sort=name 中使用的 name 参数）。

变量查询 JSON 参数

参数	默认值	描述
sort	因查询实现而异	排序键的名称，其默认值和允许值因查询实现而异。
order	asc	排序顺序，可以为 'asc' 或 'desc'。
start	0	允许对结果分页的参数。默认结果从 0 开始。
size	10	允许对结果分页的参数。默认大小为 10。

注意

请记住，start 参数用作查询的偏移量。例如，要分三页、每页三项（共 9 项）获取任务，我们会使用：

GET /runtime/tasks?start=0&size=3
GET /runtime/tasks?start=3&size=3
GET /runtime/tasks?start=6&size=3

部署

使用 Tomcat 时，请阅读在 Tomcat 中使用。

Event Registry 部署列表

GET event-registry-repository/deployments

URL 查询参数

参数	是否必需	值	描述
name	否	String	仅返回具有给定名称的部署。
nameLike	否	String	仅返回名称类似于给定名称的部署。
category	否	String	仅返回具有给定类别的部署。
categoryNotEquals	否	String	仅返回不具有给定类别的部署。
parentDeploymentId	否	String	仅返回具有给定父部署 id 的部署。
parentDeploymentIdLike	否	String	仅返回父部署 id 类似于给定值的部署。
tenantId	否	String	仅返回具有给定 tenantId 的部署。
tenantIdLike	否	String	仅返回 tenantId 类似于给定值的部署。
withoutTenantId	否	Boolean	如果为 true，仅返回未设置 tenantId 的部署。如果为 false，忽略 withoutTenantId 参数。
sort	否	'id'（默认）、'name'、'deploytime' 或 'tenantId'	排序属性，与 'order' 一起使用。

REST 响应码

响应码	描述
200	表示请求成功。

成功响应体：

{
  "data": [
    {
      "id": "03ab310d-c1de-11e6-a4f4-62ce84ef239e",
      "name": null,
      "deploymentTime": "2016-12-14T10:16:37.000+01:00",
      "category": null,
      "url": "http://localhost:8080/flowable-rest/event-registry-api/event-registry-repository/deployments/03ab310d-c1de-11e6-a4f4-62ce84ef239e",
      "parentDeploymentId": "17510",
      "tenantId": ""
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "id",
  "order": "asc",
  "size": 1
}

获取 Event Registry 部署

GET event-registry-repository/deployments/{deploymentId}

获取部署 - URL 参数

参数	是否必需	值	描述
deploymentId	是	String	要获取的部署的标识符。

获取部署 - 响应码

响应码	描述
200	表示已找到并返回该部署。
404	表示未找到请求的部署。

成功响应体：

{
  "id": "03ab310d-c1de-11e6-a4f4-62ce84ef239e",
  "name": null,
  "deploymentTime": "2016-12-14T10:16:37.000+01:00",
  "category": null,
  "url": "http://localhost:8080/flowable-rest/event-registry-api/event-registry-repository/deployments/03ab310d-c1de-11e6-a4f4-62ce84ef239e",
  "parentDeploymentId": "17510",
  "tenantId": ""
}

创建新的 Event Registry 部署

POST event-registry-repository/deployments

请求体：

请求体应包含 multipart/form-data 类型的数据。请求中应恰好有一个文件；任何额外文件都将被忽略。部署名称即为传入的文件字段的名称。

可以在请求体中传入一个名为 tenantId 的额外参数（表单字段）。该字段的值将用作本次部署所属租户的标识符。

创建新的 Event 部署 - 响应码

响应码	描述
201	表示部署已创建。
400	表示请求体中没有内容，或内容的 mime 类型不支持部署。状态描述包含更多信息。

成功响应体：

{
  "id": "03ab310d-c1de-11e6-a4f4-62ce84ef239e",
  "name": "newDeployment1",
  "deploymentTime": "2016-12-14T10:16:37.000+01:00",
  "category": null,
  "url": "http://localhost:8080/flowable-rest/event-registry-api/event-registry-repository/deployments/03ab310d-c1de-11e6-a4f4-62ce84ef239e",
  "parentDeploymentId": "17510",
  "tenantId" : "myTenant"
}

删除 Event Registry 部署

DELETE event-registry-repository/deployments/{deploymentId}

删除 Event Registry 部署 - URL 参数

参数	是否必需	值	描述
deploymentId	是	String	要删除的部署的标识符。

删除 Event Registry 部署 - 响应码

响应码	描述
204	表示已找到部署并已删除。响应体有意为空。
404	表示未找到请求的部署。

获取 Event Registry 部署资源内容

GET event-registry-repository/deployments/{deploymentId}/resourcedata/{resourceId}

获取部署资源内容 - URL 参数

参数	是否必需	值	描述
deploymentId	是	String	请求资源所属部署的标识符。
resourceId	是	String	要获取数据的资源的标识符。如果 resourceId 包含正斜杠，请务必对其进行 URL 编码。例如，使用 'events%2Fmy-event.event' 而非 'events/my-event.event'。

获取部署资源内容 - 响应码

响应码	描述
200	表示部署和资源均已找到，并已返回资源数据。
404	表示未找到请求的部署，或部署中不存在具有给定标识符的资源。状态描述包含更多信息。

成功响应体：

响应体将包含请求资源的二进制资源内容。响应 content-type 将与资源 'mimeType' 属性中返回的类型相同。此外，还会设置 content-disposition 头，使浏览器下载该文件而非显示它。

Event 定义

Event 定义列表

GET event-registry-repository/event-definitions

Event 定义列表 - URL 参数

参数	是否必需	值	描述
version	否	integer	仅返回具有给定版本的 Event 定义。
name	否	String	仅返回具有给定名称的 Event 定义。
nameLike	否	String	仅返回名称类似于给定名称的 Event 定义。
key	否	String	仅返回具有给定 key 的 Event 定义。
keyLike	否	String	仅返回 key 类似于给定 key 的 Event 定义。
resourceName	否	String	仅返回具有给定资源名的 Event 定义。
resourceNameLike	否	String	仅返回资源名类似于给定名称的 Event 定义。
category	否	String	仅返回具有给定类别的 Event 定义。
categoryLike	否	String	仅返回类别类似于给定名称的 Event 定义。
categoryNotEquals	否	String	仅返回不具有给定类别的 Event 定义。
deploymentId	否	String	仅返回属于具有给定标识符的部署的 Event 定义。
latest	否	Boolean	仅返回最新的 Event 定义版本。只能与 'key' 和 'keyLike' 参数一起使用，使用任何其他参数将导致 400 响应。
sort	否	'name'（默认）、'id'、'key'、'category'、'deploymentId' 和 'tenantId'	排序属性，与 'order' 一起使用。

Event 定义列表 - 响应码

响应码	描述
200	表示请求成功，并返回 Event 定义
400	表示传入的参数格式错误，或 'latest' 与 'key' 和 'keyLike' 以外的参数一起使用。状态消息包含更多信息。

成功响应体：

{
  "data": [
        {
      "id": "46b0379c-c0a1-11e6-bc93-6ab56fad108a",
      "url": "http://localhost:8080/flowable-rest/event-registry-api/event-registry-repository/event-definitions/46b0379c-c0a1-11e6-bc93-6ab56fad108a",
      "category": null,
      "name": "Event Definition One",
      "key": "EventDefinitionOne",
      "description": null,
      "version": 3,
      "resourceName": "EventDefinitionOne.event",
      "deploymentId": "46aa6b3a-c0a1-11e6-bc93-6ab56fad108a",
      "parentDeploymentId": "5001",
      "tenantId": ""
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "name",
  "order": "asc",
  "size": 1
}

获取 Event 定义

GET event-registry-repository/event-definitions/{eventDefinitionId}

获取 Event 定义 - URL 参数

参数	是否必需	值	描述
eventDefinitionId	是	String	要获取的 Event 定义的标识符。

获取 Event 定义 - 响应码

响应码	描述
200	表示已找到并返回该 Event 定义。
404	表示未找到请求的 Event 定义。

成功响应体：

{
  "id": "46b0379c-c0a1-11e6-bc93-6ab56fad108a",
  "url": "http://localhost:8080/flowable-rest/event-registry-api/event-registry-repository/event-definitions/46b0379c-c0a1-11e6-bc93-6ab56fad108a",
  "category": null,
  "name": "Event Definition One",
  "key": "EventDefinitionOne",
  "description": null,
  "version": 3,
  "resourceName": "EventDefinitionOne.event",
  "deploymentId": "46aa6b3a-c0a1-11e6-bc93-6ab56fad108a",
  "parentDeploymentId": "5001",
  "tenantId": ""
}

获取 Event 定义资源内容

GET event-registry-repository/event-definitions/{eventDefinitionId}/resourcedata

获取 Event 定义资源内容 - URL 参数

参数	是否必需	值	描述
eventDefinitionId	是	String	要获取其资源数据的 Event 定义的标识符。

响应：

响应码与 GET event-registry-repository/deployments/{deploymentId}/resourcedata/{resourceId} 完全相同。

获取 Event 定义模型

GET event-registry-repository/event-definitions/{eventDefinitionId}/model

获取 Event 定义模型 - URL 参数

参数	是否必需	值	描述
eventDefinitionId	是	String	要获取其模型的 Event 定义的标识符。

获取 Event 定义模型 - 响应码

响应码	描述
200	表示已找到 Event 定义并返回模型。
404	表示未找到请求的 Event 定义。

响应体：
响应体是 org.flowable.eventregistry.model.EventModel 的 JSON 表示。

{
   "key": "myEvent",
   "name": "My event",
   "correlationParameters": [
      {
        "name": "customerId",
        "type": "string"
      }
   ],
   "payload": [
      {
        "name": "payload1",
        "type": "string"
      },
      {
        "name": "payload2",
        "type": "integer"
      }
   ]
}

Channel 定义

Channel 定义列表

GET event-registry-repository/channel-definitions

Channel 定义列表 - URL 参数

参数	是否必需	值	描述
version	否	integer	仅返回具有给定版本的 Channel 定义。
name	否	String	仅返回具有给定名称的 Channel 定义。
nameLike	否	String	仅返回名称类似于给定名称的 Channel 定义。
key	否	String	仅返回具有给定 key 的 Channel 定义。
keyLike	否	String	仅返回 key 类似于给定 key 的 Channel 定义。
resourceName	否	String	仅返回具有给定资源名的 Channel 定义。
resourceNameLike	否	String	仅返回资源名类似于给定名称的 Channel 定义。
category	否	String	仅返回具有给定类别的 Channel 定义。
categoryLike	否	String	仅返回类别类似于给定名称的 Channel 定义。
categoryNotEquals	否	String	仅返回不具有给定类别的 Channel 定义。
deploymentId	否	String	仅返回属于具有给定标识符的部署的 Channel 定义。
latest	否	Boolean	仅返回最新的 Channel 定义版本。只能与 'key' 和 'keyLike' 参数一起使用，使用任何其他参数将导致 400 响应。
sort	否	'name'（默认）、'id'、'key'、'category'、'deploymentId' 和 'tenantId'	排序属性，与 'order' 一起使用。

Channel 定义列表 - 响应码

响应码	描述
200	表示请求成功，并返回 Channel 定义
400	表示传入的参数格式错误，或 'latest' 与 'key' 和 'keyLike' 以外的参数一起使用。状态消息包含更多信息。

成功响应体：

{
  "data": [
        {
      "id": "46b0379c-c0a1-11e6-bc93-6ab56fad108a",
      "url": "http://localhost:8080/flowable-rest/event-registry-api/event-registry-repository/channel-definitions/46b0379c-c0a1-11e6-bc93-6ab56fad108a",
      "category": null,
      "name": "Channel Definition One",
      "key": "ChannelDefinitionOne",
      "description": null,
      "version": 3,
      "resourceName": "ChannelDefinitionOne.channel",
      "deploymentId": "46aa6b3a-c0a1-11e6-bc93-6ab56fad108a",
      "parentDeploymentId": "5001",
      "tenantId": ""
    }
  ],
  "total": 1,
  "start": 0,
  "sort": "name",
  "order": "asc",
  "size": 1
}

获取 Channel 定义

GET event-registry-repository/channel-definitions/{channelDefinitionId}

获取 Channel 定义 - URL 参数

参数	是否必需	值	描述
channelDefinitionId	是	String	要获取的 Channel 定义的标识符。

获取 Channel 定义 - 响应码

响应码	描述
200	表示已找到并返回该 Channel 定义。
404	表示未找到请求的 Channel 定义。

成功响应体：

{
  "id": "46b0379c-c0a1-11e6-bc93-6ab56fad108a",
  "url": "http://localhost:8080/flowable-rest/event-registry-api/event-registry-repository/channel-definitions/46b0379c-c0a1-11e6-bc93-6ab56fad108a",
  "category": null,
  "name": "Channel Definition One",
  "key": "ChannelDefinitionOne",
  "description": null,
  "version": 3,
  "resourceName": "ChannelDefinitionOne.channel",
  "deploymentId": "46aa6b3a-c0a1-11e6-bc93-6ab56fad108a",
  "parentDeploymentId": "5001",
  "tenantId": ""
}

获取 Channel 定义资源内容

GET event-registry-repository/channel-definitions/{channelDefinitionId}/resourcedata

获取 Channel 定义资源内容 - URL 参数

参数	是否必需	值	描述
channelDefinitionId	是	String	要获取其资源数据的 Channel 定义的标识符。

响应：

响应码与 GET event-registry-repository/deployments/{deploymentId}/resourcedata/{resourceId} 完全相同。

获取 Channel 定义模型

GET event-registry-repository/channel-definitions/{channelDefinitionId}/model

获取 Channel 定义模型 - URL 参数

参数	是否必需	值	描述
channelDefinitionId	是	String	要获取其模型的 Channel 定义的标识符。

获取 Channel 定义模型 - 响应码

响应码	描述
200	表示已找到 Channel 定义并返回模型。
404	表示未找到请求的 Channel 定义。

响应体：
响应体是 org.flowable.eventregistry.model.ChannelModel 的 JSON 表示。

{
   "key": "myChannel",
   "category": "channel",
   "name": "My channel",
   "description": "My channel description",
   "channelType": "inbound",
   "type": "jms",
   "destination": "testQueue",
   "deserializerType": "json",
   "channelEventKeyDetection": {
      "fixedValue": "myEvent"
   }
}

Event Registry 服务

发送事件

POST event-registry-runtime/event-instances

请求体：

{
  "eventDefinitionKey": "myEvent",
  "eventPayload": {
      "customerName": "John Doe",
      "productName": "Laptop"
  },
  "tenantId": "tenant1"
}

除了事件定义 key，也可以使用事件定义 id。

发送事件时没有响应体。

发送事件 - 响应码

响应码	描述
201	表示事件已发送。

引擎

获取 Event Registry 引擎信息

GET event-registry-management/engine

返回此 REST 服务中所用 Event Registry 引擎的只读视图。

成功响应体：

{
   "name":"default",
   "version":"6.6.0"
}

获取引擎信息 - 响应码

响应码	描述
200	表示已返回引擎信息。

Flowable REST 通用原则​

安装与认证​

配置​

在 Tomcat 中使用​

方法与返回码​

错误响应体​

请求参数​

URL 片段​

Rest URL 查询参数​

JSON 请求体参数​

分页与排序​

部署​

Event Registry 部署列表​

获取 Event Registry 部署​

创建新的 Event Registry 部署​

删除 Event Registry 部署​

获取 Event Registry 部署资源内容​

Event 定义​

Event 定义列表​

获取 Event 定义​

获取 Event 定义资源内容​

获取 Event 定义模型​

Channel 定义​

Channel 定义列表​

获取 Channel 定义​

获取 Channel 定义资源内容​

获取 Channel 定义模型​

Event Registry 服务​

发送事件​

引擎​

获取 Event Registry 引擎信息​

Flowable REST 通用原则

安装与认证

配置

在 Tomcat 中使用

方法与返回码

错误响应体

请求参数

URL 片段

Rest URL 查询参数

JSON 请求体参数

分页与排序

部署

Event Registry 部署列表

获取 Event Registry 部署

创建新的 Event Registry 部署

删除 Event Registry 部署

获取 Event Registry 部署资源内容

Event 定义

Event 定义列表

获取 Event 定义

获取 Event 定义资源内容

获取 Event 定义模型

Channel 定义

Channel 定义列表

获取 Channel 定义

获取 Channel 定义资源内容

获取 Channel 定义模型

Event Registry 服务

发送事件

引擎

获取 Event Registry 引擎信息