# Bucket API

Để tương tác với một bucket , bạn cần phải có bộ S3 Access Key để xác thực các request gửi lên hệ thống. Bạn không thể tương tác với bucket mà không có bộ {ref}`key<s3/how-to/tao-s3-access-key>` này.

Xem thêm {ref}`Hướng dẫn generate hashed key<s3/how-to/sd-api-key/bang-cac-ngon-ngu>`

* {ref}`Create Bucket<s3/reference/bucket-operations/create-bucket>`
    - {ref}`Constraints<s3/reference/bucket-operations/create-bucket/constraints>`
    - {ref}`Syntax<s3/reference/bucket-operations/create-bucket/syntax>`
    - {ref}`Parameters<s3/reference/bucket-operations/create-bucket/parameters>`
    - {ref}`Request Entity<s3/reference/bucket-operations/create-bucket/request-entity>`
    - {ref}`Response Entity<s3/reference/bucket-operations/create-bucket/response-entity>`
    - {ref}`Response Status<s3/reference/bucket-operations/create-bucket/response-status>`
* {ref}`Get bucket<s3/reference/bucket-operations/get-bucket>`
    - {ref}`Syntax<s3/reference/bucket-operations/get-bucket/syntax>`
    - {ref}`Parameters<s3/reference/bucket-operations/get-bucket/parameters>`
    - {ref}`Request Entity<s3/reference/bucket-operations/get-bucket/request-entity>`
    - {ref}`Response Entity<s3/reference/bucket-operations/get-bucket/response-entity>`
    - {ref}`Response Status<s3/reference/bucket-operations/get-bucket/response-status>`
* {ref}`Edit bucket<s3/reference/bucket-operations/edit-bucket>`
    - {ref}`Syntax<s3/reference/bucket-operations/edit-bucket/syntax>`
    - {ref}`Parameters<s3/reference/bucket-operations/edit-bucket/parameters>`
    - {ref}`Request Entity<s3/reference/bucket-operations/edit-bucket/request-entity>`
    - {ref}`Response Entity<s3/reference/bucket-operations/edit-bucket/response-entity>`
    - {ref}`Response Status<s3/reference/bucket-operations/edit-bucket/response-status>`
* {ref}`Delete bucket<s3/reference/bucket-operations/delete-bucket>`
    - {ref}`Syntax<s3/reference/bucket-operations/delete-bucket/syntax>`
    - {ref}`Parameters<s3/reference/bucket-operations/delete-bucket/parameters>`
    - {ref}`Request Entity<s3/reference/bucket-operations/delete-bucket/request-entity>`
    - {ref}`Response Entity<s3/reference/bucket-operations/delete-bucket/response-entity>`
    - {ref}`Response Status<s3/reference/bucket-operations/delete-bucket/response-status>`
* {ref}`Search Bucket<s3/reference/bucket-operations/search-bucket>`
    - {ref}`Syntax<s3/reference/bucket-operations/search-bucket/syntax>`
    - {ref}`Parameters<s3/reference/bucket-operations/search-bucket/parameters>`
    - {ref}`Request Entity<s3/reference/bucket-operations/search-bucket/request-entity>`
    - {ref}`Response Entity<s3/reference/bucket-operations/search-bucket/response-entity>`
    - {ref}`Response Status<s3/reference/bucket-operations/search-bucket/response-status>`


(s3/reference/bucket-operations/create-bucket)=
## Create Bucket

Tạo mới một bucket để sử dụng trong hệ thống.

(s3/reference/bucket-operations/create-bucket/constraints)=
**Constraints**

Bucket name sẽ là một phần trong sun s3 domain hoặc sun s3 path, vì vậy tên của bucket sẽ follow ràng buộc của domain

* Bucket names là duy nhất trong một pool.
* Bucket names không được có định dạng giống địa chỉ IP.
* Bucket names có độ dài trong khoảng 3 tới 58 ký tự.
* Bucket names không được tồn tại ký tự viết hoa hoặc dấu gạch dưới "_".
* Bucket names bắt đầu bằng một chữ viết thường, hoặc số.
* Bucket codes sẽ được hệ thống sinh ra theo bucket name. 

```{note}
Người dùng tương tác với hệ thống Sun S3 thông qua bucket code. Bucket code không thể thay đổi sau khi được sinh ra.
```

(s3/reference/bucket-operations/create-bucket/syntax)=
**Syntax**

```
POST /s3/v1/bucket
api-key: Basic Base64(<access-key>:<hash-of-header-and-secret>)
```

(s3/reference/bucket-operations/create-bucket/parameters)=
**Parameters**

(s3/reference/bucket-operations/create-bucket/request-entity)=
**Request Entity**

Example

```{code-block} json
{
  "cors": {
    "corsRules": [
      {
        "allowOrigins": [
          "http://console.sunteco.vn"
        ]
      }
    ]
  },
  "name": "bucket-name",
  "poolId": 123
}
```

Definition

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| allowOrigins | Array String | Định nghĩa danh sách các origin được phép truy cập từ client. | No |
| name | String | Bucket name do người dùng đặt tên | Yes |
| poolId | number | Id của pool mà bucket được tạo ra | Yes |

(s3/reference/bucket-operations/create-bucket/response-entity)=
**Response Entity**

| Name | Type | Description |
| ---- | ---- | ----------- |
| Result | String | Mô tả trạng thái tạo bucket |

(s3/reference/bucket-operations/create-bucket/response-status)=
**Response Status**

| HTTP Status | Status Code | Description |
| ----------- | ----------- | ----------- |
| 200 | SUCCESS | Tạo bucket thành công |
| 400 | BAD REQUEST | Tham số truyền lên không hợp lệ |
| 401 | UNAUTHORIZED | API chưa được xác thực. |
| 403 | FORBIDDEN | Access Key không có quyền thực hiện tạo bucket |
| 409 | CONFLICT | Bucket name đã tồn tại trong pool |

(s3/reference/bucket-operations/get-bucket)=
## Get bucket

Lấy thông tin của một bucket.

(s3/reference/bucket-operations/get-bucket/syntax)=
**Syntax**

```
GET /s3/v1/bucket
api-key: Basic Base64(<access-key>:<hash-of-header-and-secret>)
```

(s3/reference/bucket-operations/get-bucket/parameters)=
**Parameters**

| Name | Description | Valid values | Required |
| ---- | ----------- | ------------ | -------- |
| uniqcode | Bucket code | any string | yes |

(s3/reference/bucket-operations/get-bucket/request-entity)=
**Request Entity**

(s3/reference/bucket-operations/get-bucket/response-entity)=
**Response Entity**

(s3/reference/bucket-operations/get-bucket/response-status)=
**Response Status**

| HTTP Status | Status Code | Description |
| ----------- | ----------- | ----------- |
| 200 | SUCCESS | Lấy thành công |
| 400 | BAD REQUEST | Tham số truyền lên không hợp lệ |
| 401 | UNAUTHORIZED | API chưa được xác thực |
| 403 | FORBIDDEN | Access Key không có quyền thực hiện lấy thông tin bucket |
| 404 | NOTFOUND | Không tìm thấy bucket hợp lệ |
| 409 | CONFLICT | Bucket name đã tồn tại trong pool |

(s3/reference/bucket-operations/edit-bucket)=
## Edit bucket

Chỉnh sửa các thông tin của bucket.

(s3/reference/bucket-operations/edit-bucket/syntax)=
**Syntax**

```
PUT /s3/v1/bucket
api-key: Basic Base64(<access-key>:<hash-of-header-and-secret>)
```

(s3/reference/bucket-operations/edit-bucket/parameters)=
**Parameters**

(s3/reference/bucket-operations/edit-bucket/request-entity)=
**Request Entity**

Example

```{code-block} json
{
  "name": "new bucket name",
  "uniqcode": "bucket-code"
}
```

Definition

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| name | String | Tên mới của bucket khi muốn thay đổi | Yes |
| uniqcode | String | Bucket code của bucket | Yes |

(s3/reference/bucket-operations/edit-bucket/response-entity)=
**Response Entity**

(s3/reference/bucket-operations/edit-bucket/response-status)=
**Response Status**

| HTTP Status | Status Code | Description |
| ----------- | ----------- | ----------- |
| 200 | SUCCESS | Sửa thành công |
| 400 | BAD REQUEST | Tham số truyền lên không hợp lệ |
| 401 | UNAUTHORIZED | API chưa được xác thực. |
| 403 | FORBIDDEN | Access Key không có quyền thực hiện sửa bucket |
| 404 | NOTFOUND | Không tìm thấy bucket hợp lệ |

(s3/reference/bucket-operations/delete-bucket)=
## Delete bucket

Xóa một bucket để có thể giảm dung lượng sử dụng của pool, tái sử dụng tên của bucket trong pool.

(s3/reference/bucket-operations/delete-bucket/syntax)=
**Syntax**

```
DELETE /s3/v1/bucket
api-key: Basic Base64(<access-key>:<hash-of-header-and-secret>)
```

(s3/reference/bucket-operations/delete-bucket/parameters)=
**Parameters**

| Name | Description | Valid values | Required |
| ---- | ----------- | ------------ | -------- |
| uniqcode | Bucket code | any string | yes |

(s3/reference/bucket-operations/delete-bucket/request-entity)=
**Request Entity**

(s3/reference/bucket-operations/delete-bucket/response-entity)=
**Response Entity**

(s3/reference/bucket-operations/delete-bucket/response-status)=
**Response Status**

| HTTP Status | Status Code | Description |
| ----------- | ----------- | ----------- |
| 200 | SUCCESS | Xóa thành công |
| 400 | BAD REQUEST | Tham số truyền lên không hợp lệ |
| 401 | UNAUTHORIZED | API chưa được xác thực. |
| 403 | FORBIDDEN | Access Key không có quyền thực hiện xóa bucket |
| 404 | NOTFOUND | Không tìm thấy bucket hợp lệ |

(s3/reference/bucket-operations/search-bucket)=
## Search Bucket

Search các bucket trong một pool theo name.

(s3/reference/bucket-operations/search-bucket/syntax)=
**Syntax**

```
POST /s3/v1/bucket/query
api-key: Basic Base64(<access-key>:<hash-of-header-and-secret>)
```

(s3/reference/bucket-operations/search-bucket/parameters)=
**Parameters**

(s3/reference/bucket-operations/search-bucket/request-entity)=
**Request Entity**

Example

```{code-block} json
{
  "poolUniqcode": "pool-code",
  "textSearch": "any text"
}
```

Definition

| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| poolUniqcode | String | Pool code, định danh của {ref}`Sun S3 Pool<s3/reference/pool>` | Yes |
| textSearch | String | Đoạn text cần search | No |

(s3/reference/bucket-operations/search-bucket/response-entity)=
**Response Entity**

(s3/reference/bucket-operations/search-bucket/response-status)=
**Response Status**

| HTTP Status | Status Code | Description |
| ----------- | ----------- | ----------- |
| 200 | SUCCESS | Tìm kiếm thành công |
| 400 | BAD REQUEST | Tham số truyền lên không hợp lệ |
| 401 | UNAUTHORIZED | API chưa được xác thực. | 
| 403 | FORBIDDEN | Access Key không có quyền thực hiện đọc bucket |