Modify¶

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

Overview¶

Modifies a Pipeline. The optional configVersion is the current configuration version number at read time; if it is stale, the API returns 409 ft.PipelineConfigVersionConflict. If omitted, behavior is compatible with legacy calls.

When the category is profiling, this rule takes effect only when the workspace configuration field CentralPLServiceSwitch (returned by the /workspace/get API) is set to true.

Route Parameters¶

Body Request Parameters¶

Generation method: 1. First prepare an array of test samples. 2. Run JSON.stringify on the array. 3. Base64-encode the resulting UTF-8 string and pass it in testData.

Common examples: - Empty sample array: [] -> W10= - Single JSON log: [{"level":"info","msg":"HTTP"}] -> W3sibGV2ZWwiOiJpbmZvIiwibXNnIjoiSFRUUCJ9XQ== - Single text log: ["raw log line"] -> WyJyYXcgbG9nIGxpbmUiXQ==

Invalid example: Passing the base64 encoding of {"level":"info","msg":"HTTP"} directly, because the decoded top-level value is an object, not an array.
Allow empty: False
Allow empty string: True
| | dataType | string | | Data type: line_protocol - line protocol format; json - JSON format; message - Message
Example: line_protocol
Allow empty: False
Allow empty string: True
Allowed values: ['line_protocol', 'json', 'message']
| | isForce | boolean | | Whether to replace the default when the specific type has a default
Allow empty: False
| | configVersion | integer | | The current configuration version number at read time; passing it prevents concurrent overwrites
Allow empty: False
$minValue: 1
| | asDefault | int | | Whether to set this as the default Pipeline for the type; 1 sets it as default
Allow empty: False
| | enableByLogBackup | int | | Whether to enable the Pipeline to process forwarded data; 1 enables, 0 disables
Allow empty: False
| | category | string | Y | Category
Allow empty: False
Allow empty string: False
Allowed values: ['logging', 'object', 'custom_object', 'network', 'tracing', 'rum', 'llm', 'agent_monitor', 'security', 'keyevent', 'metric', 'profiling', 'dialtesting', 'billing', 'keyevent']
| | extend | json | | Category
Allow empty: False
| | extend.appID | array | | appID
Allow empty: True
| | extend.measurement | array | | Source
Allow empty: True
| | extend.loggingIndex | string | | Log Index
Allow empty: True
| | extend.ifAiCreate | boolean | | Whether the parsing rule is AI-generated
Allow empty: True
| | extend.aiTargetStructure | string | | AI-extracted content
Allow empty string: True
Allow empty: True
| | extend.exampleSource | string | | Example source
Allow empty string: True
Allow empty: True
| | extend.exampleType | string | | Example type
Allow empty string: True
Allow empty: True
|

Additional Parameter Notes¶

Concurrent Modification Protection¶

It is recommended to first call /api/v1/pipeline/<pl_uuid>/get to read the current configuration and configVersion, and then submit the existing modification parameters along with configVersion. This API is not a partial update endpoint that only submits configVersion; required parameters such as name, type, category, and content must still be provided according to the contract.

configVersion is an optional positive integer. Omitting it remains compatible with legacy calls, but version conflict checking is not enabled. When the version matches and the configuration actually changes, the old configuration is archived and a new configuration version is returned; saving the same configuration repeatedly does not create a new version. On receiving 409 / ft.PipelineConfigVersionConflict, re-read and compare the configuration before submitting, and do not automatically overwrite changes made by others.

Example request body: {"name":"demo","type":"local","category":"logging","content":"YWRkX2tleShjaXR5LCAic2hhbmdoYWkiKQ==","testData":"W10=","source":["nginx"],"configVersion":3}.

Response and Retry¶

On success, content is the current Pipeline object, including configVersion, configVersionAt, configVersionOperator, configVersionSource, configVersionAction, and configVersionSourceInfo. The time is a Unix timestamp in seconds. If content is {"confirm":["logging"]}, the default replacement requires confirmation and the modification has not been completed yet; isForce only applies to default replacement and does not skip name/source or version conflict validation.

The content and testData request fields are both Base64-encoded. Regular OpenAPI modification keeps the constraint that testData decodes to an empty value or a JSON array. After a timeout, query the current configuration first to confirm the write result before resubmitting, and avoid unconditional duplicate submissions.

Request Example¶

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

Response¶

{
    "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"
}