Biblioteca `Storage` da Azion

Aprenda a usar a biblioteca Storage para interagir com a API do Object Storage.

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.

Saiba mais sobre as Azion Libraries

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:

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).

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:

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`	Um objeto com métodos para interagir com o Storage.

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.

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:

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:

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:

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`	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:

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`	Parâmetros para filtragem e paginação.
`options?`	`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:

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`	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:

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:

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`	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:

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`	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:

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`	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:

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`	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:

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`	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.

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

'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.