跳转到主要内容
OpenYida 提供强大的 HTTP 连接器管理功能，支持从 curl 命令智能创建连接器，实现宜搭与外部系统的无缝对接。

​
功能概述

智能创建

从 curl 命令自动解析并创建连接器，支持鉴权信息提取。

API 管理

完整的连接器生命周期管理：创建、更新、测试、删除。

鉴权支持

支持 Bearer Token、API Key、OAuth2 等多种鉴权方式。

动作管理

添加、测试、管理连接器的执行动作。

​
智能创建连接器

通过 curl 命令一键创建连接器： 
openyida connector smart-create \
  --curl "curl 'https://api.example.com/v1/users' -H 'Authorization: Bearer xxx'" \
  --name "用户管理连接器" \
  --desc "用于管理用户数据的 HTTP 连接器"
智能创建流程：
  1. 解析接口信息 - 提取协议、Host、方法、路径、鉴权类型
  2. 匹配已有连接器 - 查找相同 Host 和鉴权的现有连接器
  3. 生成连接器配置 - 自动构建 OpenAPI 格式的连接器定义
  4. 创建或更新 - 创建新连接器或向现有连接器添加动作

​
连接器管理命令

​
列出连接器

openyida connector list
openyida connector list --page 1 --size 20

​
创建连接器

openyida connector create "连接器名称" "api.example.com" \
  --operations ./operations.json \
  --protocol https \
  --desc "连接器描述"
operations JSON 文件中的 method 字段会自动规范化为小写（例如 "POST" 会转换为 "post"）。如果未指定 method，默认值为 "get"。

​
查看连接器详情

openyida connector detail <connector-id>

​
删除连接器

openyida connector delete <connector-id> --force

​
动作管理

​
添加执行动作

openyida connector add-action \
  --connector-id <id> \
  --operations ./new-action.json \
  --confirm
operations 配置中的 method 字段会自动规范化为小写（例如 "POST" 会转换为 "post"）。你可以使用任意大小写。如果未指定，默认值为 "get"。

​
列出现有动作

openyida connector list-actions <connector-id>

​
测试动作

openyida connector test \
  --connector-id <id> \
  --action <actionId> \
  --params '{"key": "value"}'

​
删除动作

openyida connector delete-action <connector-id> <operation-id> --force

​
Operations JSON 格式

--operations 参数接受一个 JSON 文件，用于定义执行动作配置。数组中的每个动作包含 inputs，按参数位置分组描述请求参数。

​
输入分组

分组名称paramLocation 值说明
HeadersheaderHTTP 请求头
Bodybody请求体字段（POST/PUT）
QueryqueryURL 查询参数

​
paramLocation 字段

每个输入分组及其 childList 子项都必须包含 paramLocation 字段，用于指示参数在 HTTP 请求中的发送位置。有效值为 "header"、"body" 和 "query"。

​
示例 operations JSON

[
  {
    "operationId": "queryUsers",
    "summary": "查询用户",
    "description": "分页查询用户数据",
    "url": "v1/users",
    "method": "post",
    "inputs": [
      {
        "name": "Headers",
        "paramType": "Object",
        "desc": "请求头",
        "required": false,
        "paramLocation": "header",
        "childList": [
          {
            "name": "Content-Type",
            "paramType": "String",
            "desc": "Content-Type",
            "required": false,
            "defaultValue": "application/json",
            "paramLocation": "header"
          }
        ]
      },
      {
        "name": "Body",
        "paramType": "Object",
        "desc": "请求体",
        "required": false,
        "paramLocation": "body",
        "childList": [
          {
            "name": "pageSize",
            "paramType": "Number",
            "desc": "pageSize",
            "required": false,
            "paramLocation": "body"
          }
        ]
      },
      {
        "name": "Query",
        "paramType": "Object",
        "desc": "查询参数",
        "required": false,
        "paramLocation": "query",
        "childList": [
          {
            "name": "appType",
            "paramType": "String",
            "desc": "appType",
            "required": false,
            "paramLocation": "query"
          }
        ]
      }
    ],
    "parameters": {
      "header": [{ "name": "Content-Type", "value": "application/json" }],
      "body": { "default": "{\"pageSize\": 20}" },
      "query": [{ "name": "appType", "value": "" }]
    },
    "responses": { "type": "object", "properties": {} },
    "outputs": [
      {
        "name": "Response",
        "paramType": "Object",
        "desc": "响应体结构",
        "required": false,
        "childList": []
      }
    ]
  }
]
paramLocation 字段在输入分组（如 Headers、Body、Query）和其 childList 中的每个子项上都是必需的。缺少此字段可能导致连接器动作编辑器无法渲染或连接器调用失败。

​
鉴权账号管理

​
列出鉴权账号

openyida connector list-connections <connector-id>

​
创建鉴权账号

openyida connector create-connection <connector-id> "生产环境账号" \
  --token "Bearer xxx" \
  --type bearer

​
辅助工具

​
解析 API 信息

openyida connector parse-api --curl "curl命令" --output ./api-info.json

​
生成接口文档模板

openyida connector gen-template ./my-api-template.json

​
最佳实践

​
1. 使用环境变量管理敏感信息

export API_TOKEN="your-secret-token"
openyida connector smart-create --curl "curl -H 'Authorization: Bearer $API_TOKEN' ..."

​
2. 分阶段创建复杂连接器

# 第一步：创建基础连接器
openyida connector create "钉钉 API" "oapi.dingtalk.com"

# 第二步：逐个添加动作
openyida connector add-action --connector-id <id> --operations ./action1.json
openyida connector add-action --connector-id <id> --operations ./action2.json

​
3. 测试后再启用

# 创建但不确认
openyida connector add-action --connector-id <id> --operations ./action.json

# 测试动作
openyida connector test --connector-id <id> --action <actionId>

# 确认生效
# 在宜搭后台完成最终确认

​
常见问题

确保 curl 命令格式正确，包含完整的 URL 和必要的 headers。如果包含特殊字符，建议使用引号包裹。
使用 connector add-action 命令，如果动作 ID 已存在，系统会提示是否更新。
目前支持 Bearer Token、API Key、Basic Auth、OAuth2。curl 命令中的鉴权信息会被自动识别。