Restore Historical Version¶

POST /api/v1/pipeline_history/{pipeline_history_uuid}/restore

Overview¶

Restore a historical configuration. configVersion is the current configuration version. If it is outdated, HTTP 409 is returned. No test run is required before restoring. Name and source conflicts still raise errors; isForce only confirms replacement of the default Pipeline.

Path Parameters¶

Body Request Parameters¶

Additional Parameter Notes¶

Overwrites the original Pipeline with the specified historical configuration. This operation changes customer resource configuration, so read and confirm the target historical details first.

Recommended Call Flow¶

1. Query the current Pipeline details or the first page of history to obtain the current configVersion.
2. Select the target uuid from the history list, read the historical details, and confirm the configuration.
3. Put the current configVersion into the request body and call restore for the target historical uuid.
4. On success, refresh the local cache using the configVersion and configuration from the response.

For example, if the current version is 3 and the target historical version is 1, the request body should pass {"configVersion":3}, not 1. On success, if the configuration actually changes, the original current configuration is archived and a new current version is generated (for example, 4). The current version is not rolled back to 1, and the target historical snapshot is not modified. The restored content does not include the enable/disable status, and no test needs to be run first. If the target configuration is identical to the current configuration, no new version is generated.

Conflicts and Confirmation¶

• HTTP 409 / ft.PipelineConfigVersionConflict: The current configuration has been modified by another call. Stop the overwrite, re-read and compare the latest configuration, and submit only after confirmation from the caller. Do not blindly retry with a new version number automatically.
• ft.PipelineSourceExists: The historical source is already occupied by another Pipeline. Resolve the conflict before restoring. isForce=true cannot bypass source or version conflicts.
• If restoring as the default Pipeline conflicts with the existing default and is not confirmed, the success response may include content.confirm (for example, {"confirm":["logging"]}). This is only a confirmation prompt and does not mean the restore is complete. After the caller confirms, call again with isForce=true and a still-valid configVersion.
• On timeout or connection interruption, the write result may be unknown. First query the current configuration and version, and do not unconditionally repeat the write.

Prerequisites¶

Use the DF-API-KEY of the Workspace to call the OpenAPI service. Queries require read permission; restore and clone require Pipeline management and write permission. The API does not support specifying another Workspace or operator through the request body. The Endpoint, resource UUID, and API-Key in the examples are placeholders. Replace them before calling, and do not output the API Key in logs.

The response examples use fictitious resources to show typical business fields. Actual responses may contain additional fields from ordinary Pipeline APIs. Callers should be compatible with new fields.

Version Fields¶

The historical config.content and config.testData are Base64-encoded strings. The caller should Base64-decode them and then read as UTF-8. testData is a test sample and will not be automatically executed by the read or restore API. Do not treat the source version in configVersionSourceInfo as the current version.

Response Notes¶

On successful write, the content follows the Pipeline object of the ordinary modification API, including uuid, configuration fields, and version metadata. The content of the confirmation branch contains only confirm. The restore is not executed if the resource has been deleted, the history has been cleaned, or the caller lacks permission.

Example Request¶

curl -X POST 'https://openapi.guance.com/api/v1/pipeline_history/<pipeline_history_uuid>/restore' -H 'DF-API-KEY: <API-Key>' -H 'Content-Type: application/json' -d '{"configVersion":3,"isForce":false}'

Response¶

{
    "code": 200,
    "content": {
        "name": "demo",
        "type": "local",
        "category": "logging",
        "source": [
            "nginx"
        ],
        "content": "YWRkX2tleShjaXR5LCAic2hhbmdoYWkiKQ==",
        "testData": "W10=",
        "dataType": "line_protocol",
        "asDefault": 0,
        "enableByLogBackup": 0,
        "extend": {},
        "id": 10,
        "uuid": "pl_example",
        "workspaceUUID": "wksp_example",
        "status": 0,
        "creator": "acnt_example",
        "updator": "acnt_example",
        "createAt": 1788799900,
        "updateAt": 1788800200,
        "deleteAt": -1,
        "configVersion": 4,
        "configVersionAt": 1788800200,
        "configVersionOperator": "acnt_example",
        "configVersionSource": "history",
        "configVersionAction": "history_restore",
        "configVersionSourceInfo": {
            "pipelineHistoryUUID": "plh_example",
            "pipelineUUID": "pl_example",
            "configVersion": 2
        }
    },
    "errorCode": "",
    "message": "",
    "success": true,
    "traceId": "TRACE_EXAMPLE"
}