# Primeiros passos com a Azion Lib

Este guia orienta você na criação do seu primeiro bucket do Object Storage com a [Azion Lib](/pt-br/documentacao/devtools/azion-lib/).

- Instale o pacote `@aziontech/storage`.
- Defina seu personal token na variável de ambiente `AZION_TOKEN`.
- Crie um bucket com um script Node.js.
- Liste os buckets da sua conta e leia o envelope de resposta.

Os scripts trabalham com dois objetos, nesta ordem:

1. O **personal token** autoriza todas as chamadas. O pacote lê o token de `AZION_TOKEN` e o envia para a Azion API v4.
2. O **bucket** é o contêiner do [Object Storage](/pt-br/documentacao/plataforma/object-storage/) que o primeiro script cria. Toda função de Storage encontra um bucket pelo nome dele.

---

## Pré-requisitos

- Uma conta Azion. Para criar uma, consulte [Criar uma conta](/pt-br/documentacao/fundamentos/criar-uma-conta/).
- Um personal token. Para criar um, consulte [Tokens pessoais](/pt-br/documentacao/fundamentos/personal-tokens/).
- Node.js e npm. Os scripts desta página são módulos ES que usam `await` de nível superior, e eles rodam com o comando `node`.

---

## Instale o pacote Storage

O pacote `@aziontech/storage` contém as funções da Azion Lib para buckets e objetos do Object Storage. Em um diretório vazio para o projeto, instale o pacote:

```bash
npm install @aziontech/storage
```

O npm instala o pacote no diretório `node_modules` do projeto, de onde os scripts o importam.

---

## Defina seu personal token

As funções de Storage leem seu personal token da variável de ambiente `AZION_TOKEN`. No terminal em que você executa os scripts, defina a variável. Substitua `[TOKEN VALUE]` pelo seu token:

```bash
export AZION_TOKEN=[TOKEN VALUE]
```

Todo script que você inicia neste terminal lê o token, até que o terminal seja fechado. Um client criado com `createClient` recebe o token no campo `token` dele, em vez da variável. Para mais informações, consulte [Storage](/pt-br/documentacao/devtools/azion-lib/storage/#createclient).

---

## Crie um bucket

A função `createBucket` cria um bucket a partir de um `name` e de um nível de acesso `workloads_access`. O nome de um bucket é único entre todas as contas Azion, então substitua `my-bucket` no script por um nome seu. Para as regras de nomenclatura e os níveis de acesso, consulte [Buckets e objetos](/pt-br/documentacao/plataforma/object-storage/buckets-e-objetos/).

Crie um arquivo chamado `create-bucket.mjs` com o seguinte código:

```javascript
import { createBucket } from '@aziontech/storage';

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

Execute o script:

```bash
node create-bucket.mjs
```

O script imprime o nome do bucket que ele criou:

```text
Bucket created with name: my-bucket
```

Sua conta tem um bucket chamado `my-bucket`, com o nível de acesso `read_only`.

---

## Liste os buckets e leia o envelope de resposta

Toda função de Storage retorna um envelope de resposta, `{ data, error }`, em vez de lançar um erro. Em caso de sucesso, `data` contém o resultado. Em caso de falha, `data` fica ausente e `error` contém dois campos: `message`, o motivo, e `operation`, a chamada que falhou.

A função `getBuckets` lista os buckets da sua conta, uma página por vez. Crie um arquivo chamado `list-buckets.mjs` com o seguinte código:

```javascript
import { getBuckets } from '@aziontech/storage';

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

Execute o script:

```bash
node list-buckets.mjs
```

O script imprime o tamanho da página e o número de buckets da conta. A página contém no máximo os 10 buckets que `page_size` define:

```text
Retrieved 10 of 25 buckets
```

Em `data`, `buckets` contém a página de buckets, e `count` contém o número de buckets da conta, não o tamanho da página. Se o terminal não tiver `AZION_TOKEN`, a chamada retorna `error` no lugar: `message` traz `Authentication credentials were not provided.` e `operation` traz `get all buckets`.

O `count` inclui o bucket que `create-bucket.mjs` criou. Para todas as mensagens de erro que as funções de Storage retornam, consulte [Storage](/pt-br/documentacao/devtools/azion-lib/storage/#erros).

---

## Próximos passos

- [Storage](/pt-br/documentacao/devtools/azion-lib/storage.md): Todas as funções de bucket e de objeto do @aziontech/storage, com os parâmetros e os erros delas.
- [Como a Azion Lib funciona](/pt-br/documentacao/devtools/azion-lib/como-funciona.md): Os pacotes, como cada módulo encontra seu token e a configuração de debug.
- [SQL](/pt-br/documentacao/devtools/azion-lib/sql.md): Crie bancos de dados SQL e execute queries com o pacote @aziontech/sql.
- [Object Storage](/pt-br/documentacao/plataforma/object-storage.md): O que um bucket armazena, os níveis de acesso dele e como uma aplicação o serve.