Biblioteca `Storage` da Azion

A biblioteca Edge Storage fornece métodos para interagir com a API do Edge 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.

Saiba mais das 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).

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?: OptionsParams }>`	Configurações do `client` do Storage.

Retorno:

Tipo de retorno	Descrição
`AzionStorageClient`	Um objeto com métodos para interagir com o Storage.

Uso

`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',
  edge_access: 'public',
});
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.
`edge_access`	`string`	A configuração de `edge access` do bucket.
`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.
`debug?`	`boolean`	Habilita o modo de debug para logs detalhados.

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
`options?`	`AzionBucketCollectionOptions`	Parâmetros opcionais para filtragem e paginação.
`page?`	`number`	O número da página para paginação.
`page_size?`	`number`	O número de itens por página.
`debug?`	`boolean`	Ativa o modo de debug para logs detalhados.

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.
`debug?`	`boolean`	Ativa o modo de debug para logs detalhados.

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',
  edge_access: 'private',
});
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.
`edge_access`	`string`	A nova configuração de `edge access` para o bucket.
`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({
  bucketName: 'my-bucket',
  key: 'new-file.txt',
  file: '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
`bucketName`	`string`	O nome do bucket onde o objeto será criado.
`objectKey`	`string`	A chave (nome) do objeto a ser criado.
`file`	`string`	O conteúdo do arquivo a ser enviado.
`debug?`	`boolean`	Ativa o modo de debug para logs detalhados.

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({
  bucketName: '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
`bucketName`	`string`	O nome do bucket contendo o objeto.
`objectKey`	`string`	A chave do objeto a ser recuperado.
`debug?`	`boolean`	Ativa o modo de debug para logs detalhados.

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({
  bucketName: '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
`bucketName`	`string`	O nome do bucket a partir do qual os objetos devem ser recuperados.
`debug?`	`boolean`	Ativa o modo de debug para logs detalhados.

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({
  bucketName: 'my-bucket',
  key: 'file.txt',
  file: '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
`bucketName`	`string`	O nome do bucket que contém o objeto.
`objectKey`	`string`	O nome do objeto a ser atualizado.
`arquivo`	`string`	O novo conteúdo do arquivo.
`debug?`	`boolean`	Ativa o modo de debug para logs detalhados.

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({
  bucketName: '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
`bucketName`	`string`	O nome do bucket que contém o objeto.
`objectKey`	`string`	O nome do objeto a ser excluído.
`debug?`	`boolean`	Ativa o modo de debug para logs detalhados.

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:

`ClientConfig`

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

Parâmetro	Tipo	Descrição
`token?`	`string`	Seu token de API da Azion.
`debug?`	`boolean`	Ativa o modo de debug para logs detalhados.

`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, edge_access: string`	`Promise<AzionStorageResponse<AzionBucket>>`
`updateBucket`	`name: string, edge_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.
`edge_access`	`string` (opcional)	A configuração `edge access` do bucket.
`state`	`'executed' \| 'pending'` (opcional)	O estado do bucket.
`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.