Create custom operator

Create a custom operator that can be used in workflows. Code type operators require source code or source file IDs; built-in binding types use base operators and binding configurations.

POST https://moi.matrixorigin.cn/newmoi/workflow/v2/custom-operators

Preparation before calling

Prepare a personal access token and target workspace ID that has access to the target workspace. First decide whether to create a code type or a built-in binding type, and prepare the corresponding implementation content.

Request body

namestringRequired
Operator name.
identifierstringRequired
Operator ID.
descriptionstringRequired
Operator description.
kindstring
Operator type; when omitted, it is the code type.
languagestring
The implementation language of the code type; currently only python is supported.
handlerstring
Handler for the code type. Python processing functions use module and function names, such as main.handle; the corresponding function must accept three parameters: workspace_id, sdk and input.
input_schemaobjectRequired
Input definition. description must be provided for each properties entry.
output_schemaobjectRequired
Output definition. description must be provided for each properties entry.
versionstring
Version for the code type.
isolation_levelstring
Isolation configuration for the code type.
codestring
Source code for the code type; provide it instead of source_file_id.
source_file_idstring
Source file ID for the code type; provide it instead of code.
base_node_idstring
Base operator ID required by the built-in binding type.
base_node_versionstring
Base operator version required by the built-in binding type.
binding_configobject
Binding configuration required by the built-in binding type.
node_idstring
Custom workflow operator ID. When omitted, the service generates it from the target workspace and identifier.
enabledboolean
Whether to enable initially.
catalog_idinteger
Associated catalog ID.
database_idinteger
Associated database ID.

Request example

curl -X POST "https://moi.matrixorigin.cn/newmoi/workflow/v2/custom-operators" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Text Counter",
    "identifier": "text_counter",
    "node_id": "moi:custom.operator:$WORKSPACE_ID:text_counter",
    "description": "Counts the number of characters in the input text.",
    "language": "python",
    "handler": "main.handle",
    "input_schema": {
      "type": "object",
      "properties": {
        "text": {
          "type": "string",
          "description": "The text to count."
        }
      }
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "count": {
          "type": "integer",
          "description": "Character count."
        }
      }
    },
    "code": "def handle(workspace_id, sdk, input):\n    return {\"count\": len(input[\"text\"])}"
  }'

Successful response

The response returns the ID and configuration of the newly created operator. Save the operator ID, which will be used for subsequent viewing, updating, trial running, activation, deactivation, and deletion.

The response fields are as follows.

codestring
OK on success.
msgstring
OK on success.
data.idinteger
Newly created custom operator ID.
data.node_idstring
Operator ID in the workflow.
data.namestring
Operator name.
data.identifierstring
Operator ID.
data.descriptionstring
Operator description; returned if there is a value.
data.languageinteger
Implements the numerical encoding of the language. language usage string in request.
data.kindinteger
Numeric encoding of the operator type. kind usage string in request.
data.handlerstring
Processing function; returned when there is a value.
data.versionstring
Operator version; returned if there is a value.
data.isolation_levelstring
Isolation configuration; returned if there is a value.
data.source_file_idstring
Source file ID; returned when created using a source file.
data.input_schemastring
Enter the defined serialization content.
data.output_schemastring
Output the defined serialized content.
data.created_bystring
Creator ID; returned if there is a value.
data.updated_bystring
Last updater ID; returned if there is a value.
data.created_atinteger
Creation timestamp; returned if there is a value.
data.updated_atinteger
Last updated timestamp; returned if there is a value.
data.base_node_idstring
The basic operator associated with the built-in binding type; returned when there is a value.
data.base_node_versionstring
The basic operator version associated with the built-in binding type; returned when there is a value.
data.binding_configstring
The serialized content of the binding configuration; returned if there is a value.
data.catalog_idinteger
Associated Catalog ID; returned if there is a value.
data.database_idinteger
The associated database ID; returned if there is a value.
data.enabledboolean
Whether the operator is enabled.

Successful response example

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": 123,
    "node_id": "moi:custom.operator:workspace:text_counter",
    "name": "Text Counter",
    "identifier": "text_counter",
    "language": 1,
    "kind": 1,
    "input_schema": "{\"type\":\"object\"}",
    "output_schema": "{\"type\":\"object\"}",
    "enabled": true
  }
}

Error response

codestring
Error code.
msgstring
Readable error message.
datanull
`null` in an error response.

Error response example

{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}

Follow-up operations

Query custom operator details or Trial run custom operator.

Last updated on