Object Storage API

The Functions Storage API is an interface that allows access to the Azion Object Storage. Through this interface, it's possible to read and write data in the storage and its buckets.

View as Markdown

The Functions Storage API is an interface that allows access to the Object Storage. Through this interface, it’s possible to read and write data in the storage and its buckets.

Class instantiation

To leverage this API, you need to import and instantiate the Storage class, passing the bucket’s name.

Syntax

Import:

import Storage from "azion:storage";

Instantiate:

const storage = new Storage(bucket);

Parameters

ParameterTypeDescription
bucketstringName of a bucket.

The bucket is created during the deploy of a static application through Azion CLI or through Azion API requests.

Return value

Storage object used to access Object Storage.

Methods

async storage.put

The Storage.put method is used to insert a new object into the storage.

This is an async method and must be used with await or event.waitUntil.

Syntax

async Storage.put(key, value, options)

Parameters

ParameterTypeDescription
keystringIdentifier that allows the search for an object in the storage
valueArrayBuffer ou ReadableStreamContent of the object being stored. In case value implements a ReadableStream, the Stream APIs can be used, and the option content-lenght is required
optionsobjectThe options attributes are described in the table below

options

To pass the options parameter, you must provide an object with the following attributes:

AttributeTypeDescription
content-typestringThe content-type of the object being created. It’s similar to the HTTP Header content-type and describes how the content of the bucket should be treated. content-type is optional. The default value is application/octet-stream
content-lengthstringThe size of the object to be created, in bytes. It’s mandatory when the value is ReadableStream
metadataobjectAny JavaScript object containing information about the object that will be stored in the Storage. All properties of the object must be strings

Return

SuccessError
No responseThrows a StorageError

Code sample

  1. To persist the request body:
import Storage from "azion:storage";
async function handleRequest(event) {
try{
const bucket = “mybucket”
const storage = new Storage(bucket);
const key = "test";
const inputStream = event.request.body;
let contentLength = event.request.headers.get("content-length");
await storage.put(key, inputStream, { "content-length": contentLength });
return new Response("OK");
}catch(error){
return new Response(error, {status:500});
}
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event));
});
  1. To persist a JSON object:
import Storage from "azion:storage";
async function handleRequest(event) {
try{
const bucket = "mybucket";
const storage = new Storage(bucket);
const key = "test";
const data = JSON.stringify({
name:"John",
address:"Abbey Road"
});
const buffer = new TextEncoder().encode(data);
await storage.put(key, buffer);
return new Response("OK");
}catch(error){
return new Response(error, {status:500});
}
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event));
});
  1. To save a JSON with metadata:
import Storage from "azion:storage";
async function handleRequest(event) {
try{
const bucket = "mybucket";
const storage = new Storage(bucket);
const key = "test2";
const data = JSON.stringify({
name:"Paul",
address:"Abbey Road"
});
const buffer = new TextEncoder().encode(data);
const options = { "content-type": "application/json",
"metadata": {
info:"test info",
counter: "1",
}}
await storage.put(key, buffer, options);
return new Response("OK");
}catch(error){
return new Response(error, {status:500});
}
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event));
});

async storage.get(key)

The storage.get(key) method is used to retrieve an object.

The method is async and must be used with await or event.waitUntil.

Syntax

async storage.get(key)

Parameters

ParameterTypeDescription
keystringIdentifier that allows the search for an object in the bucket

Return

SuccessError
Returns an object of the class StorageObjectThrows a StorageError

Code sample

  1. To retrieve and return content from the storage:
import Storage from "azion:storage";
async function handleRequest(event) {
try{
const bucket = "mybucket";
const storage = new Storage(bucket);
const key = "test";
const storageObject = await storage.get(key);
return new Response(storageObject.content);
}catch(error){
return new Response(error, {status:500});
}
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event));
});
  1. To get a JSON from the storage:
import Storage from "azion:storage";
async function handleRequest(event) {
try{
const bucket = "mybucket";
const storage = new Storage(bucket);
const key = "test";
const storageObject = await storage.get(key);
const data = new TextDecoder().decode(await storageObject.arrayBuffer());
return new Response(data);
}catch(error){
return new Response(error, {status:500});
}
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event));
});
  1. To read an object’s metadata:
import Storage from "azion:storage";
async function handleRequest(event) {
try{
const bucket = "mybucket";
const storage = new Storage(bucket);
const key = "test2"
const storageObject = await storage.get(key);
return new Response(storageObject.metadata.get("info"));
}catch(error){
return new Response(error, {status:500});
}
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event));
});

async storage.delete(key)

The Storage.delete(key) is used to remove an object from Object Storage.

This is an async method and must be used with await or event.waitUntil.

Syntax

async Storage.delete(key)

Parameters

ParameterTypeDescription
keystringIdentifier that allows the search for an object in the bucket

Return

SuccessError
No responseThrows a StorageError

Code sample

  1. To remove an object stored in Object Storage related to a specific bucket:
import Storage from "azion:storage";
async function handleRequest(event) {
const bucket = "mybucket";
const storage = new Storage(bucket);
const key = "test";
try{
await storage.delete(key);
}catch(error){
return new Response(error, {status:500});
}
return new Response("Ok");
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event));
});

async storage.list()

The Storage.list() method is used to list all objects belonging to the specific bucket.

This is an async method and must be used with await or event.waitUntil.

Syntax

await storage.list()

Return

SuccessError
Returns an object of the class StorageObjectListIt throws a StorageError

Code sample

  1. Listing objects from Azion Storage:
import Storage from "azion:storage";
async function handleRequest(event) {
try{
const bucket = "mybucket";
const storage = new Storage(bucket);
const objectsList = await storage.list();
for (const entry of objectsList.entries) {
console.log(`key: ${entry.key} length: ${entry.content_length}`);
}
return new Response("Ok");
}catch(error){
return new Response(error, {status:500});
}
}
addEventListener("fetch", (event) => {
event.respondWith(handleRequest(event));
});

StorageObject Class Methods

MethodDescription
StorageObject.contentRead-only property containing a ReadableStream for the content stored in the storage
async StorageObject.arrayBuffer()Asynchronous function that returns an ArrayBuffer with the content stored in the storage. This method consumes the ReadableStream from the content property
StorageObject.metadataRead-only property containing a Map object with the metadata of the object stored in the storage
StorageObject.contentTypeRead-only property containing the content-type of the content stored in the storage
StorageObject.contentLengthRead-only property containing the size in bytes of the content stored in the storage