API docs by Redocly

算子 (0.1.3)

Download OpenAPI specification:

算子（operator）是把一段能力注册成可复用、可版本化、可发布的产物。 function.yaml 里的 /function/execute 是「跑一段临时代码」； 这里是「把它固化下来，带上元数据、执行控制与生命周期」。

两种元数据类型，注册时用 operator_metadata_type 指定，决定哪些字段必填：

类型 算子是什么 必填
function 一段 Python 代码 function_input（含 code、入参 / 出参定义）
openapi 一个已有的 HTTP 接口 data（OpenAPI JSON/YAML 原文）

生命周期：unpublish（新建未发布）→ published（已发布）→ offline（下架）， 已发布后再改会进 editing。每次编辑产生新 version，历史版本可查、可回看。 发布后的算子才会出现在算子市场（/operator/market）。

业务域：注册、列表、删除、市场相关接口要求 x-business-domain 头， 算子按业务域隔离。

时间戳一律是纳秒：本服务所有 *_time 字段用 time.Now().UnixNano() 生成， 形如 1784880971306127803。按毫秒解析会得到 1970 年附近的日期。

认证：Authorization: Bearer <token>（OAuth access token 或 bak_ 前缀的 AppKey）。

Operator

注册算子

创建一个新算子。operator_metadata_type 决定必填字段——function 走 function_input，openapi 走 data。

direct_publish=true 表示注册完直接进入 published，跳过手工发布一步。

Authorizations:
OAuth2AppKey
header Parameters
x-business-domain
required
string

业务域 ID。算子按业务域隔离，缺失返回 400。

Request Body schema: application/json
required
operator_metadata_type
required
string (MetadataType)
Enum: "openapi" "function"

元数据类型。function 走 function_input，openapi 走 data， 二者决定注册时哪些字段必填。

description
string

算子描述。

object (OperatorInfo)
object (OperatorExecuteControl)

执行控制：超时与重试。

object (FunctionInput)

函数类算子的定义。**operator_metadata_type=function 时必填**。 代码约定与 function.yaml 一致：入口函数必须叫 handler。

data
string

OpenAPI 原文（JSON 或 YAML 字符串）。 operator_metadata_type=openapi 时必填。

object

扩展信息，原样存取。

direct_publish
boolean

注册后直接发布，跳过手工发布一步。

Responses

Request samples

Content type
application/json
Example
{
  • "operator_metadata_type": "function",
  • "description": "求和",
  • "operator_info": {
    },
  • "function_input": {
    },
  • "direct_publish": true
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "operator_id": "string",
  • "version": "string",
  • "error": null
}

编辑算子

改已有算子。方法是 POST 不是 PUT，算子由请求体里的 operator_id 指定。

编辑已发布的算子会把状态推进到 editing，并产生新的 version； 原来那个已发布版本仍在历史里可查。

Authorizations:
OAuth2AppKey
Request Body schema: application/json
required
operator_id
required
string <uuid>

算子 ID。

name
string

算子名称。

description
string

算子描述。

object (OperatorInfoEdit)

编辑时的算子信息，比 OperatorInfo 少了只读的 category_name。

object (OperatorExecuteControl)

执行控制：超时与重试。

metadata_type
string (MetadataType)
Enum: "openapi" "function"

元数据类型。function 走 function_input，openapi 走 data， 二者决定注册时哪些字段必填。

object (FunctionInputEdit)

编辑时的函数定义，比 FunctionInput 少了 name / description。

data
string

OpenAPI 原文，编辑 openapi 类算子时用。

object

扩展信息。

Responses

Request samples

Content type
application/json
{
  • "operator_id": "fa9de6bb-1df8-4ba6-9e6d-1172fbf7e166",
  • "name": "string",
  • "description": "string",
  • "operator_info": {
    },
  • "operator_execute_control": {
    },
  • "metadata_type": "openapi",
  • "function_input": {
    },
  • "data": "string",
  • "extend_info": { }
}

Response samples

Content type
application/json
{
  • "operator_id": "string",
  • "version": "string",
  • "status": "unpublish"
}

用 OpenAPI 原文整体更新算子

用一份新的元数据整体覆盖算子，请求体是注册请求再加一个 operator_id。 与 /operator/info 的差别：那边是按字段改，这边是整包替换。

Authorizations:
OAuth2AppKey
Request Body schema: application/json
required
operator_metadata_type
required
string (MetadataType)
Enum: "openapi" "function"

元数据类型。function 走 function_input，openapi 走 data， 二者决定注册时哪些字段必填。

description
string

算子描述。

object (OperatorInfo)
object (OperatorExecuteControl)

执行控制：超时与重试。

object (FunctionInput)

函数类算子的定义。**operator_metadata_type=function 时必填**。 代码约定与 function.yaml 一致：入口函数必须叫 handler。

data
string

OpenAPI 原文（JSON 或 YAML 字符串）。 operator_metadata_type=openapi 时必填。

object

扩展信息，原样存取。

direct_publish
boolean

注册后直接发布，跳过手工发布一步。

operator_id
required
string <uuid>

要更新的算子 ID。

Responses

Request samples

Content type
application/json
{
  • "operator_metadata_type": "openapi",
  • "description": "string",
  • "operator_info": {
    },
  • "operator_execute_control": {
    },
  • "function_input": {
    },
  • "data": "string",
  • "extend_info": { },
  • "direct_publish": true,
  • "operator_id": "fa9de6bb-1df8-4ba6-9e6d-1172fbf7e166"
}

Response samples

Content type
application/json
{
  • "status": "success",
  • "operator_id": "string",
  • "version": "string",
  • "error": null
}

分页查询算子

按业务域分页列出算子，支持按名称、状态、分类、创建人、算子类型过滤。

page_size 传负数等价于「不分页、全量返回」（服务端会把它翻译成 all=true）；正常范围是 1–100。

Authorizations:
OAuth2AppKey
query Parameters
page
integer >= 1
Default: 1

页码，从 1 开始。

page_size
integer <= 100
Default: 10

每页数量，上限 100。传负数等价于不分页全量返回。

sort_by
string
Default: "update_time"
Enum: "update_time" "create_time" "name"

排序字段。

sort_order
string
Default: "desc"
Enum: "asc" "desc"

排序方向。

name
string

按名称过滤。

status
string (BizStatus)
Enum: "unpublish" "published" "offline" "editing"

按状态过滤。

create_user
string

按创建人过滤。

category
string

按分类过滤，取值见 GET /operator/category。

operator_type
string (OperatorType)
Enum: "basic" "composite"

按算子类型过滤。

is_data_source
boolean

只看 / 排除数据源算子。

all
boolean

忽略分页返回全部。

header Parameters
x-business-domain
required
string

业务域 ID。算子按业务域隔离，缺失返回 400。

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "page": 1,
  • "page_size": 10,
  • "total_pages": 0,
  • "has_next": false,
  • "has_prev": false,
  • "data": [ ]
}

查询算子详情

按 ID 取算子的当前版本详情，含元数据与执行控制。

Authorizations:
OAuth2AppKey
path Parameters
operator_id
required
string

算子 ID。

Responses

Response samples

Content type
application/json
{
  • "business_domain_id": "string",
  • "operator_id": "string",
  • "name": "string",
  • "version": "string",
  • "status": "unpublish",
  • "metadata_type": "openapi",
  • "metadata": {
    },
  • "operator_info": {
    },
  • "operator_execute_control": {
    },
  • "extend_info": { },
  • "is_internal": true,
  • "tag": 0,
  • "create_user": "string",
  • "create_time": 0,
  • "update_user": "string",
  • "update_time": 0,
  • "release_user": "string",
  • "release_time": 0
}

按 ID 批量取算子名

给一批算子 ID，换回它们的名称。前端的对象级授权页用它回显名字。

不存在的 ID 会被静默略过，不报错也不占位——调用方要自己比对哪些没回来。 ids 传空数组时返回空 entries。

工具箱、Skill 有同名同形的接口（/tool-box/names、/skills/names）， 契约完全一致。

Authorizations:
OAuth2AppKey
Request Body schema: application/json
required
ids
Array of strings

待取名的 ID 列表。空列表返回空 entries。

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
{
  • "entries": [
    ]
}

批量改算子状态

发布 / 下架 / 撤回。请求体是数组，一次可以改多个算子。

把状态改成 published 即发布，算子随即出现在算子市场；改成 offline 即从市场下架。

Authorizations:
OAuth2AppKey
Request Body schema: application/json
required
Array
operator_id
required
string <uuid>
status
required
string (BizStatus)
Enum: "unpublish" "published" "offline" "editing"

生命周期状态：unpublish 未发布、published 已发布、offline 已下架、 editing 已发布后编辑中。

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "Public.BadRequest",
  • "description": "string",
  • "solution": "string",
  • "link": "string",
  • "details": null
}

批量删除算子

DELETE 带请求体，且请求体是数组——不是常见的路径参数删除， 很多 HTTP 客户端默认不给 DELETE 发 body，注意。

Authorizations:
OAuth2AppKey
header Parameters
x-business-domain
required
string

业务域 ID。算子按业务域隔离，缺失返回 400。

Request Body schema: application/json
required
Array
operator_id
required
string <uuid>

算子 ID。

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "Public.BadRequest",
  • "description": "string",
  • "solution": "string",
  • "link": "string",
  • "details": null
}

调试算子

用指定版本跑一次算子，看真实请求与响应。调的是某个具体 version， 不是「当前版本」——version 必填。

请求参数按 HTTP 的四个位置分开传：header / query / path / body。 函数类算子只用 body。

Authorizations:
OAuth2AppKey
Request Body schema: application/json
required
operator_id
required
string <uuid>
version
required
string <uuid>

要调试的版本 ID。必填，调的是具体版本而非「当前版本」。

timeout
integer

超时（秒）。

object

请求头参数。

object

查询参数。

object

路径参数。

body
any

请求体。函数类算子只用这个。

Responses

Request samples

Content type
application/json
{
  • "operator_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  • "version": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  • "timeout": 30,
  • "body": {
    }
}

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "headers": { },
  • "body": null,
  • "error": "string"
}

查询算子历史版本列表

列出该算子已发布过的版本。

Authorizations:
OAuth2AppKey
path Parameters
operator_id
required
string

算子 ID。

Responses

Response samples

Content type
application/json
[
  • {
    }
]

查询算子指定历史版本详情

取某个已发布版本的完整定义，用于版本对比或回看。

Authorizations:
OAuth2AppKey
path Parameters
operator_id
required
string

算子 ID。

version
required
string

版本 ID。

query Parameters
tag
integer

版本号（递增序号），与 version 二选一定位。

Responses

Response samples

Content type
application/json
{
  • "business_domain_id": "string",
  • "operator_id": "string",
  • "name": "string",
  • "version": "string",
  • "status": "unpublish",
  • "metadata_type": "openapi",
  • "metadata": {
    },
  • "operator_info": {
    },
  • "operator_execute_control": {
    },
  • "extend_info": { },
  • "is_internal": true,
  • "tag": 0,
  • "create_user": "string",
  • "create_time": 0,
  • "update_user": "string",
  • "update_time": 0,
  • "release_user": "string",
  • "release_time": 0
}

算子市场列表

市场只收已发布 / 已下架的算子——status 的可选值只有 published 与 offline，传 unpublish / editing 会 400。这是它与 /operator/info/list 的关键差别：那边看的是工作区的全部算子。

Authorizations:
OAuth2AppKey
query Parameters
page
integer >= 1
Default: 1

页码，从 1 开始。

page_size
integer <= 100
Default: 10

每页数量，上限 100。传负数等价于不分页全量返回。

sort_by
string
Default: "update_time"
Enum: "update_time" "create_time" "name"

排序字段。

sort_order
string
Default: "desc"
Enum: "asc" "desc"

排序方向。

status
string
Enum: "published" "offline"

市场内的状态过滤，只接受这两个值。

name
string

按名称过滤。

create_user
string

按创建人过滤。

release_user
string

按发布人过滤。

category
string

按分类过滤。

all
boolean

忽略分页返回全部。

header Parameters
x-business-domain
required
string

业务域 ID。算子按业务域隔离，缺失返回 400。

Responses

Response samples

Content type
application/json
{
  • "total": 0,
  • "page": 0,
  • "page_size": 0,
  • "total_pages": 0,
  • "has_next": true,
  • "has_prev": true,
  • "data": [
    ]
}

算子市场详情

在市场视角查看某个算子的详情。

Authorizations:
OAuth2AppKey
path Parameters
operator_id
required
string

算子 ID。

header Parameters
x-business-domain
required
string

业务域 ID。算子按业务域隔离，缺失返回 400。

Responses

Response samples

Content type
application/json
{
  • "business_domain_id": "string",
  • "operator_id": "string",
  • "name": "string",
  • "version": "string",
  • "status": "unpublish",
  • "metadata_type": "openapi",
  • "metadata": {
    },
  • "operator_info": {
    },
  • "operator_execute_control": {
    },
  • "extend_info": { },
  • "is_internal": true,
  • "tag": 0,
  • "create_user": "string",
  • "create_time": 0,
  • "update_user": "string",
  • "update_time": 0,
  • "release_user": "string",
  • "release_time": 0
}

算子分类列表

返回可用的算子分类。category_type 是机器可读值（过滤与注册时填它）， name 是随请求语言本地化的显示名。

Authorizations:
OAuth2AppKey

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]