Object Storage API

The Azion Runtime Object Storage API gives a function from Functions read and write access to the objects of an Object Storage bucket. The function imports the Storage class from the azion:storage module, names a bucket, and calls put, get, delete, and list on it. No token is involved: the constructor takes the bucket name and nothing else.

Under azion dev, the module stores objects on the local disk and behaves differently: put without an options object fails with TypeError: Cannot read properties of undefined (reading 'content-length'), a number in metadata is accepted, a missing key throws ENOENT instead of StorageError: Object not found, and list returns keys without the leading slash and without content_length. Test storage calls on a deployed function.

Constructor

Import the Storage class and create one instance per bucket:

JavaScript

01import Storage from "azion:storage";

03const storage = new Storage("my-bucket");

Parameter	Type	Description
`bucket`	string	Name of the bucket. Required: without it, the constructor throws `StorageError: bucketName must be a string`.

The constructor returns a Storage object whose methods read and write that bucket. It does not check that the bucket exists: an unknown name fails on the first method call with a Bucket not found error.

The bucket is created when you deploy a static application with the Azion CLI, or through the Azion API. The CLI also creates and manages buckets directly; for more information, refer to Azion CLI storage. The bucket’s workloads_access setting decides what the platform may do with its objects; for more information, refer to Buckets and objects.

Methods

Every Storage method is asynchronous and returns a promise. Call it with await, or pass the promise to event.waitUntil.

put

put stores an object in the bucket under a key:

await storage.put(key, value, options);

Parameter	Type	Required	Description
`key`	string	Yes	Identifier of the object in the bucket.
`value`	`ArrayBuffer` or ReadableStream	Yes	Content of the object. The examples pass the `Uint8Array` that `TextEncoder` returns. A string throws `TypeError: value must be an ArrayBuffer or a ReadableStream`. With a `ReadableStream`, the Stream APIs apply and `content-length` is required.
`options`	object	With a `ReadableStream`	Attributes of the object, described in the next table.

The options object takes these attributes:

Attribute	Type	Default	Description
`content-type`	string	`application/octet-stream`	Media type of the object, like the HTTP `content-type` header. It describes how the content is treated. Optional.
`content-length`	string	—	Size of the object, in bytes. Required when `value` is a `ReadableStream`; without it, `put` throws `TypeError: Cannot read properties of undefined (reading 'content-length')`.
`metadata`	object	—	A JavaScript object stored with the object. Every property value must be a string: a number throws `TypeError: serde_v8 error: invalid type; expected: string, got: Number`.

put resolves with undefined. It throws a StorageError when the bucket does not exist.

get

get retrieves the object stored under a key:

const storageObject = await storage.get(key);

Parameter	Type	Required	Description
`key`	string	Yes	Identifier of the object in the bucket.

get resolves with a StorageObject. It throws StorageError: Object not found when the key holds no object, and a StorageError when the bucket does not exist.

delete

delete removes the object stored under a key:

await storage.delete(key);

Parameter	Type	Required	Description
`key`	string	Yes	Identifier of the object in the bucket.

delete resolves with undefined, also when the key holds no object. It throws a StorageError when the bucket does not exist.

list

list returns the objects of the bucket:

const objectsList = await storage.list();

list takes no parameters. It resolves with a StorageObjectList, and throws a StorageError when the bucket does not exist.

StorageObject

get resolves with a StorageObject, which carries the content of the object and its attributes:

Member	Type	Description
`content`	`ReadableStream`	Read-only. The content of the object, as a stream.
`arrayBuffer()`	async function	Returns an `ArrayBuffer` with the content of the object. It consumes the `content` stream.
`metadata`	Map	Read-only. The metadata stored with the object. Read one value with `metadata.get("info")`.
`contentType`	string	Read-only. The `content-type` of the object.
`contentLength`	number	Read-only. Size of the content, in bytes.

StorageObjectList

list resolves with a StorageObjectList. Its entries array holds one item per object, and each item carries two properties:

Property	Type	Description
`key`	string	Key of the object, with a leading slash: an object stored as `test2` is listed as `/test2`.
`content_length`	number	Size of the object, in bytes.

Examples

Each example is a complete function that uses the bucket my-bucket. Replace the name with one of your buckets.

Persist the request body

This function streams the body of the request into the object test:

JavaScript

01import Storage from "azion:storage";

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}

17addEventListener("fetch", (event) => {

18 event.respondWith(handleRequest(event));

19});

For a POST request with a text body, the function stores the body and responds OK.

Persist a JSON object

This function encodes a JSON object and stores it as the object test:

JavaScript

01import Storage from "azion:storage";

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}

20addEventListener("fetch", (event) => {

21 event.respondWith(handleRequest(event));

22});

The function responds OK once the object is stored.

Store a JSON object with metadata

This function stores a JSON object as test2, with the application/json content type and two metadata values:

JavaScript

01import Storage from "azion:storage";

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}

25addEventListener("fetch", (event) => {

26 event.respondWith(handleRequest(event));

27});

The function responds OK once the object is stored.

Return the content of an object

This function retrieves the object test and returns its content stream as the response body:

JavaScript

01import Storage from "azion:storage";

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}

15addEventListener("fetch", (event) => {

16 event.respondWith(handleRequest(event));

17});

When test holds the JSON object from the Persist a JSON object example, the function responds with this body:

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

Decode a JSON object

This function reads the object test with arrayBuffer() and decodes it to text:

JavaScript

01import Storage from "azion:storage";

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}

16addEventListener("fetch", (event) => {

17 event.respondWith(handleRequest(event));

18});

When test holds the JSON object from the Persist a JSON object example, the function responds with this body:

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

Read the metadata of an object

This function retrieves the object test2 and returns its info metadata value:

JavaScript

01import Storage from "azion:storage";

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}

15addEventListener("fetch", (event) => {

16 event.respondWith(handleRequest(event));

17});

When test2 holds the object from the Store a JSON object with metadata example, the function responds test info.

Delete an object

This function removes the object test from the bucket:

JavaScript

01import Storage from "azion:storage";

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}

15addEventListener("fetch", (event) => {

16 event.respondWith(handleRequest(event));

17});

The function responds Ok once the object is removed.

List the objects of a bucket

This function lists the objects of the bucket and logs the key and size of each one:

JavaScript

01import Storage from "azion:storage";

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}

17addEventListener("fetch", (event) => {

18 event.respondWith(handleRequest(event));

19});

For a bucket that holds four objects, the function responds Ok and logs these lines:

Text

01key: /examples/a.json length: 38

02key: /examples/b.json length: 15

03key: /examples/c.txt length: 13

04key: /test2 length: 38

Errors

A failed call throws an error whose name is StorageError, or a TypeError for an argument the method refuses. The runtime has no global StorageError class, so match on error.name. Each string below is the error as new Response(error) returns it; <bucket-name> stands for the name the function passed.

Error	Cause	Fix
`StorageError: bucketName must be a string`	The constructor received no bucket name.	Pass the bucket name to `new Storage()`.
`StorageError: storage put error: Bucket not found: <bucket-name>`	`put` named a bucket the account does not have.	Pass the name of an existing bucket.
`StorageError: Bucket not found: <bucket-name>`	`get` named a bucket the account does not have.	Pass the name of an existing bucket.
`StorageError: storage delete error: Bucket not found: <bucket-name>`	`delete` named a bucket the account does not have.	Pass the name of an existing bucket.
`StorageError: storage list error: Bucket not found: <bucket-name>`	`list` named a bucket the account does not have.	Pass the name of an existing bucket.
`StorageError: Object not found`	`get` named a key that holds no object.	Check the key, or call `list` to see the keys of the bucket.
`TypeError: value must be an ArrayBuffer or a ReadableStream`	`put` received another type of value, such as a string.	Encode the value with `TextEncoder`, as the JSON examples do.
`TypeError: Cannot read properties of undefined (reading 'content-length')`	`put` received a `ReadableStream` without `content-length`.	Pass the size in bytes as `content-length` in `options`.
`TypeError: serde_v8 error: invalid type; expected: string, got: Number`	A `metadata` value passed to `put` is not a string.	Convert every metadata value to a string.

Object Storage

How buckets hold objects, and how an application serves them through a connector.

Buckets and objects

The workloads_access levels and the Azion API calls on the same buckets.

Azion CLI storage

Create a bucket and manage its objects from the terminal.

Handlers

The handler shapes a function exports, and the request each one receives.