# Облачное хранилище

Облачное хранилище — это файловое пространство уровня команды для файлов, которые многократно используются в сценариях автоматизации 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 |


Подробности аутентификации см. в разделе [Аутентификация](/ru/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](/ru/api-reference/cloud-storage/open-api) | Удалённый доступ через `https://api.morelogin.com`, аутентификация OAuth2 |
| [Cloud Storage Local API](/ru/api-reference/cloud-storage/local-api) | Локальный доступ через `http://127.0.0.1:40000` |


> **Примечание**: пути Local API используют префикс `/api/`. Пути Open API его не содержат.