# Biblioteca `Storage` da Azion

import DocButton from '~/components/webkit/DocButton.vue';

A biblioteca **Object Storage** fornece métodos para interagir com a API do **Object Storage**, permitindo que você gerencie buckets e objetos. Este cliente é configurável e suporta tanto o modo de debug quanto a configuração baseada em variáveis de ambiente.

A biblioteca também inclui um utilitário conveniente `setupStorage` que garante que um bucket exista antes de realizar operações.

<DocButton href="/pt-br/documentacao/produtos/azion-lib/visao-geral/" label="Saiba mais sobre as Azion Libraries" kind="secondary" size="medium" />

Você pode interagir com a API usando um `client` ou chamando os métodos diretamente da biblioteca. Quando fizer chamadas diretas, você pode usar as variáveis de ambiente para configurar o `client` sem passar os parâmetros de token e debug diretamente.

Este é um exemplo de como um arquivo `.env` com suas variáveis de ambiente pode ficar:

```sh
AZION_TOKEN=<your-api-token>
AZION_DEBUG=true
```

| Variável | Descrição |
|----------|-------------|
| `AZION_TOKEN` | Seu token de API da Azion. |
| `AZION_DEBUG` | Ativar o **modo de debug** (true/false). |

:::tip
Defina `AZION_DEBUG` como `true` para ativar o **modo de debug**. Nesse modo, as requisições de API e respostas são registradas em detalhes.
:::

Se você quiser criar um `client` específico para interagir com o **Storage**, faça isso chamando o método `createClient` da biblioteca:

```typescript
import { createClient } from 'azion/storage';
import type { AzionStorageClient, AzionStorageResponse, AzionStorage } from 'azion/storage';

const client: AzionStorageClient = createClient({ token: 'your-api-token', options: { debug: true } });

const { data, error } = await client.createBucket('my-new-bucket');
if (data) {
  console.log(`Bucket created with ID: ${data.id}`);
} else {
  console.error('Failed to create bucket', error);
}
```

O método `createClient` tem os seguintes **parâmetros** e **valor de retorno**:

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `config` | `Partial<{ token: string; options?: AzionClientOptions }>` | Configurações do `client` do Storage. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| [`AzionStorageClient`](#azionstorageclient) | Um objeto com métodos para interagir com o Storage. |

:::note
Nos exemplos a seguir, os métodos são chamados diretamente sem a criação de um `client`. Para obter mais informações sobre como interagir com serviços e produtos usando um `client`, verifique a [documentação do cliente da Azion Lib](/pt-br/documentacao/produtos/azion-lib/client/).
:::

---

## Uso

### `setupStorage`

Garante que um bucket exista, primeiro tentando obter um bucket existente e, se não existir, criando-o automaticamente. Isso é útil para scripts de inicialização ou para garantir que seu armazenamento esteja pronto para uso.

Exemplo:

```typescript
import { setupStorage } from 'azion/storage';
import type { AzionStorageResponse, AzionBucket } from 'azion/storage';

const { data: bucket, error }: AzionStorageResponse<AzionBucket> = await setupStorage({
  name: 'meu-bucket-app',
  workloads_access: 'read_write',
});
if (bucket) {
  console.log(`Storage pronto: ${bucket.name}`);
  // Agora você pode usar o bucket com segurança para operações
  await bucket.createObject({
    key: 'config.json',
    content: '{}',
    params: { content_type: 'application/json' },
  });
} else {
  console.error('Falha ao configurar storage', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do bucket a ser obtido ou criado. |
| `workloads_access` | `string` | A configuração de acesso de workloads para o bucket se precisar ser criado. Valores possíveis: `'read_only'`, `'read_write'`, `'restricted'`. |
| `options?` | `AzionClientOptions` | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionBucket>>` | O bucket existente ou recém-criado, ou erro. |

---

### `createBucket`

Cria um novo bucket.

Exemplo:

```typescript
import { createBucket } from 'azion/storage';
import type { AzionStorageResponse, AzionBucket } from 'azion/storage';
const { data, error }: AzionStorageResponse<AzionBucket> = await createBucket({
  name: 'my-new-bucket',
  workloads_access: 'read_only',
});
if (data) {
  console.log(`Bucket created with name: ${data.name}`);
} else {
  console.error('Failed to create bucket', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do novo bucket. |
| `workloads_access` | `string` | A configuração de acesso de workloads do bucket. Valores possíveis: `'read_only'`, `'read_write'`, `'restricted'`. |
| `options?` | `AzionClientOptions` | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionBucket>>` | O objeto do bucket criado ou o erro em caso de falha. |

### `deleteBucket`

Exclui um bucket pelo seu nome.

Exemplo:

```typescript
import { deleteBucket, AzionDeletedBucket, AzionStorageResponse } from 'azion/storage';

const { data, error }: AzionStorageResponse<AzionDeletedBucket> = await deleteBucket({ name: 'my-bucket' });
if (data) {
  console.log(`Bucket ${data.name} deleted successfully`);
} else {
  console.error('Failed to delete bucket', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do bucket a ser excluído. |
| `options?` | [`AzionClientOptions`](#azionclientoptions) | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionDeletedBucket>>` | Confirmação de exclusão ou o erro em caso de falha. |

### `getBuckets`

Recupera uma lista de buckets com filtragem e paginação opcional.

Exemplo:

```typescript
import { getBuckets, AzionStorageResponse, AzionBucketCollection } from 'azion/storage';

const { data: buckets, error }: AzionStorageResponse<AzionBucketCollection> = await getBuckets({
  params: { page: 1, page_size: 10 },
});
if (buckets) {
  console.log(`Retrieved ${buckets.count} buckets`);
} else {
  console.error('Failed to retrieve buckets', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `params?` | [`AzionBucketCollectionParams`](#azionbucketcollectionparams) | Parâmetros para filtragem e paginação. |
| `options?` | [`AzionClientOptions`](#azionclientoptions) | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionBucketCollection>>` | Array de objetos de bucket ou erro. |

### `getBucket`

Recupera um bucket pelo seu nome.

Exemplo:

```typescript
import { getBucket, AzionBucket } from 'azion/storage';

const { data: bucket, error }: AzionStorageResponse<AzionBucket> = await getBucket({ name: 'my-bucket' });
if (bucket) {
  console.log(`Retrieved bucket: ${bucket.name}`);
} else {
  console.error('Bucket not found', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do bucket a ser atualizado. |
| `options?` | [`AzionClientOptions`](#azionclientoptions) | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionBucket>>` | O objeto de bucket atualizado ou o erro em caso de falha. |

### `updateBucket`

Atualiza um bucket existente.

Exemplo:

```typescript
import { updateBucket, AzionBucket, AzionStorageResponse } from 'azion/storage';

const { data: updatedBucket, error }: AzionStorageResponse<AzionBucket> | null = await updateBucket({
  name: 'my-bucket',
  workloads_access: 'read_write',
});
if (updatedBucket) {
  console.log(`Bucket updated: ${updatedBucket.name}`);
} else {
  console.error('Failed to update bucket', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do bucket a ser atualizado. |
| `workloads_access` | `string` | A nova configuração de acesso de workloads para o bucket. Valores possíveis: `'read_only'`, `'read_write'`, `'restricted'`. |
| `debug?` | `boolean` | Ativa o modo de debug para logs detalhados. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionBucket>>` | O objeto do bucket atualizado ou o erro em caso de falha. |

### `createObject`

Cria um novo objeto em um bucket específico.

Exemplo:

```typescript
import { createObject, AzionBucketObject, AzionStorageResponse } from 'azion/storage';

const { data: newObject, error }: AzionStorageResponse<AzionBucketObject> = await createObject({
  name: 'my-bucket',
  key: 'new-file.txt',
  content: 'File content',
});
if (newObject) {
  console.log(`Object created with key: ${newObject.key}`);
  console.log(`Object content: ${newObject.content}`);
} else {
  console.error('Failed to create object', error);
}
```

**Parâmetros**:

| Parâmetro   | Tipo     | Descrição                                   |
|-------------|----------|---------------------------------------------|
| `name` | `string` | O nome do bucket onde o objeto será criado. |
| `key`  | `string` | A chave (nome) do objeto a ser criado. |
| `content` | `string` | O conteúdo do arquivo a ser enviado. |
| `options?` | [`AzionClientOptions`](#azionclientoptions) | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno                            | Descrição                                   |
|--------------------------------------------|---------------------------------------------|
| `Promise< AzionBucketObject \| null>`      | O objeto criado ou nulo se a criação falhar. |

### `getObjectByKey`

Recupera um objeto de um bucket específico pela sua chave.

Exemplo:

```typescript
import { getObjectByKey, AzionBucketObject, AzionStorageResponse } from 'azion/storage';

const { data: object, error }: AzionStorageResponse<AzionBucketObject> = await getObjectByKey({
  name: 'my-bucket',
  key: 'file.txt',
});
if (object) {
  console.log(`Retrieved object: ${object.key}`);
} else {
  console.error('Object not found', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do bucket contendo o objeto. |
| `key` | `string` | A chave do objeto a ser recuperado. |
| `options?` | [`AzionClientOptions`](#azionclientoptions) | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise< AzionBucketObject \| null>` | O objeto recuperado ou nulo se não encontrado. |

### `getObjects`

Recupera uma lista de objetos em um bucket específico.

Exemplo:

```typescript
import { getObjects, AzionBucketObject, AzionStorageResponse } from 'azion/storage';

const { data: objectResult, error }: AzionStorageResponse<AzionBucketObjects> = await getObjects({
  name: 'my-bucket',
});
if (objectResult) {
  console.log(`Retrieved ${objectResult.count} objects from the bucket`);
} else {
  console.error('Failed to retrieve objects', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do bucket a partir do qual os objetos devem ser recuperados. |
| `options?` | [`AzionClientOptions`](#azionclientoptions) | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionBucketObjects>>` | Array de objetos do bucket ou erro. |

### `updateObject`

Atualiza um objeto existente em um bucket específico.

Exemplo:

```typescript
import { updateObject, AzionBucketObject } from 'azion/storage';

const { data: updatedObject, error }: AzionStorageResponse<AzionBucketObject> = await updateObject({
  name: 'my-bucket',
  key: 'file.txt',
  content: 'Updated content',
});
if (updatedObject) {
  console.log(`Object updated: ${updatedObject.key}`);
  console.log(`New content: ${updatedObject.content}`);
} else {
  console.error('Failed to update object', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do bucket que contém o objeto. |
| `key` | `string` | O nome do objeto a ser atualizado. |
| `content` | `string` | O novo conteúdo do arquivo. |
| `options?` | [`AzionClientOptions`](#azionclientoptions) | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionBucketObject>>` | O objeto atualizado ou o erro caso a atualização tenha falhado. |

### `deleteObject`

Exclui um objeto de um bucket específico.

Exemplo:

```typescript
import { deleteObject, AzionDeletedBucketObject, AzionStorageResponse } from 'azion/storage';

const { data: result, error }: AzionStorageResponse<AzionDeletedBucketObject> = await deleteObject({
  name: 'my-bucket',
  key: 'file.txt',
});
if (result) {
  console.log(`Object ${result.key} deleted successfully`);
} else {
  console.error('Failed to delete object', error);
}
```

**Parâmetros**:

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `name` | `string` | O nome do bucket que contém o objeto. |
| `key` | `string` | O nome do objeto a ser excluído. |
| `options?` | [`AzionClientOptions`](#azionclientoptions) | Parâmetros opcionais para a requisição. |

**Retorno**:

| Tipo de retorno | Descrição |
|-------------|-------------|
| `Promise<AzionStorageResponse<AzionDeletedBucketObject>>` | Confirmação de exclusão ou o erro caso a exclusão tenha falhado. |

---

## Tipos

Estes são os tipos usados pela biblioteca **Storage** e seus métodos:

### AzionBucketCollectionParams

Parâmetros para filtragem e paginação ao solicitar uma coleção de buckets.

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `page?` | `number` | O número da página para paginação. |
| `page_size?` | `number` | O número de itens por página. |

### `AzionObjectCollectionParams`

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `max_object_count?` | `number` | O número máximo de objetos a serem retornados. |

### `EdgeAccessType`

O tipo de controle de acesso para o bucket.

```typescript
'read_only' | 'read_write' | 'restricted'
```

### `AzionClientOptions`

Opções de configuração para o `client` de Storage.

| Parâmetro | Tipo | Descrição |
|-----------|------|-------------|
| `debug?` | `boolean` | Ativa o modo de debug para logs detalhados. |
| `force?` | `boolean` | Força a operação mesmo que possa ser destrutiva. |
| `env?` | [`AzionEnvironment`](#azionenvironment) | Ambiente a ser utilizado (desenvolvimento, homologação, produção). |
| `external?` | `boolean` | Força o uso da API REST externa em vez da API interna do runtime. |

### AzionEnvironment

O ambiente em que o cliente opera.

```typescript
'development' | 'staging' | 'production'
```

### `StorageClient`

Um objeto com métodos para interagir com o Storage.

| Método | Parâmetros | Tipo de retorno |
|--------|------------|-----------------|
| `getBuckets` | `options?: BucketCollectionOptions` | `Promise<AzionStorageResponse<AzionBucketCollection>>` |
| `createBucket` | `name: string, workloads_access: string` | `Promise<AzionStorageResponse<AzionBucket>>` |
| `updateBucket` | `name: string, workloads_access: string` | `Promise<AzionStorageResponse<AzionBucket>>` |
| `deleteBucket` | `name: string` | `Promise<AzionStorageResponse<AzionDeletedBucket>>` |
| `getBucket` | `name: string` | `Promise<AzionStorageResponse<AzionBucket>>` |

### `AzionStorageResponse<T>`

O objeto de resposta de uma operação de bucket.

| Propriedade | Tipo | Descrição |
|-------------|------|-------------|
| `data` | `T` (opcional) | O objeto genérico de dados. |
| `error` | `{ message: string; operation: string; }` (opcional) | Os detalhes do erro se a operação falhar. |

### `AzionBucket`

O objeto bucket.

| Propriedade | Tipo | Descrição |
|-------------|------|-------------|
| `name` | `string` | O nome do bucket. |
| `workloads_access` | `string` (opcional) | A configuração de acesso de workloads do bucket. |
| `state` | `'executed' \| 'pending'` (opcional) | O estado do bucket. |
| `last_editor` | `string` (opcional) | O último editor do bucket. |
| `last_modified` | `string` (opcional) | O timestamp da última modificação. |
| `product_version` | `string` (opcional) | A versão do produto. |
| `getObjects` | `() => Promise<AzionStorageResponse<AzionBucketObjects>>` (opcional) | Um método para obter todos os objetos no bucket. |
| `getObjectByKey` | `(objectKey: string) => Promise<AzionStorageResponse<AzionBucketObject>>` (opcional) | Um método para obter um objeto pela sua chave. |
| `createObject` | `(objectKey: string, file: string) => Promise<AzionStorageResponse<AzionBucketObject>>` (opcional) | Um método para criar um novo objeto no bucket. |
| `updateObject` | `(objectKey: string, file: string) => Promise<AzionStorageResponse<AzionBucketObject>>` (opcional) | Um método para atualizar um objeto existente no bucket. |
| `deleteObject` | `(objectKey: string) => Promise<AzionStorageResponse<AzionDeletedBucketObject>>` (opcional) | Um método para excluir um objeto do bucket. |

### `AzionBucketObject`

O objeto do bucket.

| Propriedade | Tipo | Descrição |
|-------------|------|-------------|
| `key` | `string` | A chave do objeto. |
| `state` | `'executed' \| 'pending'` (opcional) | O estado do objeto. |
| `size` | `number` (opcional) | O tamanho do objeto. |
| `last_modified` | `string` (opcional) | A data da última modificação do objeto. |
| `content_type` | `string` (opcional) | O tipo de conteúdo do objeto. |
| `content` | `string` (opcional) | O conteúdo do objeto. |

### `AzionDeletedBucket`

O objeto de resposta de uma requisição de exclusão de bucket.

| Propriedade | Tipo | Descrição |
|-------------|------|-------------|
| `name` | `string` | O nome do bucket. |
| `state` | `'executed' \| 'pending'` | O estado do bucket. |

### `AzionDeletedBucketObject`

O objeto de resposta de uma requisição de exclusão de objeto.

| Propriedade | Tipo | Descrição |
|-------------|------|-------------|
| `key` | `string` | A chave do objeto excluído. |
| `state` | `'executed' \| 'pending'` | O estado da operação de exclusão. |