Storage

Funções da Azion Lib no pacote @aziontech/storage que criam, listam, leem, atualizam e excluem buckets e objetos do Object Storage.

Última atualização

Ver como Markdown Configurar agente

O pacote @aziontech/storage é a biblioteca da Azion Lib para o Object Storage. Suas funções criam, listam, leem, atualizam e excluem buckets e os objetos dentro deles pela Azion API v4. Cada função recebe um único objeto como argumento e retorna um envelope de resposta em vez de lançar uma exceção.

Instale o pacote:

npm install @aziontech/storage

Os exemplos desta página são módulos ES em TypeScript que usam await de nível superior e rodam no Node.js. Eles importam tipos com import type, o que mantém os exemplos carregáveis quando as anotações de tipo são removidas.

Autenticação

As funções leem seu personal token da variável de ambiente AZION_TOKEN. Um client criado com createClient recebe o token no campo token.

VariávelDescrição
AZION_TOKENSeu personal token da Azion.
AZION_DEBUGCom true, as funções registram no log os corpos de resposta que a API retorna.

Para saber como os pacotes da Azion Lib resolvem o token e a configuração de debug, consulte Como a Azion Lib funciona.

Envelope de resposta

Toda função retorna um objeto AzionStorageResponse, { data?, error? }. Em caso de sucesso, data contém o bucket, o objeto ou a lista. Em caso de falha, error contém { message, operation }, em que operation nomeia a chamada que falhou, como create bucket ou get object by key.

Um deleteBucket ou deleteObject bem-sucedido não retorna data: o envelope contém apenas error, com o valor undefined. Depois de uma exclusão, verifique error, não data.

createClient

Cria um client que guarda um token e as opções de requisição e expõe as funções de bucket como métodos. createClient também é o export padrão do pacote.

TypeScript
01function createClient(config?: Partial<{
02 token: string;
03 options?: AzionClientOptions;
04}>): AzionStorageClient;
ParâmetroTipoObrigatórioDescrição
tokenstringNãoSeu personal token da Azion.
optionsAzionClientOptionsNãoOpções de requisição para todas as chamadas que o client faz.

Retorna um AzionStorageClient. Seus métodos recebem o mesmo objeto que a função correspondente desta página, sem options. O client não tem métodos de objeto: leia e grave objetos com as funções de objeto ou com os métodos de bucket.

Este exemplo cria um client e, com ele, um bucket:

TypeScript
01import { createClient } from '@aziontech/storage';
02import type { AzionStorageClient } from '@aziontech/storage';
03
04const client: AzionStorageClient = createClient({ token: process.env.AZION_TOKEN, options: { debug: false } });
05
06const { data, error } = await client.createBucket({ name: 'my-client-bucket', workloads_access: 'read_only' });
07if (data) {
08 console.log(`Bucket created with name: ${data.name}`);
09} else {
10 console.error('Failed to create bucket', error);
11}

Saída:

Bucket created with name: my-client-bucket

setupStorage

Retorna um bucket pelo nome e, quando ele não existe, cria o bucket antes. A função lê o bucket e, somente quando essa leitura não encontra nada, cria um com o workloads_access que você passa.

TypeScript
01function setupStorage(params: {
02 name: string;
03 workloads_access: EdgeAccessType;
04 options?: AzionClientOptions;
05}): Promise<AzionStorageResponse<AzionBucket>>;
ParâmetroTipoObrigatórioDescrição
namestringSimO nome do bucket a retornar ou criar.
workloads_accessEdgeAccessTypeSimO nível de acesso do bucket, caso a função o crie.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como um AzionBucket, existente ou criado. O bucket traz os métodos de bucket, então você pode gravar nele em seguida.

Este exemplo obtém um bucket que existe e grava um objeto JSON nele:

TypeScript
01import { setupStorage } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucket } from '@aziontech/storage';
03
04const { data: bucket, error }: AzionStorageResponse<AzionBucket> = await setupStorage({
05 name: 'my-app-bucket',
06 workloads_access: 'read_write',
07});
08if (bucket) {
09 console.log(`Storage ready: ${bucket.name}`);
10 // Now you can safely use the bucket for operations
11 const { data: object, error: objectError } = await bucket.createObject({
12 key: 'config.json',
13 content: '{}',
14 params: { content_type: 'application/json' },
15 });
16 console.log(object ? `Object created: ${object.key}` : objectError);
17} else {
18 console.error('Failed to setup storage', error);
19}

Saída:

Texto
01Storage ready: my-app-bucket
02Object created: config.json

createBucket

Cria um bucket.

TypeScript
01function createBucket(params: {
02 name: string;
03 workloads_access: EdgeAccessType;
04 options?: AzionClientOptions;
05}): Promise<AzionStorageResponse<AzionBucket>>;
ParâmetroTipoObrigatórioDescrição
namestringSimO nome do bucket.
workloads_accessEdgeAccessTypeSimO nível de acesso do bucket.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como o AzionBucket criado. Um bucket não tem id: todas as outras funções o encontram pelo name.

TypeScript
01import { createBucket } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucket } from '@aziontech/storage';
03
04const { data, error }: AzionStorageResponse<AzionBucket> = await createBucket({
05 name: 'my-new-bucket',
06 workloads_access: 'read_only',
07});
08if (data) {
09 console.log(`Bucket created with name: ${data.name}`);
10} else {
11 console.error('Failed to create bucket', error);
12}

Saída:

Bucket created with name: my-new-bucket

getBuckets

Lista os buckets da conta, uma página por vez.

TypeScript
01function getBuckets(params: {
02 params?: AzionBucketCollectionParams;
03 options?: AzionClientOptions;
04}): Promise<AzionStorageResponse<AzionBucketCollection>>;
ParâmetroTipoObrigatórioDescrição
paramsAzionBucketCollectionParamsNãoPaginação, busca, ordenação e seleção de campos.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como um AzionBucketCollection: buckets contém a página, e count contém o número de buckets da conta, não o tamanho da página.

TypeScript
01import { getBuckets } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucketCollection } from '@aziontech/storage';
03
04const { data: buckets, error }: AzionStorageResponse<AzionBucketCollection> = await getBuckets({
05 params: { page: 1, page_size: 10 },
06});
07if (buckets) {
08 console.log(`Retrieved ${buckets.buckets.length} of ${buckets.count} buckets`);
09} else {
10 console.error('Failed to retrieve buckets', error);
11}

Saída:

Retrieved 10 of 25 buckets

getBucket

Retorna um bucket pelo nome.

TypeScript
01function getBucket(params: {
02 name: string;
03 options?: AzionClientOptions;
04}): Promise<AzionStorageResponse<AzionBucket>>;
ParâmetroTipoObrigatórioDescrição
namestringSimO nome do bucket.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como um AzionBucket, com os métodos de bucket. Um nome que não corresponde a nenhum bucket retorna error com a mensagem The specified bucket does not exist..

TypeScript
01import { getBucket } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucket } from '@aziontech/storage';
03
04const { data: bucket, error }: AzionStorageResponse<AzionBucket> = await getBucket({ name: 'my-new-bucket' });
05if (bucket) {
06 console.log(`Retrieved bucket: ${bucket.name} (${bucket.workloads_access})`);
07} else {
08 console.error('Bucket not found', error);
09}

Saída:

Retrieved bucket: my-new-bucket (read_only)

updateBucket

Altera o nível de acesso de um bucket.

TypeScript
01function updateBucket(params: {
02 name: string;
03 workloads_access: EdgeAccessType;
04 options?: AzionClientOptions;
05}): Promise<AzionStorageResponse<AzionBucket>>;
ParâmetroTipoObrigatórioDescrição
namestringSimO nome do bucket a atualizar.
workloads_accessEdgeAccessTypeSimO nível de acesso a definir no bucket.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como o AzionBucket atualizado.

TypeScript
01import { updateBucket } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucket } from '@aziontech/storage';
03
04const { data: updatedBucket, error }: AzionStorageResponse<AzionBucket> = await updateBucket({
05 name: 'my-new-bucket',
06 workloads_access: 'read_write',
07});
08if (updatedBucket) {
09 console.log(`Bucket updated: ${updatedBucket.name} (${updatedBucket.workloads_access})`);
10} else {
11 console.error('Failed to update bucket', error);
12}

Saída:

Bucket updated: my-new-bucket (read_write)

deleteBucket

Exclui um bucket pelo nome. A API exclui um bucket somente quando ele não contém objetos, e não nas 24 horas seguintes à última exclusão de objeto nele. Um bucket que nunca conteve um objeto é excluído na hora.

TypeScript
01function deleteBucket(params: {
02 name: string;
03 options?: AzionClientOptions;
04}): Promise<AzionStorageResponse<AzionDeletedBucket>>;
ParâmetroTipoObrigatórioDescrição
namestringSimO nome do bucket a excluir.
optionsAzionClientOptionsNãoOpções de requisição.

Em caso de sucesso, o envelope não contém data, por isso o exemplo verifica error. Uma exclusão recusada preenche error; as mensagens estão em Erros.

TypeScript
01import { deleteBucket } from '@aziontech/storage';
02
03const { error } = await deleteBucket({ name: 'my-new-bucket' });
04if (error) {
05 console.error('Failed to delete bucket', error);
06} else {
07 console.log('Bucket my-new-bucket deleted');
08}

Saída:

Bucket my-new-bucket deleted

createObject

Cria um objeto em um bucket.

TypeScript
01function createObject(params: {
02 bucket: string;
03 key: string;
04 content: ContentObjectStorage;
05 params?: { content_type?: string };
06 options?: AzionClientOptions;
07}): Promise<AzionStorageResponse<AzionBucketObject>>;
ParâmetroTipoObrigatórioDescrição
bucketstringSimO nome do bucket em que o objeto é criado.
keystringSimA chave (nome) do objeto.
contentContentObjectStorageSimO conteúdo do objeto: uma string, um ArrayBuffer, um ReadableStream ou um Uint8Array.
params{ content_type?: string }NãoConfigurações do objeto. content_type define o content type do objeto.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como um AzionBucketObject com key, content_type e state. O objeto criado não traz content; leia o conteúdo com getObjectByKey.

TypeScript
01import { createObject } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucketObject } from '@aziontech/storage';
03
04const { data: newObject, error }: AzionStorageResponse<AzionBucketObject> = await createObject({
05 bucket: 'my-bucket',
06 key: 'new-file.txt',
07 content: 'File content',
08 params: { content_type: 'text/plain' },
09});
10if (newObject) {
11 console.log(`Object created with key: ${newObject.key}`);
12 console.log(`Content type: ${newObject.content_type}`);
13} else {
14 console.error('Failed to create object', error);
15}

Saída:

Texto
01Object created with key: new-file.txt
02Content type: text/plain

getObjectByKey

Retorna um objeto, com seu conteúdo, pela chave.

TypeScript
01function getObjectByKey(params: {
02 bucket: string;
03 key: string;
04 options?: AzionClientOptions;
05}): Promise<AzionStorageResponse<AzionBucketObject>>;
ParâmetroTipoObrigatórioDescrição
bucketstringSimO nome do bucket que contém o objeto.
keystringSimA chave do objeto.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como um AzionBucketObject com key e content. Uma chave que não corresponde a nenhum objeto retorna error com a mensagem The specified bucket object does not exist..

TypeScript
01import { getObjectByKey } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucketObject } from '@aziontech/storage';
03
04const { data: object, error }: AzionStorageResponse<AzionBucketObject> = await getObjectByKey({
05 bucket: 'my-bucket',
06 key: 'new-file.txt',
07});
08if (object) {
09 console.log(`Retrieved object: ${object.key}`);
10 console.log(`Content: ${object.content}`);
11} else {
12 console.error('Object not found', error);
13}

Saída:

Texto
01Retrieved object: new-file.txt
02Content: File content

getObjects

Lista os objetos de um bucket.

TypeScript
01function getObjects(params: {
02 bucket: string;
03 params?: AzionObjectCollectionParams;
04 options?: AzionClientOptions;
05}): Promise<AzionStorageResponse<AzionBucketObjects>>;
ParâmetroTipoObrigatórioDescrição
bucketstringSimO nome do bucket a listar.
paramsAzionObjectCollectionParamsNãoO número máximo de objetos a retornar. Sem ele, a função solicita max_object_count=10000.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como um AzionBucketObjects: objects e count. Cada objeto listado traz key, size e last_modified. A API também retorna is_folder em cada objeto, campo que o tipo não declara.

TypeScript
01import { getObjects } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucketObjects } from '@aziontech/storage';
03
04const { data: objectResult, error }: AzionStorageResponse<AzionBucketObjects> = await getObjects({
05 bucket: 'my-bucket',
06});
07if (objectResult) {
08 console.log(`Retrieved ${objectResult.count} objects from the bucket`);
09 for (const object of objectResult.objects) console.log(object.key, object.size, object.last_modified);
10} else {
11 console.error('Failed to retrieve objects', error);
12}

Saída:

Texto
01Retrieved 1 objects from the bucket
02new-file.txt 12 2026-01-01T12:00:00.000000Z

updateObject

Substitui o conteúdo de um objeto.

TypeScript
01function updateObject(params: {
02 bucket: string;
03 key: string;
04 content: ContentObjectStorage;
05 params?: { content_type?: string };
06 options?: AzionClientOptions;
07}): Promise<AzionStorageResponse<AzionBucketObject>>;
ParâmetroTipoObrigatórioDescrição
bucketstringSimO nome do bucket que contém o objeto.
keystringSimA chave do objeto a atualizar.
contentContentObjectStorageSimO conteúdo que substitui o atual: uma string, um ArrayBuffer, um ReadableStream ou um Uint8Array.
params{ content_type?: string }NãoConfigurações do objeto. content_type define o content type do objeto.
optionsAzionClientOptionsNãoOpções de requisição.

Retorna data como o AzionBucketObject atualizado, com key e content.

TypeScript
01import { updateObject } from '@aziontech/storage';
02import type { AzionStorageResponse, AzionBucketObject } from '@aziontech/storage';
03
04const { data: updatedObject, error }: AzionStorageResponse<AzionBucketObject> = await updateObject({
05 bucket: 'my-bucket',
06 key: 'new-file.txt',
07 content: 'Updated content',
08});
09if (updatedObject) {
10 console.log(`Object updated: ${updatedObject.key}`);
11 console.log(`New content: ${updatedObject.content}`);
12} else {
13 console.error('Failed to update object', error);
14}

Saída:

Texto
01Object updated: new-file.txt
02New content: Updated content

deleteObject

Exclui um objeto de um bucket.

TypeScript
01function deleteObject(params: {
02 bucket: string;
03 key: string;
04 options?: AzionClientOptions;
05}): Promise<AzionStorageResponse<AzionDeletedBucketObject>>;
ParâmetroTipoObrigatórioDescrição
bucketstringSimO nome do bucket que contém o objeto.
keystringSimA chave do objeto a excluir.
optionsAzionClientOptionsNãoOpções de requisição.

Em caso de sucesso, o envelope não contém data, por isso o exemplo verifica error. Uma chave que não corresponde a nenhum objeto preenche error com The specified bucket object does not exist.. Excluir um objeto também bloqueia o deleteBucket nesse bucket por 24 horas.

TypeScript
01import { deleteObject } from '@aziontech/storage';
02
03const { error } = await deleteObject({
04 bucket: 'my-bucket',
05 key: 'new-file.txt',
06});
07if (error) {
08 console.error('Failed to delete object', error);
09} else {
10 console.log('Object new-file.txt deleted');
11}

Saída:

Object new-file.txt deleted

Métodos de bucket

Um bucket que getBucket, setupStorage ou createBucket retorna traz cinco métodos que agem sobre esse bucket. Cada um recebe um único objeto e retorna o mesmo envelope que a função correspondente:

MétodoArgumentoRetorna data como
getObjects{ params: AzionObjectCollectionParams } (params é obrigatório)AzionBucketObjects
getObjectByKey{ key: string }AzionBucketObject
createObject{ key: string; content: ContentObjectStorage; params?: { content_type?: string } }AzionBucketObject
updateObject{ key: string; content: ContentObjectStorage; params?: { content_type?: string } }AzionBucketObject
deleteObject{ key: string }nada em caso de sucesso; verifique error

Este exemplo lê um bucket e, em seguida, lista, lê, atualiza e exclui um objeto pelos métodos dele:

TypeScript
01import { getBucket } from '@aziontech/storage';
02
03const { data: bucket, error } = await getBucket({ name: 'my-app-bucket' });
04if (!bucket) throw new Error(error?.message);
05
06const { data: list } = await bucket.getObjects({ params: { max_object_count: 10 } });
07console.log('getObjects:', list?.objects.map((o) => o.key));
08
09const { data: object } = await bucket.getObjectByKey({ key: 'config.json' });
10console.log('getObjectByKey:', object?.key, object?.content);
11
12const { data: updated } = await bucket.updateObject({
13 key: 'config.json',
14 content: '{"theme":"dark"}',
15 params: { content_type: 'application/json' },
16});
17console.log('updateObject:', updated?.key, updated?.content);
18
19const { error: deleteError } = await bucket.deleteObject({ key: 'config.json' });
20console.log('deleteObject:', deleteError ? deleteError : 'deleted');

Saída:

Texto
01getObjects: [ 'config.json' ]
02getObjectByKey: config.json {}
03updateObject: config.json {"theme":"dark"}
04deleteObject: deleted

Erros

Uma chamada que falha retorna estas mensagens em error.message. error.operation nomeia a chamada, como get all buckets ou delete bucket.

MensagemCausaO que fazer
Authentication credentials were not provided.Nenhum token chegou à chamada: AZION_TOKEN não está definida e nenhum token foi passado ao client.Defina AZION_TOKEN ou passe token para createClient.
Invalid authentication credentials.O token não é válido.Use um personal token válido.
This field is required.A requisição de criação não tem workloads_access.Passe name e workloads_access.
The specified bucket does not exist.Nenhum bucket da conta tem esse nome.Confira o nome com getBuckets.
The specified bucket object does not exist.O bucket não contém nenhum objeto com essa chave.Confira a chave com getObjects.
Unable to delete a non-empty bucket. Additionally, objects deleted within the last 24 hours are also taken into consideration.O bucket contém objetos, ou um objeto foi excluído dele nas últimas 24 horas.Exclua todos os objetos e aguarde 24 horas após a última exclusão. Para mais informações, consulte Buckets e objetos.

Tipos

O pacote exporta estes tipos. Importe-os com import type.

AzionStorageClient

O client que createClient retorna. Todo método recebe um único objeto.

MétodoArgumentoRetorno
getBuckets{ params?: AzionBucketCollectionParams } (opcional)Promise<AzionStorageResponse<AzionBucketCollection>>
getBucket{ name: string }Promise<AzionStorageResponse<AzionBucket>>
createBucket{ name: string; workloads_access: EdgeAccessType }Promise<AzionStorageResponse<AzionBucket>>
updateBucket{ name: string; workloads_access: EdgeAccessType }Promise<AzionStorageResponse<AzionBucket>>
deleteBucket{ name: string }Promise<AzionStorageResponse<AzionDeletedBucket>>
setupStorage{ name: string; workloads_access: EdgeAccessType }Promise<AzionStorageResponse<AzionBucket>>

AzionClientOptions

Opções de requisição que toda função recebe em options e que createClient recebe para todas as suas chamadas.

PropriedadeTipoObrigatórioDescrição
debugbooleanNãoRegistra no log os corpos de resposta que a API retorna.
forcebooleanNãoForça a operação, mesmo quando ela pode destruir dados.
envAzionEnvironmentNãoO ambiente para onde vão as chamadas.
externalbooleanNãoForça o uso da API REST em vez da API integrada ao runtime.

AzionEnvironment

O ambiente que um client chama.

type AzionEnvironment = 'development' | 'staging' | 'production';

AzionStorageResponse

O envelope que toda função retorna. Para saber como lê-lo, consulte Envelope de resposta.

PropriedadeTipoObrigatórioDescrição
dataTNãoO resultado da chamada. Ausente depois de uma exclusão bem-sucedida.
error{ message: string; operation: string }NãoA mensagem de erro e a operação que falhou.

AzionBucket

Um bucket.

PropriedadeTipoObrigatórioDescrição
namestringSimO nome do bucket.
workloads_accessEdgeAccessTypeSimO nível de acesso do bucket.
state'executed' | 'executed-runtime' | 'pending'NãoO estado do bucket.
last_editorstringNãoO usuário que editou o bucket por último.
last_modifiedstringNãoQuando o bucket foi modificado pela última vez.
product_versionstringNãoA versão do produto.
getObjects, getObjectByKey, createObject, updateObject, deleteObjectfunçõesSimOs métodos de bucket.

AzionBucketCollection

Uma página de buckets.

PropriedadeTipoObrigatórioDescrição
bucketsAzionBucket[]SimOs buckets da página.
countnumberSimO número de buckets da conta.

AzionBucketCollectionParams

Paginação e filtragem para getBuckets.

PropriedadeTipoObrigatórioDescrição
pagenumberNãoO número da página.
page_sizenumberNãoO número de buckets por página.
searchstringNãoCorresponde a parte do nome de um bucket.
orderingstringNãoO campo que ordena os resultados.
fieldsstringNãoOs campos a retornar, separados por vírgula.

AzionBucketObject

Um objeto em um bucket.

PropriedadeTipoObrigatórioDescrição
keystringSimA chave do objeto.
state'executed' | 'executed-runtime' | 'pending'NãoO estado do objeto.
sizenumberNãoO tamanho do objeto, em bytes.
last_modifiedstringNãoQuando o objeto foi modificado pela última vez.
content_typestringNãoO content type do objeto.
contentContentObjectStorageNãoO conteúdo do objeto.

AzionBucketObjects

Uma lista de objetos.

PropriedadeTipoObrigatórioDescrição
objectsAzionBucketObject[]SimOs objetos do bucket.
countnumberSimO número de objetos da lista.

AzionObjectCollectionParams

O limite para getObjects.

PropriedadeTipoObrigatórioDescrição
max_object_countnumberNãoO número máximo de objetos por requisição.

AzionDeletedBucket

O tipo que deleteBucket declara para data. Uma exclusão bem-sucedida não retorna data.

PropriedadeTipoObrigatórioDescrição
namestringSimO nome do bucket.
state'executed' | 'executed-runtime' | 'pending'NãoO estado do bucket.

AzionDeletedBucketObject

O tipo que deleteObject declara para data. Uma exclusão bem-sucedida não retorna data.

PropriedadeTipoObrigatórioDescrição
keystringSimA chave do objeto excluído.
state'executed' | 'executed-runtime' | 'pending'NãoO estado da exclusão.

ContentObjectStorage

O conteúdo que um objeto aceita.

type ContentObjectStorage = ArrayBuffer | ReadableStream | Uint8Array | string;

EdgeAccessType

O nível de acesso de um bucket: o que a plataforma da Azion pode fazer com ele quando uma aplicação o serve. Para saber o que cada valor permite, consulte Níveis de acesso.

type EdgeAccessType = 'read_only' | 'read_write' | 'restricted';

Recursos relacionados

Azion Lib

As bibliotecas que a Azion Lib oferece e o pacote que contém cada uma.

Client

Um único client para Storage, SQL, Purge, Domains, Applications e AI.

Object Storage

O que um bucket armazena e como uma aplicação o serve.

Buckets e objetos

Nomes de bucket, chaves de objeto, níveis de acesso e as chamadas de API que essas funções fazem.