# Cloud Storage

Cloud Storage là không gian tệp ở cấp nhóm, dùng để lưu những tệp cần dùng lại trong các luồng tự động hóa của MoreLogin. Hãy tải lên một lần, sắp xếp bằng thẻ, tìm lại sau và xóa những tệp không còn cần.

Nó khác với các API truyền tệp của Cloud Phone. API tệp của Cloud Phone chuyển tệp vào hoặc ra khỏi một thiết bị cụ thể. API Cloud Storage quản lý thư viện tệp dùng chung, tức là trước khi tệp được thiết bị, lịch chạy, mẫu RPA hay logic tự động hóa khác sử dụng.

## Bạn có thể làm gì

| Khả năng | Dùng để làm gì | API liên quan |
|  --- | --- | --- |
| Tổng quan lưu trữ | Kiểm tra tổng dung lượng, dung lượng đã dùng, ngày hết hạn và trạng thái dung lượng trước khi tải lên hoặc dọn dẹp tệp. | Truy vấn thông tin cloud storage |
| Tìm tệp | Liệt kê tệp cloud storage theo trang và lọc theo tên tệp, loại tệp, thẻ hoặc ID tệp. | Phân trang tệp cloud storage |
| Tải tệp lên | Xin URL tải lên đã ký trước, tải nội dung tệp lên object storage, rồi xác nhận hoàn tất trong MoreLogin. | Xin hàng loạt URL tải lên đã ký trước, xác nhận hoàn tất tải lên |
| Dọn dẹp tệp | Xóa một hoặc nhiều tệp khỏi thư viện lưu trữ dùng chung. | Xóa hàng loạt tệp cloud storage |
| Gắn thẻ tệp | Ghi đè hoặc thêm thẻ để sắp xếp tệp theo dự án, khách hàng, mục đích sử dụng hoặc luồng công việc. | Đặt thẻ cho tệp, thêm thẻ cho tệp, truy vấn thẻ của tệp |
| Quản lý thẻ | Tạo, sửa, liệt kê và xóa các thẻ tệp dùng lại được. | Truy vấn toàn bộ thẻ, tạo thẻ, sửa thẻ, xóa thẻ |


## Các tình huống thường gặp

- Tải APK, tệp media, tài liệu hoặc tài nguyên kiểm thử lên một lần rồi dùng lại trong tự động hóa.
- Giữ tệp được sắp xếp theo khách hàng, chiến dịch, phiên bản ứng dụng, môi trường hoặc luồng công việc.
- Tạo bộ chọn tệp trong công cụ nội bộ của bạn bằng cách gọi API phân trang tệp kèm bộ lọc tên tệp và thẻ.
- Dọn dẹp hàng loạt các tệp đã hết hạn hoặc không dùng sau khi một luồng kết thúc.
- Đồng bộ hệ thống tài nguyên bên ngoài với MoreLogin bằng cách tạo thẻ và gắn chúng vào các tệp đã tải lên.


## Cách truy cập API

| Phương thức | Base URL | Tiền tố đường dẫn | Tình huống dùng |
|  --- | --- | --- | --- |
| **Open API** | `https://api.morelogin.com` | `/cloudstorage` | Truy cập server-to-server, công cụ từ xa, CI/CD, dịch vụ backend |
| **Local API** | `http://127.0.0.1:40000` | `/api/cloudstorage` | Script hoặc công cụ desktop chạy trên cùng máy với client MoreLogin |


Chi tiết xác thực xem tại [Xác thực](/vi/api-reference/getting-started/authentication).

## Luồng tải lên

Việc tải lên Cloud Storage dùng luồng URL đã ký trước. Mã của bạn không tải tệp nhị phân trực tiếp lên API MoreLogin.

1. Gọi **Xin hàng loạt URL tải lên đã ký trước** kèm danh sách tên tệp (có phần mở rộng).
2. Với mỗi phần tử trả về, tải tệp nhị phân lên `presignedUrl` bằng `PUT` qua HTTPS.
3. Gọi **Xác nhận hoàn tất tải lên** với `id` tệp được trả về.
4. Dùng **Phân trang tệp cloud storage** hoặc **Truy vấn thẻ của tệp** để kiểm tra và hiển thị tệp đã tải lên.


```bash
# 1. Request a presigned upload URL
curl -X POST "https://api.morelogin.com/cloudstorage/upload/init" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileNames": ["example.jpg"]
  }'

# 2. Upload file content to the returned presignedUrl
curl -X PUT "PRESIGNED_URL_FROM_RESPONSE" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@example.jpg"

# 3. Confirm upload completion (id from step 1 response)
curl -X POST "https://api.morelogin.com/cloudstorage/upload/complete" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1800000000000001
  }'
```

Với Local API, hãy giữ nguyên body request và thay đường dẫn thành `http://127.0.0.1:40000/api/cloudstorage/...`.

## Dùng tệp Cloud Storage trong RPA của Cloud Phone

Sau khi tệp được tải lên và xác nhận, tham số mẫu RPA của Cloud Phone có thể tham chiếu tệp đó bằng ID tệp Cloud Storage. Hãy dùng giao thức tệp đám mây của MoreLogin thay vì URL tải xuống công khai bên ngoài:

```text
morelogin://cloudfile?ids=1,2
```

`ids` là danh sách ID tệp Cloud Storage phân tách bằng dấu phẩy. Chỉ dùng dấu phẩy tiếng Anh, không có khoảng trắng. Bạn có thể lấy ID tệp từ phản hồi hoàn tất tải lên hoặc từ **Phân trang tệp cloud storage**.

Một tệp:

```text
morelogin://cloudfile?ids=1800000000001001
```

Nhiều tệp:

```text
morelogin://cloudfile?ids=1800000000001001,1800000000001002
```

Khi tham số RPA là loại media hoặc tệp, hãy giữ metadata `__Extra__` bắt buộc và đặt giá trị tham số là URI giao thức tệp đám mây:

```json
{
  "__Extra__": {
    "videoDownloadUrl": { "name": "video.mp4", "size": 204800000 }
  },
  "videoDownloadUrl": "morelogin://cloudfile?ids=1,2"
}
```

Điều này hữu ích cho các tác vụ RPA Cloud Phone theo lịch, mẫu trên marketplace, mẫu cá nhân, và bất kỳ tham số node RPA nào mong đợi một tệp đã tải lên dùng lại được. Runtime RPA phân giải tệp từ Cloud Storage của MoreLogin, nên tệp không cần được công khai qua URL HTTPS.

## Ví dụ hoàn chỉnh: chạy RPA Cloud Phone với một video trong Cloud Storage

Ví dụ này tải `video.mp4` lên Cloud Storage, gắn một thẻ, rồi tạo một tác vụ RPA Cloud Phone chạy một lần dùng tệp đã tải lên trong tham số mẫu `videoDownloadUrl`.

Ví dụ dùng đường dẫn Local API. Với Open API, hãy giữ nguyên body request và thay:

- `http://127.0.0.1:40000/api/cloudstorage/...` thành `https://api.morelogin.com/cloudstorage/...`
- `http://127.0.0.1:40000/api/cloudphone/...` thành `https://api.morelogin.com/cloudphone/...`


### 1. Tạo thẻ cho tài nguyên RPA

```bash
curl -X POST "http://127.0.0.1:40000/api/cloudstorage/tag/create" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tagName": "RPA Assets"
  }'
```

Lưu `id` của thẻ được trả về, ví dụ `1800000000000101`.

### 2. Xin URL tải lên đã ký trước

```bash
curl -X POST "http://127.0.0.1:40000/api/cloudstorage/upload/init" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileNames": ["video.mp4"]
  }'
```

Lưu `id` tệp được trả về và `presignedUrl`.

### 3. Tải nội dung nhị phân của tệp lên

Tải nội dung tệp lên `presignedUrl`. Request này đi tới URL object storage được trả về ở bước trước, không đi tới API MoreLogin.

```bash
curl -X PUT "PRESIGNED_URL_FROM_RESPONSE" \
  -H "Content-Type: video/mp4" \
  --data-binary "@video.mp4"
```

### 4. Xác nhận hoàn tất tải lên

```bash
curl -X POST "http://127.0.0.1:40000/api/cloudstorage/upload/complete" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1800000000000001
  }'
```

Lưu ID tệp Cloud Storage được trả về, ví dụ `1800000000001001`.

### 4.1 Gắn thẻ vào tệp

```bash
curl -X POST "http://127.0.0.1:40000/api/cloudstorage/file/tag/add" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": 1800000000001001,
    "tagIds": [1800000000000101]
  }'
```

Nếu phản hồi hoàn tất tải lên không trả về trực tiếp ID tệp, hãy truy vấn tệp theo trang:

```bash
curl -X POST "http://127.0.0.1:40000/api/cloudstorage/file/page" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pageNo": 1,
    "pageSize": 20,
    "fileName": "video",
    "tagIds": [1800000000000101]
  }'
```

### 5. Dựng tham số mẫu RPA

Dùng ID tệp Cloud Storage trong giao thức tệp đám mây của MoreLogin:

```text
morelogin://cloudfile?ids=1800000000001001
```

Với tham số mẫu RPA tên `videoDownloadUrl`, hãy dựng đối tượng JSON như sau:

```json
{
  "__Extra__": {
    "videoDownloadUrl": {
      "name": "video.mp4",
      "size": 204800000
    }
  },
  "videoDownloadUrl": "morelogin://cloudfile?ids=1800000000001001"
}
```

Sau đó escape nó thành chuỗi JSON cho `templateParameter`:

```json
"{\"__Extra__\":{\"videoDownloadUrl\":{\"name\":\"video.mp4\",\"size\":204800000}},\"videoDownloadUrl\":\"morelogin://cloudfile?ids=1800000000001001\"}"
```

### 6. Tạo tác vụ RPA Cloud Phone chạy một lần

Trước khi tạo tác vụ, hãy lấy `cloudPhoneId` từ API danh sách Cloud Phone và `templateId` từ API danh sách mẫu trên marketplace hoặc mẫu cá nhân.

```bash
curl -X POST "http://127.0.0.1:40000/api/cloudphone/rpa/onceTask/save" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cloudPhoneId": 1678331966138097,
    "scheduleName": "Upload video from Cloud Storage",
    "templateId": 1678347487160256,
    "templateParameter": "{\"__Extra__\":{\"videoDownloadUrl\":{\"name\":\"video.mp4\",\"size\":204800000}},\"videoDownloadUrl\":\"morelogin://cloudfile?ids=1800000000001001\"}",
    "description": "Use a Cloud Storage video file in a one-time Cloud Phone RPA task"
  }'
```

### 7. Kiểm tra tác vụ

Truy vấn danh sách tác vụ hoặc danh sách tác vụ con của RPA Cloud Phone để kiểm tra trạng thái chạy:

```bash
curl -X POST "http://127.0.0.1:40000/api/cloudphone/rpa/task/page" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pageNo": 1,
    "pageSize": 20,
    "taskName": "Upload video from Cloud Storage"
  }'
```

Điểm then chốt là tác vụ RPA nhận `videoDownloadUrl` dưới dạng `morelogin://cloudfile?ids=...`. MoreLogin phân giải tệp từ Cloud Storage lúc chạy, nên phần tích hợp của bạn không cần host tệp trên URL công khai.

## Luồng làm việc với thẻ

Thẻ là metadata dùng lại được cho các tệp cloud storage. Một tệp có thể có nhiều thẻ.

- Dùng **Tạo thẻ tệp cloud storage** để tạo các thẻ như `Invoices`, `APK`, `Customer A` hoặc `RPA Assets`.
- Dùng **Đặt thẻ cho tệp** khi bạn muốn ghi đè toàn bộ thẻ của một tệp.
- Dùng **Thêm thẻ cho tệp** khi bạn muốn thêm mà không xóa các thẻ hiện có.
- Dùng **Truy vấn toàn bộ thẻ tệp cloud storage** để dựng bộ lọc thẻ trong giao diện của bạn.
- Dùng **Truy vấn thẻ của tệp** để hiển thị những thẻ nào đang gắn với các tệp đã chọn.


Ví dụ: thêm một thẻ vào tệp mà không xóa các thẻ nó đang có.

```bash
curl -X POST "https://api.morelogin.com/cloudstorage/file/tag/add" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": 1800000000001001,
    "tagIds": [1800000000000103]
  }'
```

## Bản đồ API

| Tác vụ | Đường dẫn Open API | Đường dẫn Local API |
|  --- | --- | --- |
| Truy vấn thông tin lưu trữ | `GET /cloudstorage/info` | `GET /api/cloudstorage/info` |
| Phân trang tệp | `POST /cloudstorage/file/page` | `POST /api/cloudstorage/file/page` |
| Xin URL tải lên đã ký trước | `POST /cloudstorage/upload/init` | `POST /api/cloudstorage/upload/init` |
| Xác nhận hoàn tất tải lên | `POST /cloudstorage/upload/complete` | `POST /api/cloudstorage/upload/complete` |
| Xóa tệp hàng loạt | `POST /cloudstorage/file/delete/batch` | `POST /api/cloudstorage/file/delete/batch` |
| Đặt thẻ cho tệp | `POST /cloudstorage/file/tag/set` | `POST /api/cloudstorage/file/tag/set` |
| Thêm thẻ cho tệp | `POST /cloudstorage/file/tag/add` | `POST /api/cloudstorage/file/tag/add` |
| Truy vấn thẻ trên tệp | `POST /cloudstorage/file/tag/query` | `POST /api/cloudstorage/file/tag/query` |
| Truy vấn toàn bộ thẻ | `GET /cloudstorage/tag/all` | `GET /api/cloudstorage/tag/all` |
| Tạo thẻ | `POST /cloudstorage/tag/create` | `POST /api/cloudstorage/tag/create` |
| Sửa thẻ | `POST /cloudstorage/tag/edit` | `POST /api/cloudstorage/tag/edit` |
| Xóa thẻ | `POST /cloudstorage/tag/delete/batch` | `POST /api/cloudstorage/tag/delete/batch` |


## Tài liệu API

| API | Mô tả |
|  --- | --- |
| [Cloud Storage Open API](/vi/api-reference/cloud-storage/open-api) | Truy cập từ xa qua `https://api.morelogin.com`, xác thực OAuth2 |
| [Cloud Storage Local API](/vi/api-reference/cloud-storage/local-api) | Truy cập cục bộ qua `http://127.0.0.1:40000` |


> **Lưu ý**: đường dẫn Local API dùng tiền tố `/api/`. Đường dẫn Open API thì không.