Object Storage API

Referência da Object Storage API: o módulo azion:storage que uma function usa para gravar, ler, excluir e listar os objetos de um bucket.

Última atualização

Ver como Markdown Configurar agente

A Object Storage API do Azion Runtime dá a uma function de Functions acesso de leitura e escrita aos objetos de um bucket do Object Storage. A function importa a classe Storage do módulo azion:storage, informa um bucket e chama put, get, delete e list nele. Nenhum token é usado: o construtor recebe o nome do bucket e nada mais.

nota — Com azion dev, o módulo guarda os objetos no disco local e se comporta de outra forma: put sem um objeto options falha com TypeError: Cannot read properties of undefined (reading 'content-length'), um número em metadata é aceito, uma key ausente lança ENOENT em vez de StorageError: Object not found, e list retorna as keys sem a barra inicial e sem content_length. Teste as chamadas de storage em uma function após o deploy.

Construtor

Importe a classe Storage e crie uma instância por bucket:

JavaScript
01import Storage from "azion:storage";
02
03const storage = new Storage("my-bucket");
ParâmetroTipoDescrição
bucketstringNome do bucket. Obrigatório: sem ele, o construtor lança StorageError: bucketName must be a string.

O construtor retorna um objeto Storage cujos métodos leem e gravam nesse bucket. Ele não verifica se o bucket existe: um nome desconhecido falha na primeira chamada de método com um erro Bucket not found.

O bucket é criado quando você faz o deploy de uma aplicação estática com a Azion CLI, ou pela Azion API. A CLI também cria e gerencia buckets diretamente; para mais informações, consulte Azion CLI storage. A configuração workloads_access do bucket define o que a plataforma pode fazer com os objetos dele; para mais informações, consulte Buckets e objetos.

Métodos

Todo método de Storage é assíncrono e retorna uma promise. Chame-o com await, ou passe a promise para event.waitUntil.

put

put guarda um objeto no bucket sob uma key:

await storage.put(key, value, options);
ParâmetroTipoObrigatórioDescrição
keystringSimIdentificador do objeto no bucket.
valueArrayBuffer ou ReadableStreamSimConteúdo do objeto. Os exemplos passam o Uint8Array que TextEncoder retorna. Uma string lança TypeError: value must be an ArrayBuffer or a ReadableStream. Com um ReadableStream, as APIs de Stream se aplicam e content-length é obrigatório.
optionsobjectCom um ReadableStreamAtributos do objeto, descritos na próxima tabela.

O objeto options recebe estes atributos:

AtributoTipoPadrãoDescrição
content-typestringapplication/octet-streamTipo de mídia do objeto, como o cabeçalho HTTP content-type. Descreve como o conteúdo é tratado. Opcional.
content-lengthstring—Tamanho do objeto, em bytes. Obrigatório quando value é um ReadableStream; sem ele, put lança TypeError: Cannot read properties of undefined (reading 'content-length').
metadataobject—Um objeto JavaScript guardado com o objeto. Todo valor de propriedade precisa ser uma string: um número lança TypeError: serde_v8 error: invalid type; expected: string, got: Number.

put resolve com undefined. Ele lança um StorageError quando o bucket não existe.

get

get recupera o objeto guardado sob uma key:

const storageObject = await storage.get(key);
ParâmetroTipoObrigatórioDescrição
keystringSimIdentificador do objeto no bucket.

get resolve com um StorageObject. Ele lança StorageError: Object not found quando a key não guarda nenhum objeto, e um StorageError quando o bucket não existe.

delete

delete remove o objeto guardado sob uma key:

await storage.delete(key);
ParâmetroTipoObrigatórioDescrição
keystringSimIdentificador do objeto no bucket.

delete resolve com undefined, também quando a key não guarda nenhum objeto. Ele lança um StorageError quando o bucket não existe.

list

list retorna os objetos do bucket:

const objectsList = await storage.list();

list não recebe parâmetros. Ele resolve com um StorageObjectList e lança um StorageError quando o bucket não existe.

StorageObject

get resolve com um StorageObject, que carrega o conteúdo do objeto e os atributos dele:

MembroTipoDescrição
contentReadableStreamSomente leitura. O conteúdo do objeto, como um stream.
arrayBuffer()função assíncronaRetorna um ArrayBuffer com o conteúdo do objeto. Consome o stream content.
metadataMapSomente leitura. Os metadados guardados com o objeto. Leia um valor com metadata.get("info").
contentTypestringSomente leitura. O content-type do objeto.
contentLengthnumberSomente leitura. Tamanho do conteúdo, em bytes.

StorageObjectList

list resolve com um StorageObjectList. O array entries dele contém um item por objeto, e cada item carrega duas propriedades:

PropriedadeTipoDescrição
keystringKey do objeto, com uma barra inicial: um objeto guardado como test2 é listado como /test2.
content_lengthnumberTamanho do objeto, em bytes.

Exemplos

Cada exemplo é uma function completa que usa o bucket my-bucket. Substitua o nome por um dos seus buckets.

Persista o corpo da requisição

Esta function transmite o corpo da requisição para o objeto test:

JavaScript
01import Storage from "azion:storage";
02
03async function handleRequest(event) {
04 try{
05 const bucket = "my-bucket";
06 const storage = new Storage(bucket);
07 const key = "test";
08 const inputStream = event.request.body;
09 let contentLength = event.request.headers.get("content-length");
10 await storage.put(key, inputStream, { "content-length": contentLength });
11 return new Response("OK");
12 }catch(error){
13 return new Response(error, {status:500});
14 }
15}
16
17addEventListener("fetch", (event) => {
18 event.respondWith(handleRequest(event));
19});

Para uma requisição POST com um corpo de texto, a function guarda o corpo e responde OK.

Persista um objeto JSON

Esta function codifica um objeto JSON e o guarda como o objeto test:

JavaScript
01import Storage from "azion:storage";
02
03async function handleRequest(event) {
04 try{
05 const bucket = "my-bucket";
06 const storage = new Storage(bucket);
07 const key = "test";
08 const data = JSON.stringify({
09 name:"John",
10 address:"Abbey Road"
11 });
12 const buffer = new TextEncoder().encode(data);
13 await storage.put(key, buffer);
14 return new Response("OK");
15 }catch(error){
16 return new Response(error, {status:500});
17 }
18}
19
20addEventListener("fetch", (event) => {
21 event.respondWith(handleRequest(event));
22});

A function responde OK depois que o objeto é guardado.

Guarde um objeto JSON com metadados

Esta function guarda um objeto JSON como test2, com o content type application/json e dois valores de metadados:

JavaScript
01import Storage from "azion:storage";
02
03async function handleRequest(event) {
04 try{
05 const bucket = "my-bucket";
06 const storage = new Storage(bucket);
07 const key = "test2";
08 const data = JSON.stringify({
09 name:"Paul",
10 address:"Abbey Road"
11 });
12 const buffer = new TextEncoder().encode(data);
13 const options = { "content-type": "application/json",
14 "metadata": {
15 info:"test info",
16 counter: "1",
17 }}
18 await storage.put(key, buffer, options);
19 return new Response("OK");
20 }catch(error){
21 return new Response(error, {status:500});
22 }
23}
24
25addEventListener("fetch", (event) => {
26 event.respondWith(handleRequest(event));
27});

A function responde OK depois que o objeto é guardado.

Retorne o conteúdo de um objeto

Esta function recupera o objeto test e retorna o stream de conteúdo dele como o corpo da resposta:

JavaScript
01import Storage from "azion:storage";
02
03async function handleRequest(event) {
04 try{
05 const bucket = "my-bucket";
06 const storage = new Storage(bucket);
07 const key = "test";
08 const storageObject = await storage.get(key);
09 return new Response(storageObject.content);
10 }catch(error){
11 return new Response(error, {status:500});
12 }
13}
14
15addEventListener("fetch", (event) => {
16 event.respondWith(handleRequest(event));
17});

Quando test guarda o objeto JSON do exemplo Persista um objeto JSON, a function responde com este corpo:

{"name":"John","address":"Abbey Road"}

Decodifique um objeto JSON

Esta function lê o objeto test com arrayBuffer() e o decodifica para texto:

JavaScript
01import Storage from "azion:storage";
02
03async function handleRequest(event) {
04 try{
05 const bucket = "my-bucket";
06 const storage = new Storage(bucket);
07 const key = "test";
08 const storageObject = await storage.get(key);
09 const data = new TextDecoder().decode(await storageObject.arrayBuffer());
10 return new Response(data);
11 }catch(error){
12 return new Response(error, {status:500});
13 }
14}
15
16addEventListener("fetch", (event) => {
17 event.respondWith(handleRequest(event));
18});

Quando test guarda o objeto JSON do exemplo Persista um objeto JSON, a function responde com este corpo:

{"name":"John","address":"Abbey Road"}

Leia os metadados de um objeto

Esta function recupera o objeto test2 e retorna o valor de metadados info dele:

JavaScript
01import Storage from "azion:storage";
02
03async function handleRequest(event) {
04 try{
05 const bucket = "my-bucket";
06 const storage = new Storage(bucket);
07 const key = "test2"
08 const storageObject = await storage.get(key);
09 return new Response(storageObject.metadata.get("info"));
10 }catch(error){
11 return new Response(error, {status:500});
12 }
13}
14
15addEventListener("fetch", (event) => {
16 event.respondWith(handleRequest(event));
17});

Quando test2 guarda o objeto do exemplo Guarde um objeto JSON com metadados, a function responde test info.

Exclua um objeto

Esta function remove o objeto test do bucket:

JavaScript
01import Storage from "azion:storage";
02
03async function handleRequest(event) {
04 const bucket = "my-bucket";
05 const storage = new Storage(bucket);
06 const key = "test";
07 try{
08 await storage.delete(key);
09 }catch(error){
10 return new Response(error, {status:500});
11 }
12 return new Response("Ok");
13}
14
15addEventListener("fetch", (event) => {
16 event.respondWith(handleRequest(event));
17});

A function responde Ok depois que o objeto é removido.

Liste os objetos de um bucket

Esta function lista os objetos do bucket e registra no log a key e o tamanho de cada um:

JavaScript
01import Storage from "azion:storage";
02
03async function handleRequest(event) {
04 try{
05 const bucket = "my-bucket";
06 const storage = new Storage(bucket);
07 const objectsList = await storage.list();
08 for (const entry of objectsList.entries) {
09 console.log(`key: ${entry.key} length: ${entry.content_length}`);
10 }
11 return new Response("Ok");
12 }catch(error){
13 return new Response(error, {status:500});
14 }
15}
16
17addEventListener("fetch", (event) => {
18 event.respondWith(handleRequest(event));
19});

Para um bucket que guarda quatro objetos, a function responde Ok e registra estas linhas no log:

Texto
01key: /examples/a.json length: 38
02key: /examples/b.json length: 15
03key: /examples/c.txt length: 13
04key: /test2 length: 38

Erros

Uma chamada que falha lança um erro cujo name é StorageError, ou um TypeError para um argumento que o método recusa. O runtime não tem uma classe global StorageError, então compare com error.name. Cada string abaixo é o erro como new Response(error) o retorna; <bucket-name> representa o nome que a function passou.

ErroCausaO que fazer
StorageError: bucketName must be a stringO construtor não recebeu um nome de bucket.Passe o nome do bucket para new Storage().
StorageError: storage put error: Bucket not found: <bucket-name>put informou um bucket que a conta não tem.Passe o nome de um bucket que existe.
StorageError: Bucket not found: <bucket-name>get informou um bucket que a conta não tem.Passe o nome de um bucket que existe.
StorageError: storage delete error: Bucket not found: <bucket-name>delete informou um bucket que a conta não tem.Passe o nome de um bucket que existe.
StorageError: storage list error: Bucket not found: <bucket-name>list informou um bucket que a conta não tem.Passe o nome de um bucket que existe.
StorageError: Object not foundget informou uma key que não guarda nenhum objeto.Verifique a key, ou chame list para ver as keys do bucket.
TypeError: value must be an ArrayBuffer or a ReadableStreamput recebeu outro tipo de valor, como uma string.Codifique o valor com TextEncoder, como os exemplos de JSON fazem.
TypeError: Cannot read properties of undefined (reading 'content-length')put recebeu um ReadableStream sem content-length.Passe o tamanho em bytes como content-length em options.
TypeError: serde_v8 error: invalid type; expected: string, got: NumberUm valor de metadata passado para put não é uma string.Converta todo valor de metadados para uma string.

Recursos relacionados

Object Storage

Como os buckets guardam objetos, e como uma aplicação os entrega por meio de um connector.

Buckets e objetos

Os níveis de workloads_access e as chamadas da Azion API nos mesmos buckets.

Azion CLI storage

Crie um bucket e gerencie os objetos dele pelo terminal.

Handlers

Os formatos de handler que uma function exporta, e a requisição que cada um recebe.