JCS-pub/docs/JCS_pub_API.md

# JCS-pub API

**跳转回README.md [中文](../README.md) [英文](../README_en.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 根据名字查询桶


### 1.3 查询所有桶



### 1.4 删除桶


## 2 包相关

### 2.1 创建包


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


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


### 2.4 删除包


## 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>
        <p>一个例子：</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=--------------------------818270992847011232305151
Content-Length: 1649
<span style="display:block; height:1em;"></span>
<mark>----------------------------818270992847011232305151</mark>
Content-Disposition: form-data; name="info"
<span style="display:block; height:1em;"></span>
{
	"userID": 1,
	"packageID": 1
}
<mark>----------------------------818270992847011232305151</mark>
Content-Disposition: form-data; name="files"; filename="test.txt"
Content-Type: text/plain
<span style="display:block; height:1em;"></span>
testdata
<mark>----------------------------818270992847011232305151</mark>
Content-Disposition: form-data; name="files"; filename="a%2Fb%2Ftest2.txt"
Content-Type: text/plain
<span style="display:block; height:1em;"></span>
testdata2
<mark>----------------------------818270992847011232305151--</mark></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/bucket/download</td>
    </tr>
    <tr>
        <td>Query</td>
        <td colspan="2">
        <pre>● objectID：int64
● offset：int64，偏移量
● length：int64，读取长度。不存在则读取整个对象</pre>
        </td>
    </tr>
    <tr>
        <td>Body</td>
        <td colspan="2">无</td>
    </tr>
    <tr>
        <th colspan="3">响应示例</th>
    </tr>
    <tr>
        <td colspan="3">
        如果请求成功，那么Content-Type将会是application/octet-stream，响应体就是文件数据。
        如果失败，那么Content-Type将会是application/json，响应体格式如下：
        <pre>{
    "code": "OperationFailed",
    "message": "xxxxxxxx",
    "data": null
}</pre>
        </td>
    </tr>
</table>


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


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

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

### 3.6 批量移动对象

### 3.7 批量删除对象

### 3.8 批量复制对象

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

### 3.10 上传分片

### 3.11 合并分片

## 4 用户存储空间相关

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

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

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

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

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

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

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


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

### 5.1 创建同步任务   

### 5.2 获取同步任务

### 5.3 取消同步任务


<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 {
  padding: 8px 12px;
  border-top: 1px solid #eaecef;
  background-color: #ffffff;
}

.api-doc-table td:first-child {
  font-weight: bold;
}

/* .api-doc-table pre {
  margin: 0;
  font-family: monospace;
  font-size: 14px;
  line-height: 1.5;
} */
</style>