# Хмарне сховище

Хмарне сховище — це файловий простір на рівні команди для файлів, які багаторазово використовуються у сценаріях автоматизації MoreLogin. Завантажте файл один раз, упорядкуйте його теґами, знайдіть пізніше та видаліть, коли він більше не потрібен.

Це не те саме, що API передавання файлів хмарного телефона. API файлів хмарного телефона переміщують файли до конкретного примірника пристрою і назад. API хмарного сховища керують спільною бібліотекою файлів до того, як файл використають пристрої, розклади, шаблони RPA або інша логіка автоматизації.

## Що можна робити

| Можливість | Для чого | Пов'язані API |
|  --- | --- | --- |
| Огляд сховища | Перевірте загальний обсяг, використаний обсяг, дату завершення та стан обсягу перед завантаженням або очищенням файлів. | Запит інформації про хмарне сховище |
| Пошук файлів | Постранично виведіть файли хмарного сховища та відфільтруйте за назвою, типом, теґом або ID файлу. | Постраничний список файлів хмарного сховища |
| Завантаження файлів | Запросіть попередньо підписані URL для завантаження, надішліть вміст до об'єктного сховища, потім підтвердьте завершення в MoreLogin. | Пакетний запит попередньо підписаних URL, підтвердження завершення завантаження |
| Очищення файлів | Видаліть один або кілька файлів зі спільної бібліотеки. | Пакетне видалення файлів хмарного сховища |
| Теґи файлів | Замініть або додайте теґи, щоб упорядкувати файли за проєктом, клієнтом, призначенням або сценарієм. | Установлення теґів файлу, додавання теґів файлу, запит теґів файлу |
| Керування теґами | Створюйте, змінюйте, виводьте та видаляйте повторно використовувані теґи файлів. | Запит усіх теґів, створення теґа, зміна теґа, видалення теґів |


## Типові сценарії

- Завантажте APK, медіафайли, документи або тестові матеріали один раз і використовуйте їх в автоматизації повторно.
- Тримайте файли впорядкованими за клієнтом, кампанією, версією застосунку, середовищем або сценарієм.
- Зробіть вибір файлів у своєму внутрішньому інструменті, викликаючи постраничний API з фільтрами за назвою та теґом.
- Пакетно очищайте прострочені або невикористовувані файли після завершення сценарію.
- Зв'яжіть зовнішню систему матеріалів із MoreLogin, створюючи теґи та призначаючи їх завантаженим файлам.


## Доступ до API

| Спосіб | Базовий URL | Префікс шляху | Сценарій |
|  --- | --- | --- | --- |
| **Open API** | `https://api.morelogin.com` | `/cloudstorage` | Взаємодія між серверами, віддалені інструменти, CI/CD, бекенд-сервіси |
| **Local API** | `http://127.0.0.1:40000` | `/api/cloudstorage` | Скрипти або настільні інструменти на тій самій машині, де працює клієнт MoreLogin |


Подробиці аутентифікації див. у розділі [Аутентифікація](/uk/api-reference/getting-started/authentication).

## Потік завантаження

Завантаження до хмарного сховища використовує попередньо підписані URL. Ваш код не надсилає двійковий файл напряму до API MoreLogin.

1. Викличте **Пакетний запит попередньо підписаних URL для завантаження**, передавши список назв файлів (з розширеннями).
2. Для кожного повернутого елемента надішліть двійковий файл на `presignedUrl` методом `PUT` через HTTPS.
3. Викличте **Підтвердження завершення завантаження** з повернутим `id` файлу.
4. Перевірте та покажіть завантажений файл через **Постраничний список файлів хмарного сховища** або **Запит теґів файлу**.


```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
  }'
```

Для Local API залиште те саме тіло запиту та замініть шлях на `http://127.0.0.1:40000/api/cloudstorage/...`.

## Використання файлів хмарного сховища в RPA хмарного телефона

Після завантаження та підтвердження файлу параметри шаблона RPA хмарного телефона можуть посилатися на нього за ID файлу в хмарному сховищі. Використовуйте протокол хмарних файлів MoreLogin замість зовнішнього публічного URL для завантаження:

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

`ids` — це список ID файлів хмарного сховища через кому. Використовуйте лише англійські коми без пробілів. ID файлів можна отримати з відповіді про завершення завантаження або з **Постраничного списку файлів хмарного сховища**.

Один файл:

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

Кілька файлів:

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

Якщо параметр RPA стосується медіа або файлу, збережіть обов'язкові метадані `__Extra__` і задайте значенням параметра URI протоколу хмарних файлів:

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

Це зручно для запланованих задач RPA хмарного телефона, шаблонів із маркетплейсу, особистих шаблонів і будь-якого параметра вузла RPA, який очікує повторно використовуваний завантажений файл. Середовище виконання RPA отримує файл із хмарного сховища MoreLogin, тому файл не потрібно публікувати за загальнодоступною HTTPS-адресою.

## Повний приклад: запуск RPA хмарного телефона з відео з хмарного сховища

У цьому прикладі `video.mp4` завантажується до хмарного сховища, до нього додається теґ, а потім створюється одноразова задача RPA хмарного телефона, яка використовує завантажений файл у параметрі шаблона `videoDownloadUrl`.

У прикладі використано шляхи Local API. Для Open API залиште ті самі тіла запитів і замініть:

- `http://127.0.0.1:40000/api/cloudstorage/...` на `https://api.morelogin.com/cloudstorage/...`
- `http://127.0.0.1:40000/api/cloudphone/...` на `https://api.morelogin.com/cloudphone/...`


### 1. Створіть теґ для матеріалів 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"
  }'
```

Збережіть `id` повернутого теґа, наприклад `1800000000000101`.

### 2. Запросіть попередньо підписаний URL для завантаження

```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"]
  }'
```

Збережіть повернуті `id` файлу та `presignedUrl`.

### 3. Надішліть двійковий вміст файлу

Надішліть вміст файлу на `presignedUrl`. Цей запит іде на URL об'єктного сховища, повернутий на попередньому кроці, а не до API MoreLogin.

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

### 4. Підтвердьте завершення завантаження

```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
  }'
```

Збережіть повернутий ID файлу хмарного сховища, наприклад `1800000000001001`.

### 4.1 Призначте теґ файлу

```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]
  }'
```

Якщо відповідь про завершення завантаження не містить ID файлу напряму, запросіть файли постранично:

```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. Складіть параметр шаблона RPA

Використайте ID файлу хмарного сховища у протоколі хмарних файлів MoreLogin:

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

Для параметра шаблона RPA з назвою `videoDownloadUrl` складіть об'єкт JSON так:

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

Потім екрануйте його як рядок JSON для `templateParameter`:

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

### 6. Створіть одноразову задачу RPA хмарного телефона

Перед створенням задачі отримайте `cloudPhoneId` з API списку хмарних телефонів і `templateId` з API списку шаблонів маркетплейсу або особистих шаблонів.

```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. Перевірте задачу

Запросіть список задач або підзадач RPA хмарного телефона, щоб перевірити стан виконання:

```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"
  }'
```

Головне — задача RPA отримує `videoDownloadUrl` у вигляді `morelogin://cloudfile?ids=...`. MoreLogin отримує файл із хмарного сховища під час виконання, тому вашій інтеграції не потрібно розміщувати файл за публічним URL.

## Робота з теґами

Теґи — це повторно використовувані метадані для файлів хмарного сховища. Файл може мати кілька теґів.

- Використовуйте **Створення теґа файлу хмарного сховища**, щоб створити теґи на кшталт `Invoices`, `APK`, `Customer A` або `RPA Assets`.
- Використовуйте **Установлення теґів файлу**, коли потрібно перезаписати всі теґи файлу.
- Використовуйте **Додавання теґів файлу**, коли потрібно додати теґи, не видаляючи наявні.
- Використовуйте **Запит усіх теґів файлів хмарного сховища**, щоб побудувати фільтри за теґами у своєму інтерфейсі.
- Використовуйте **Запит теґів файлу**, щоб показати, які теґи призначені вибраним файлам.


Приклад: додати теґ до файлу, не видаляючи наявні.

```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]
  }'
```

## Карта API

| Задача | Шлях Open API | Шлях Local API |
|  --- | --- | --- |
| Запит інформації про сховище | `GET /cloudstorage/info` | `GET /api/cloudstorage/info` |
| Постраничний список файлів | `POST /cloudstorage/file/page` | `POST /api/cloudstorage/file/page` |
| Запит попередньо підписаних URL для завантаження | `POST /cloudstorage/upload/init` | `POST /api/cloudstorage/upload/init` |
| Підтвердження завершення завантаження | `POST /cloudstorage/upload/complete` | `POST /api/cloudstorage/upload/complete` |
| Пакетне видалення файлів | `POST /cloudstorage/file/delete/batch` | `POST /api/cloudstorage/file/delete/batch` |
| Установлення теґів файлу | `POST /cloudstorage/file/tag/set` | `POST /api/cloudstorage/file/tag/set` |
| Додавання теґів файлу | `POST /cloudstorage/file/tag/add` | `POST /api/cloudstorage/file/tag/add` |
| Запит теґів на файлах | `POST /cloudstorage/file/tag/query` | `POST /api/cloudstorage/file/tag/query` |
| Запит усіх теґів | `GET /cloudstorage/tag/all` | `GET /api/cloudstorage/tag/all` |
| Створення теґа | `POST /cloudstorage/tag/create` | `POST /api/cloudstorage/tag/create` |
| Зміна теґа | `POST /cloudstorage/tag/edit` | `POST /api/cloudstorage/tag/edit` |
| Видалення теґів | `POST /cloudstorage/tag/delete/batch` | `POST /api/cloudstorage/tag/delete/batch` |


## Довідник API

| API | Опис |
|  --- | --- |
| [Cloud Storage Open API](/uk/api-reference/cloud-storage/open-api) | Віддалений доступ через `https://api.morelogin.com`, аутентифікація OAuth2 |
| [Cloud Storage Local API](/uk/api-reference/cloud-storage/local-api) | Локальний доступ через `http://127.0.0.1:40000` |


> **Примітка**: шляхи Local API використовують префікс `/api/`. Шляхи Open API його не містять.