# Cloud Storage

O Cloud Storage é um espaço de arquivos no nível da equipe para guardar arquivos que precisam ser reutilizados nos fluxos de automação do MoreLogin. Use-o para enviar um arquivo uma vez, organizá-lo com tags, encontrá-lo depois e excluir o que não é mais necessário.

Ele é separado das APIs de transferência de arquivos do Cloud Phone. As APIs de arquivo do Cloud Phone movem arquivos para dentro ou para fora de uma instância de aparelho específica. As APIs do Cloud Storage gerenciam a biblioteca de arquivos compartilhada antes de um arquivo ser usado por aparelhos, agendamentos, modelos de RPA ou outra lógica de automação.

## O que você pode fazer

| Recurso | Para que serve | APIs relacionadas |
|  --- | --- | --- |
| Visão geral do armazenamento | Verifique a capacidade total, a capacidade usada, a data de expiração e o status de capacidade antes de enviar ou limpar arquivos. | Consultar informações do cloud storage |
| Busca de arquivos | Liste os arquivos do cloud storage por página e filtre por nome, tipo, tag ou ID do arquivo. | Paginar arquivos do cloud storage |
| Envio de arquivos | Solicite URLs de upload pré-assinadas, envie o conteúdo ao object storage e depois confirme a conclusão no MoreLogin. | Solicitar em lote URLs de upload pré-assinadas, confirmar a conclusão do upload |
| Limpeza de arquivos | Exclua um ou mais arquivos da biblioteca compartilhada. | Excluir em lote arquivos do cloud storage |
| Marcação de arquivos | Substitua ou acrescente tags para organizar arquivos por projeto, cliente, uso ou fluxo. | Definir tags do arquivo, adicionar tags ao arquivo, consultar tags do arquivo |
| Gerenciamento de tags | Crie, edite, liste e exclua tags de arquivo reutilizáveis. | Consultar todas as tags, criar tag, editar tag, excluir tags |


## Casos de uso comuns

- Envie APKs, arquivos de mídia, documentos ou recursos de teste uma vez e reutilize-os na automação.
- Mantenha os arquivos organizados por cliente, campanha, versão do aplicativo, ambiente ou fluxo.
- Crie um seletor de arquivos na sua ferramenta interna chamando a API de paginação com filtros de nome e tag.
- Limpe em lote os arquivos expirados ou não usados depois que um fluxo termina.
- Sincronize um sistema externo de recursos com o MoreLogin criando tags e anexando-as aos arquivos enviados.


## Acesso à API

| Método | URL base | Prefixo do caminho | Caso de uso |
|  --- | --- | --- | --- |
| **Open API** | `https://api.morelogin.com` | `/cloudstorage` | Acesso servidor a servidor, ferramentas remotas, CI/CD, serviços de backend |
| **Local API** | `http://127.0.0.1:40000` | `/api/cloudstorage` | Scripts ou ferramentas de desktop rodando na mesma máquina que o cliente MoreLogin |


Para detalhes de autenticação, veja [Autenticação](/pt/api-reference/getting-started/authentication).

## Fluxo de upload

Os uploads do Cloud Storage usam um fluxo de URL pré-assinada. Seu código não envia o arquivo binário diretamente para a API do MoreLogin.

1. Chame **Solicitar em lote URLs de upload pré-assinadas** com uma lista de nomes de arquivo (com extensão).
2. Para cada item retornado, envie o arquivo binário para `presignedUrl` com `PUT` por HTTPS.
3. Chame **Confirmar a conclusão do upload** com o `id` do arquivo retornado.
4. Use **Paginar arquivos do cloud storage** ou **Consultar tags do arquivo** para verificar e exibir o arquivo enviado.


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

Para a Local API, mantenha o mesmo corpo de requisição e substitua o caminho por `http://127.0.0.1:40000/api/cloudstorage/...`.

## Usar arquivos do Cloud Storage no RPA do Cloud Phone

Depois que um arquivo é enviado e confirmado, os parâmetros de modelo do RPA do Cloud Phone podem referenciá-lo pelo ID de arquivo do Cloud Storage. Use o protocolo de arquivo em nuvem do MoreLogin em vez de uma URL de download pública externa:

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

`ids` é uma lista de IDs de arquivo do Cloud Storage separados por vírgula. Use apenas vírgulas inglesas, sem espaços. Você pode obter os IDs de arquivo na resposta de conclusão do upload ou em **Paginar arquivos do cloud storage**.

Arquivo único:

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

Vários arquivos:

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

Quando o parâmetro do RPA é de mídia ou arquivo, mantenha os metadados obrigatórios `__Extra__` e defina o valor do parâmetro como o URI do protocolo de arquivo em nuvem:

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

Isso é útil para tarefas agendadas de RPA do Cloud Phone, modelos do marketplace, modelos pessoais e qualquer parâmetro de nó de RPA que espere um arquivo enviado reutilizável. O runtime do RPA resolve o arquivo a partir do Cloud Storage do MoreLogin, então o arquivo não precisa ser exposto em uma URL HTTPS pública.

## Exemplo completo: executar RPA do Cloud Phone com um vídeo do Cloud Storage

Este exemplo envia `video.mp4` para o Cloud Storage, anexa uma tag e depois cria uma tarefa única de RPA do Cloud Phone que usa o arquivo enviado no parâmetro de modelo `videoDownloadUrl`.

O exemplo usa caminhos da Local API. Para a Open API, mantenha os mesmos corpos de requisição e substitua:

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


### 1. Criar uma tag para recursos de 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"
  }'
```

Salve o `id` da tag retornada, por exemplo `1800000000000101`.

### 2. Solicitar uma URL de upload pré-assinada

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

Salve o `id` do arquivo retornado e o `presignedUrl`.

### 3. Enviar o binário do arquivo

Envie o conteúdo do arquivo para `presignedUrl`. Essa requisição vai para a URL do object storage retornada na etapa anterior, e não para a API do MoreLogin.

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

### 4. Confirmar a conclusão do upload

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

Salve o ID de arquivo do Cloud Storage retornado, por exemplo `1800000000001001`.

### 4.1 Anexar a tag ao arquivo

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

Se a sua resposta de conclusão do upload não incluir o ID do arquivo diretamente, consulte os arquivos por página:

```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. Montar o parâmetro de modelo do RPA

Use o ID de arquivo do Cloud Storage no protocolo de arquivo em nuvem do MoreLogin:

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

Para um parâmetro de modelo de RPA chamado `videoDownloadUrl`, monte o objeto JSON assim:

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

Depois escape-o como string JSON para `templateParameter`:

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

### 6. Criar uma tarefa única de RPA do Cloud Phone

Antes de criar a tarefa, obtenha `cloudPhoneId` na API de listagem do Cloud Phone e `templateId` na API de listagem de modelos do marketplace ou pessoais.

```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. Verificar a tarefa

Consulte a lista de tarefas ou de subtarefas de RPA do Cloud Phone para verificar o status de execução:

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

O ponto principal é que a tarefa de RPA recebe `videoDownloadUrl` como `morelogin://cloudfile?ids=...`. O MoreLogin resolve o arquivo a partir do Cloud Storage em tempo de execução, então sua integração não precisa hospedar o arquivo em uma URL pública.

## Fluxo de tags

Tags são metadados reutilizáveis para arquivos do cloud storage. Um arquivo pode ter várias tags.

- Use **Criar tag de arquivo do cloud storage** para criar tags como `Invoices`, `APK`, `Customer A` ou `RPA Assets`.
- Use **Definir tags do arquivo** quando quiser sobrescrever todas as tags de um arquivo.
- Use **Adicionar tags ao arquivo** quando quiser acrescentar sem remover as tags existentes.
- Use **Consultar todas as tags de arquivo do cloud storage** para montar filtros de tag na sua interface.
- Use **Consultar tags do arquivo** para mostrar quais tags estão nos arquivos selecionados.


Exemplo: acrescentar uma tag a um arquivo sem remover as que ele já tem.

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

## Mapa de APIs

| Tarefa | Caminho da Open API | Caminho da Local API |
|  --- | --- | --- |
| Consultar informações de armazenamento | `GET /cloudstorage/info` | `GET /api/cloudstorage/info` |
| Paginar arquivos | `POST /cloudstorage/file/page` | `POST /api/cloudstorage/file/page` |
| Solicitar URLs de upload pré-assinadas | `POST /cloudstorage/upload/init` | `POST /api/cloudstorage/upload/init` |
| Confirmar a conclusão do upload | `POST /cloudstorage/upload/complete` | `POST /api/cloudstorage/upload/complete` |
| Excluir arquivos em lote | `POST /cloudstorage/file/delete/batch` | `POST /api/cloudstorage/file/delete/batch` |
| Definir tags do arquivo | `POST /cloudstorage/file/tag/set` | `POST /api/cloudstorage/file/tag/set` |
| Adicionar tags ao arquivo | `POST /cloudstorage/file/tag/add` | `POST /api/cloudstorage/file/tag/add` |
| Consultar tags nos arquivos | `POST /cloudstorage/file/tag/query` | `POST /api/cloudstorage/file/tag/query` |
| Consultar todas as tags | `GET /cloudstorage/tag/all` | `GET /api/cloudstorage/tag/all` |
| Criar tag | `POST /cloudstorage/tag/create` | `POST /api/cloudstorage/tag/create` |
| Editar tag | `POST /cloudstorage/tag/edit` | `POST /api/cloudstorage/tag/edit` |
| Excluir tags | `POST /cloudstorage/tag/delete/batch` | `POST /api/cloudstorage/tag/delete/batch` |


## Referência da API

| API | Descrição |
|  --- | --- |
| [Cloud Storage Open API](/pt/api-reference/cloud-storage/open-api) | Acesso remoto via `https://api.morelogin.com`, autenticação OAuth2 |
| [Cloud Storage Local API](/pt/api-reference/cloud-storage/local-api) | Acesso local via `http://127.0.0.1:40000` |


> **Nota**: os caminhos da Local API usam o prefixo `/api/`. Os da Open API o omitem.