跳轉到主要內容
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 命令中的鑑權信息會被自動識別。