JCS-pub/docs/JCS_pub_API.md

# JCS-pub API

**跳转回[README.md](../README.md)**

## 1 桶相关

### 1.1 创建桶

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/bucket/create</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
            <pre>{
    "userID": 1,
    "name": "bkt1"  // 桶名
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "bucket": {
            "bucketID": 1,   // 桶ID
            "name": "bkt1"   // 桶名
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 1.2 根据名字查询桶

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/bucket/getByName</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; name：string  // 桶名</p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
      "bucket": {
        "bucketID": 1,  // 桶ID
        "name": "bkt1"  // 桶名
      }
    }
}</pre>
        </td>
    </tr>
</table>

### 1.3 查询所有桶

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/bucket/listAll</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
      "buckets": [{
        "bucketID": 1,  // 桶ID
        "name": "bkt1"  // 桶名
      }]
    }
}</pre>
        </td>
    </tr>
</table>

### 1.4 删除桶

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/bucket/delete</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
            <pre>{
    "bucketID":1
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": null
}</pre>
        </td>
    </tr>
</table>

## 2 包相关

### 2.1 创建包

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/package/create</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
            <pre>{
    "bucketID":1,
    "name": ""  // 包名
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "package": {
            "packageID": 32,
            "name": "t1",
            "bucketID": 1,
            "createTime": "2025-06-24T16:31:28.5148754+08:00"
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 2.2 根据桶名和包名查询包

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/package/getByFullName</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; bucketName：string  // 桶名
&#45; packageName：string  // 包名 </p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "package": {
            "packageID": 32,
            "name": "t1",
            "bucketID": 1,
            "createTime": "2025-06-24T16:31:28.5148754+08:00"
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 2.3 获取桶里所有的包

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/package/listBucketPackages</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; bucketID：int64  // 桶ID </p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
      "packages":[{
            "packageID": 32,
            "name": "t1",
            "bucketID": 1,
            "createTime": "2025-06-24T16:31:28.5148754+08:00"
        }]
    }
}</pre>
        </td>
    </tr>
</table>

### 2.4 删除包

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/package/delete</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
            <pre>{
    "packageID":1
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": null
}</pre>
        </td>
    </tr>
</table>

## 3 对象相关

### 3.1 批量上传对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>multipart/form-data; boundary=xxxxxxx</td>
        <td>/v1/object/upload</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <p>被boundary分隔的多个part，第一个part的name必须是info，格式如下：</p>
        <pre>{
  "packageID": 1,  // PackageID，使用从创建Package接口返回的ID
  "affinity": 1  // 文件优先上传到哪个存储空间，可以不填。
}</pre>
        <p>之后的每一个part都是一个文件，name为files，filename为文件路径，需要进行URL编码。
一个例子：</p>
        <pre>POST /object/upload HTTP/1.1
User-Agent: PostmanRuntime/7.29.0
Accept: */*
Postman-Token: c12fa8b5-d902-46f3-b104-028effa0d531
Host: localhost:7890
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Type: multipart/form-data; boundary=&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;818270992847011232305151
Content-Length: 1649
<span></span>
&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;818270992847011232305151
Content-Disposition: form-data; name="info"
<span></span>
{
	"userID": 1,
	"packageID": 1
}
&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;818270992847011232305151
Content-Disposition: form-data; name="files"; filename="test.txt"
Content-Type: text/plain
<span></span>
testdata
&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;818270992847011232305151
Content-Disposition: form-data; name="files"; filename="a%2Fb%2Ftest2.txt"
<span></span>
testdata2
&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;&#45;818270992847011232305151&#45;&#45;</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "uploadeds": [
            {
                "objectID": 7,
                "packageID": 1,
                "path": "test.txt",
                "size": "123456",
                "fileHash": "xxxxxxxxxx",
                "redundancy": {
                    "type": "none"
                },
                "createTime": "2024-11-05T11:06:28+08:00",
                "updateTime": "2025-01-10T09:15:39.4452196+08:00"
            },
            {
                "objectID": 8,
                "packageID": 1,
                "path": "a/b/test2.txt",
                "size": "123456",
                "fileHash": "xxxxxxxxxx",
                "redundancy": {
                    "type": "none"
                },
                "createTime": "2024-11-05T11:06:28+08:00",
                "updateTime": "2025-01-10T09:15:39.4452196+08:00"
            }
        ]
    }
}</pre>
        </td>
    </tr>
</table>

### 3.2 下载对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/object/download</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; objectID：int64
&#45; offset：int64  // 偏移量
&#45; length：int64  // 读取长度。不存在则读取整个对象 </p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <p>如果请求成功，那么Content-Type将会是application/octet-stream，响应体就是文件数据。
如果失败，那么Content-Type将会是application/json，响应体格式如下：</p>
        <pre>{
    "code": "OperationFailed",
    "message": "xxxxxxxx",
    "data": null
}</pre>
        </td>
    </tr>
</table>

### 3.3 根据路径下载对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/object/downloadByPath</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; path：string
&#45; offset：int64  // 偏移量
&#45; length：int64  // 读取长度。不存在则读取整个对象 </p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <p>如果请求成功，那么Content-Type将会是application/octet-stream，响应体就是文件数据。
如果失败，那么Content-Type将会是application/json，响应体格式如下：</p>
        <pre>{
    "code": "OperationFailed",
    "message": "xxxxxxxx",
    "data": null
}</pre>
        </td>
    </tr>
</table>

### 3.4 根据路径查询对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/object/listByPath</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; packageID：int64
&#45; path：string
&#45; isPrefix：bool  // 如果为true，则会用path参数进行前缀查询
&#45; noRecursive：bool  // 如果为true，则在进行前缀查询的时候，会用类似查询目录的方式分别返回对象和“目录”
&#45; maxKeys：int  // 本次查询最多返回的结果的数量，即commonPrefixes+objects两个数组加起来的总数量
&#45; continuationToken：string  // 从token指定的位置进行本次查询，设置为空则从头开始查询。这个值应该直接使用从上一次查询的响应里的类似名字的字段 </p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "nextContinuationToken": "123456", // 用于下一次分页查询
        "isTruncated": false, // 如果为true，则代表还有更多结果等待下次查询。
        "commonPrefixes": [
            "a/b/",
            "a/c/"
        ],
        "objects": [
            {
                "objectID": 617,
                "packageID": 12,
                "path": "a/1.txt",
                "size": "1293",
                "fileHash": "Full4E69A8B8CD9F42EDE371DA94458BADFB2308AFCA736AA393784A3D81F4746377",
                "redundancy": {
                    "type": "none"
                },
                "createTime": "2024-11-19T16:02:25+08:00",
                "updateTime": "2024-11-19T16:02:25+08:00"
            },
            {
                "objectID": 618,
                "packageID": 12,
                "path": "a/2.txt",
                "size": "1293",
                "fileHash": "Full4E69A8B8CD9F42EDE371DA94458BADFB2308AFCA736AA393784A3D81F4746377",
                "redundancy": {
                    "type": "none"
                },
                "createTime": "2024-11-19T16:02:25+08:00",
                "updateTime": "2024-11-19T16:02:25+08:00"
            }
        ]
    }
}</pre>
        </td>
    </tr>
</table>

### 3.5 获取包中所有的对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/object/getPackageObjects</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; packageID：int64 </p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "objects": [
            {
                "objectID": 617,
                "packageID": 12,
                "path": "a/1.txt",
                "size": "1293",
                "fileHash": "Full4E69A8B8CD9F42EDE371DA94458BADFB2308AFCA736AA393784A3D81F4746377",
                "redundancy": {
                    "type": "none"
                },
                "createTime": "2024-11-19T16:02:25+08:00",
                "updateTime": "2024-11-19T16:02:25+08:00"
            },
            {
                "objectID": 618,
                "packageID": 12,
                "path": "a/2.txt",
                "size": "1293",
                "fileHash": "Full4E69A8B8CD9F42EDE371DA94458BADFB2308AFCA736AA393784A3D81F4746377",
                "redundancy": {
                    "type": "none"
                },
                "createTime": "2024-11-19T16:02:25+08:00",
                "updateTime": "2024-11-19T16:02:25+08:00"
            }
        ]
    }
}</pre>
        </td>
    </tr>
</table>

### 3.6 批量移动对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/object/move</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
            <pre>{
    "movings":[
        {
            "objectID":4, // 原对象ID
            "packageID":3, // 移动后的PackageID
            "path":"trace2.txt" // 移动后的Path
        }
    ]
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
      "successes": [ // 移动成功的对象ID
        4
      ]
    }
}</pre>
        </td>
    </tr>
</table>

### 3.7 批量删除对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/object/delete</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
            <pre>{
    "objectIDs":[
      4
    ]
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": null
}</pre>
        <p>即使文件不存在也会返回OK</p>
        </td>
    </tr>
</table>

### 3.8 批量复制对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/object/clone</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
            <pre>{
    "clonings": [
        {
            "objectID": 4,  // 原对象ID
            "newPath": "trace3.txt",  // 新对象的路径
            "newPackageID": 3  // 新对象的包ID
        }
    ]
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
      "objects":[{
                "objectID": 5,
                "packageID": 3,
                "path": "trace3.txt",
                "size": "1293",
                "fileHash": "Full4E69A8B8CD9F42EDE371DA94458BADFB2308AFCA736AA393784A3D81F4746377",
                "redundancy": {
                    "type": "none"
                },
                "createTime": "2024-11-19T16:02:25+08:00",
                "updateTime": "2024-11-19T16:02:25+08:00"
       }]
    }
}</pre>
        </td>
    </tr>
</table>

### 3.9 创建分片上传对象

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/object/newMultipartUpload</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
            <pre>{
    "packageID": 3,
    "path": "multi"  // 对象的path
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "object": {
            "objectID": 1039,
            "packageID": 3,
            "path": "obj.txt",
            "size": "0",
            "fileHash": "Full0000000000000000000000000000000000000000000000000000000000000000",
            "redundancy": {
                "type": "multipartUpload"
            },
            "createTime": "2025-03-04T16:03:18+08:00",
            "updateTime": "2025-03-11T15:20:44.5182982+08:00"
        }
    }
}</pre>
        <p>创建出来的对象能在查询接口里找到</p>
        </td>
    </tr>
</table>

### 3.10 上传分片

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>multipart/form-data; boundary=xxxxxxx</td>
        <td>/v1/object/uploadPart</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <p>与上传对象接口类似，需要包含info和file两个part，info的格式为：</p>
        <pre>{
  "objectID": 1, // 使用从创建分片上传对象接口得到的ObjectID
  "index": 1 // 分片编号，用于最终合并文件时使用。index相同时会覆盖旧数据。
}</pre>
        <p>file则为文件数据</p>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": ""
}</pre>
        </td>
    </tr>
</table>

### 3.11 合并分片

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/object/completeMultipartUpload</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "objectID": 1039,  // 需要进行合并的对象的ID
    "indexes": [2,3,1]  // 分片编号。可以重复出现相同的分片，合并时将按照参数指定的顺序组合分片。未使用的分片将被丢弃
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "object": {
            "objectID": 1039,
            "packageID": 3,
            "path": "obj.txt",
            "size": "30",
            "fileHash": "FullB7660EB37969EDC68202258A1838B89493B4C77EA006B1640768D20CEF7A7CD2",
            "redundancy": {
                "type": "none"
            },
            "createTime": "2025-03-04T16:03:18+08:00",
            "updateTime": "2025-03-11T15:42:03+08:00"
        }
    }
}</pre>
        </td>
    </tr>
</table>

## 4 用户存储空间相关

### 4.1 创建用户存储空间配置

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/userSpace/create</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "name": "test1",
    "storage": { // 存储系统类型
        "type": "OBS",
        "region": "",
        "endpoint": "",
        "bucket": "",
        "projectID": ""
    },
    "credential": { // 访问存储系统所需的权限信息
        "type": "OBS",
        "accessKeyId": "",
        "secretAccessKey": ""
    },
    "shardStore": { // 分片存储的配置，为null则不开启分片存储
        "maxSize":1024
    },
    "features": [], // 存储系统特性功能的配置
    "workingDir": "" // 包括分片存储在内的各种组件存放数据的根目录
}</pre>
        <p>&#45; storage、credential的内容是根据type字段来决定的，你可以在gitlink.org.cn/cloudream/jcs-pub/coordinator/types包中找到更多类型定义。
&#45; features为存储系统特性功能配置，具体有哪些可同样参考上面那个包。注：不是所有存储系统都支持所有特性。</p>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "userSpace": {
            "userSpaceID": 1,
            "name": "test1",
            "storage": {
                "type": "OBS",
                "region": "",
                "endpoint": "",
                "bucket": "",
                "projectID": ""
            },
            "credential": {
                "type": "OBS",
                "accessKeyId": "",
                "secretAccessKey": ""
            },
            "shardStore": {
                "maxSize": 1024
            },
            "features": [],
            "workingDir": "",
            "revision": 1
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 4.2 更新用户存储空间配置

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/userSpace/update</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "userSpaceID": 1,
    "name": "test1", // 新名称
    "credential": { // 新权限信息
        "type": "OBS",
        "accessKeyId": "",
        "secretAccessKey": ""
    }
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "userSpace": {
            "userSpaceID": 1,
            "name": "test1",
            "storage": {
                "type": "OBS",
                "region": "",
                "endpoint": "",
                "bucket": "",
                "projectID": ""
            },
            "credential": {
                "type": "OBS",
                "accessKeyId": "",
                "secretAccessKey": ""
            },
            "shardStore": {
                "maxSize": 1024
            },
            "features": [],
            "workingDir": "",
            "revision": 1
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 4.3 删除用户存储空间配置

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/userSpace/delete</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "userSpaceID": 1
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": null
}</pre>
        <p>如果不存在也会返回OK</p>
        </td>
    </tr>
</table>

### 4.4 获取用户存储空间配置

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/userSpace/get</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; userSpaceID: int64</p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "userSpace": {
            "userSpaceID": 1,
            "name": "test1",
            "storage": {
                "type": "OBS",
                "region": "",
                "endpoint": "",
                "bucket": "",
                "projectID": ""
            },
            "credential": {
                "type": "OBS",
                "accessKeyId": "",
                "secretAccessKey": ""
            },
            "shardStore": {
                "maxSize": 1024
            },
            "features": [],
            "workingDir": "",
            "revision": 1
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 4.5 测试用户存储空间配置

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/userSpace/test</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "storage": {
        "type": "OBS",
        "region": "",
        "endpoint": "",
        "bucket": "",
        "projectID": ""
    },
    "credential": {
        "type": "OBS",
        "accessKeyId": "",
        "secretAccessKey": ""
    },
    "workingDir": ""
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": null
}</pre>
        <p>返回OK代表配置有效，能够连接到存储系统</p>
        </td>
    </tr>
</table>

### 4.6 从用户存储空间上传到一个新的包

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/userSpace/createPackage</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "userSpaceID": 1,
    "path": "",  // 用户存储空间中的路径。可以是文件夹也可以是文件。注：不会加上WorkingDir
    "bucketID": 1,  // 新创建的包的bucketID
    "name": "",  // 新创建的包的名称
    "spaceAffinity": 0  // 上传的文件优先选择的存储空间。为0则不指定
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "package": {
            "packageID": 32,
            "name": "t1",
            "bucketID": 1,
            "createTime": "2025-06-24T16:31:28.5148754+08:00"
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 4.7 下载一个包到用户存储空间

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/userSpace/downloadPackage</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "userSpaceID": 1,
    "packageID": 1,
    "rootPath": "", // 存放下载文件的根路径
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": null
}</pre>
        </td>
    </tr>
</table>

## 5 用户存储空间同步相关

### 5.1 创建同步任务   

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/spaceSyncer/createTask</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "trigger": { // 同步任务触发条件
        "type": "Interval",
        "interval": 30
    },
    "mode": { // 同步模式
        "type": "Diff",
        "includeSize": false,
        "includeModTime": true
    },
    "filters": [ // 过滤规则
        {
            "type": "Size",
            "minSize": 10,
            "maxSize": 20000
        }
    ],
    "options": { // 选项
        "noEmptyDirectories": false
    }, 
    "srcUserSpaceID": 1, // 源存储空间ID
    "srcPath": "space1/cli", // 源存储空间中的路径
    "destUserSpaceIDs": [ // 目的存储空间ID
        2
    ],
    "destPathes": [ // 目的存储空间路径
        "space2/svr"
    ]
}</pre>
        <p>&#45; trigger、mod、filters的内容是根据type来变化的，可以查看gitlink.org.cn/cloudream/jcs-pub/client/types包来了解更多</p>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "task": {
            "taskID": 1,
            "trigger": {
                "type": "Interval",
                "interval": 30
            },
            "mode": {
                "type": "Diff",
                "includeSize": false,
                "includeModTime": true
            },
            "filters": [
                {
                    "type": "Size",
                    "minSize": 10,
                    "maxSize": 20000
                }
            ],
            "options": {
                "noEmptyDirectories": false
            },
            "srcUserSpaceID": 1,
            "srcPath": "space1/cli",
            "destUserSpaceIDs": [
                2
            ],
            "destPathes": [
                "space2/svr"
            ]
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 5.2 获取同步任务

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>GET</td>
        <td>application/json</td>
        <td>/v1/spaceSyncer/getTask</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <p>&#45; taskID: int64</p>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": {
        "task": {
            "taskID": 1,
            "trigger": {
                "type": "Interval",
                "interval": 30
            },
            "mode": {
                "type": "Diff",
                "includeSize": false,
                "includeModTime": true
            },
            "filters": [
                {
                    "type": "Size",
                    "minSize": 10,
                    "maxSize": 20000
                }
            ],
            "options": {
                "noEmptyDirectories": false
            },
            "srcUserSpaceID": 1,
            "srcPath": "space1/cli",
            "destUserSpaceIDs": [
                2
            ],
            "destPathes": [
                "space2/svr"
            ]
        }
    }
}</pre>
        </td>
    </tr>
</table>

### 5.3 取消同步任务

<table class="api-doc-table" > 
    <tr>
        <th colspan="3">请求</th>
    </tr>
    <tr>
        <td>POST</td>
        <td>application/json</td>
        <td>/v1/spaceSyncer/cancelTask</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">
        <pre>{
    "taskID": 1
}</pre>
        </td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        <pre>{
    "code": "OK",
    "message": "",
    "data": null
}</pre>
        </td>
    </tr>
</table>

<style>
.api-doc-table {
  border-collapse: collapse;
  width: 100%;
  font-family: monospace;
  border: 1px solid #e1e4e8;
}

.api-doc-table th {
  background-color: #f6f8fa;
  text-align: center;
  font-weight: 600;
  padding: 8px 12px;
}

.api-doc-table td {
  background-color: #ffffff;
}

.api-doc-table tr:not(:last-child) td:first-child {
  font-weight: bold;
}

.api-doc-table p {
  margin: 6px 0px 0px;
  line-height: 1.2;
  font-size: 0.95em;  
}

.api-doc-table pre {
   margin: 0px 2px 3px;
   padding: 0px 0px; 
}
</style>