修改¶

POST /api/v1/pipeline/{pl_uuid}/modify

概述¶

修改一个 Pipeline。可选 configVersion 为读取时的当前配置版本号，过期返回 409 ft.PipelineConfigVersionConflict；缺省兼容旧调用。

当类型 category 为 profiling 时, 空间配置的字段 CentralPLServiceSwitch(/workspace/get 接口返回) 为 true 该规则才会实际生效

路由参数¶

参数名	类型	必选	说明
pl_uuid	string	Y	Pipeline 的 ID

Body 请求参数¶

参数名	类型	必选	说明
name	string	Y	Pipeline 文件名称，也是其 source 类型值允许为空: False 最大长度: 256 $notSearchRegExp: [^a-zA-Z0-9_\u4e00-\u9fa5-]+
type	string	Y	Pipeline 文件类型允许为空: False 可选值: ['local', 'central']
source	array		选取的 source 列表允许为空: False
content	string	Y	pipeline 文件内容(base64编码)。
base64 解码后的脚本按 Studio UI 的字符计数规则校验：U+0001–U+007E、U+FF60–U+FF9F 计 1，其他 UTF-16 单元计 2，上限 65535。同时要求解码后脚本全文的 UTF-8 编码大小不超过 65535 字节；任一超限返回 ft.ContextExceedLimit，字节超限提示以字节为单位。
允许为空: False
testData	string		测试数据(base64编码)。OpenAPI 侧仅允许传空字符串或 base64 解码后为 JSON 数组的内容。

生成方式： 1. 先准备测试样例数组； 2. 对数组执行 JSON.stringify； 3. 对得到的 UTF-8 字符串做 base64 编码后传入 testData。

常用示例： - 空样例数组：[] -> W10= - 单条 JSON 日志：[{"level":"info","msg":"HTTP"}] -> W3sibGV2ZWwiOiJpbmZvIiwibXNnIjoiSFRUUCJ9XQ== - 单条文本日志：["raw log line"] -> WyJyYXcgbG9nIGxpbmUiXQ==

非法示例：直接把 {"level":"info","msg":"HTTP"} 做 base64 后传入，因为解码后顶层是 object，不是数组。
允许为空: False
允许为空字符串: True
| | dataType | string | | 数据类型 line_protocol-行协议格式; json-JSON 格式; message-Message
例子: line_protocol
允许为空: False
允许为空字符串: True
可选值: ['line_protocol', 'json', 'message']
| | isForce | boolean | | 具体类型存在 default 时, 是否进行替换
允许为空: False
| | configVersion | integer | | 读取时的当前配置版本号；传入后可防止并发覆盖
允许为空: False
$minValue: 1
| | asDefault | int | | 是否作为该类型的默认 pipeline, 1为设为默认
允许为空: False
| | enableByLogBackup | int | | 启用 Pipeline 处理转发数据, 1为启用, 0为不启用
允许为空: False
| | category | string | Y | 类别
允许为空: False
允许为空字符串: False
可选值: ['logging', 'object', 'custom_object', 'network', 'tracing', 'rum', 'llm', 'agent_monitor', 'security', 'keyevent', 'metric', 'profiling', 'dialtesting', 'billing', 'keyevent']
| | extend | json | | 类别
允许为空: False
| | extend.appID | array | | appID
允许为空: True
| | extend.measurement | array | | source 来源
允许为空: True
| | extend.loggingIndex | string | | 日志索引
允许为空: True
| | extend.ifAiCreate | boolean | | 是否为AI生成解析规则
允许为空: True
| | extend.aiTargetStructure | string | | AI提取内容
允许为空字符串: True
允许为空: True
| | extend.exampleSource | string | | 示例源
允许为空字符串: True
允许为空: True
| | extend.exampleType | string | | 示例类型
允许为空字符串: True
允许为空: True
|

参数补充说明¶

并发修改保护¶

建议先调用 /api/v1/pipeline/<pl_uuid>/get 读取当前配置和 configVersion，再以现有修改参数加 configVersion 提交。本接口并非只提交 configVersion 的局部更新接口，name、type、category、content 等必填参数仍需按契约提供。

configVersion 为可选正整数；不传兼容旧调用，但不启用版本号冲突检查。版本一致且配置实际变化时，归档旧配置并返回新的配置版本；相同配置重复保存不生成版本。收到 409 / ft.PipelineConfigVersionConflict 时，应重新读取并比较配置，确认后再提交，不能自动覆盖他人修改。

示例请求体：{"name":"demo","type":"local","category":"logging","content":"YWRkX2tleShjaXR5LCAic2hhbmdoYWkiKQ==","testData":"W10=","source":["nginx"],"configVersion":3}。

返回及重试¶

成功响应 content 是当前 Pipeline 对象，包含 configVersion、configVersionAt、configVersionOperator、configVersionSource、configVersionAction、configVersionSourceInfo。时间为 Unix 秒级时间戳。若 content 为 {"confirm":["logging"]}，表示默认替换需要确认，本次尚未完成修改；isForce 仅用于默认替换，不跳过名称/source或版本冲突校验。

content 和 testData 请求字段均为 Base64 编码。普通 OpenAPI 修改保留 testData 解码后为空或 JSON 数组的约束。超时后应先查询当前配置确认写入结果，避免无条件重复提交。

请求例子¶

curl 'https://openapi.guance.com/api/v1/pipeline/pl_xxxx32/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"name":"test_modify","category":"logging","asDefault":0,"content":"YWRkX2tleShjaXR5LCAic2hhbmdoYWkiKQ==","testData":"W3sibGV2ZWwiOiJpbmZvIiwibXNnIjoiSFRUUCJ9XQ==","source":["nsqlookupd"]}' \
--compressed

响应¶

{
    "code": 200,
    "content": {
        "asDefault": 0,
        "category": "logging",
        "content": "YWRkX2tleShjaXR5LCAic2hhbmdoYWkiKQ==\n",
        "createAt": 1678026470,
        "creator": "xxx",
        "deleteAt": -1,
        "extend": {},
        "id": 86,
        "isSysTemplate": 0,
        "name": "test_modify",
        "source": [],
        "status": 0,
        "testData": "W10=\n",
        "updateAt": 1678026808.95266,
        "updator": "xx",
        "uuid": "pl_xxxx32",
        "workspaceUUID": "wksp_xxxx32",
        "configVersion": 4,
        "configVersionAt": 1788800200,
        "configVersionOperator": "acnt_example",
        "configVersionSource": "openapi",
        "configVersionAction": "modify",
        "configVersionSourceInfo": {}
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE-1EA80DD4-EB2C-4A9B-A146-D00606CC50E0"
}

修改¶

概述¶