ballerinax/azure.storage.files Ballerina library

Checks whether a share exists in the storage account. Returns false only when Azure confirms the share is absent; an Error means the check itself failed.

Lists the shares in the storage account.

Creates a new share in the storage account.

Deletes a share from the storage account.

Restores a soft-deleted share.

Reads the account's file-service configuration (metrics and CORS rules).

Updates the account's file-service configuration. The record replaces the whole configuration.

Gets a user-delegation key for signing user-delegation SAS tokens. Requires Microsoft Entra ID credentials with the Storage File Delegator role.

Generates an account-level SAS (Shared Access Signature) token. Requires shared key credentials.

Downloads a file to a local path. An existing local file at destinationPath fails the download with a ProcessingError.

Opens a file's content as a byte stream.

Reads a file's full content as UTF-8 text.

Reads a file's full content and binds it as JSON to the target type. Binding is strict: the content must match the target type exactly.

Reads a file's full content and binds it as XML: to an xml value, or to a record projected from the document. Binding is strict.

Reads a file's full content and binds it as CSV: to string[][] rows, or to a record array whose field names are taken from the header row. Binding is strict.

Uploads a local file to the watched share.

Uploads in-memory content to the watched share. Dispatch is by the value's runtime type: byte[] is written as-is, a string as raw text, xml as its textual form, a map<json> (including compatible records) as a JSON document, and a string[][] as CSV rows.

Deletes a file from the watched share.

Renames or moves a file within the watched share. An existing destination file is overwritten only when RenameOptions.replaceIfExists is set.

Copies a file within the watched share. The copy is asynchronous; inspect the returned CopyInfo.copyStatus for its state.

Checks the state of the most recent copy operation that targeted a file.

Aborts a pending asynchronous copy operation.

Creates a directory in the watched share.

Deletes a directory from the watched share. The directory must be empty.

Lists the entries (files and subdirectories) under a directory of the watched share.

Gets the properties of the bound share.

Replaces the metadata of the bound share.

Gets the approximate amount of data stored on the bound share, in bytes.

Creates a directory in the bound share.

Deletes a directory from the bound share. The directory must be empty.

Checks whether a directory exists in the bound share. Returns false only when Azure confirms the directory is absent; an Error means the check itself failed.

Gets the properties of a directory.

Replaces the metadata of a directory.

Lists the entries (files and subdirectories) under a directory.

Renames or moves a directory within the bound share, together with its entire contents.

Creates an empty file of a fixed size.

Deletes a file from the bound share.

Checks whether a file exists in the bound share. Returns false only when Azure confirms the file is absent; an Error means the check itself failed.

Gets the properties of a file.

Replaces the metadata of a file.

Sets the content headers of a file, such as Content-Type and Cache-Control. Any header omitted from headers is cleared on the file.

Renames or moves a file within the bound share. An existing destination file is overwritten only when RenameOptions.replaceIfExists is set.

Uploads a local file to the bound share.

// ./reports/q1.pdf (local disk) --> /2026/q1/report.pdf (on the share)
check fileClient->uploadFile("./reports/q1.pdf", "/2026/q1/report.pdf");

Uploads in-memory content to the bound share. A byte[] is written as-is, a string as raw text, an xml value as its textual form, a map<json> as a JSON document, and a string[][] as CSV rows.

check fileClient->uploadContent({revenue: 1250000, growth: 0.12}, "/2026/q1/metrics.json");

Uploads a byte stream to the bound share. The total content length must be known up front.

Downloads a file to a local path. An existing local file at destinationPath fails the download.

// /2026/q1/report.pdf (on the share) --> ./reports/q1.pdf (local disk)
check fileClient->downloadFile("/2026/q1/report.pdf", "./reports/q1.pdf");

Opens a file's content as a byte stream.

stream<byte[], files:Error?> contentStream = check fileClient->getFileContent("/2026/q1/data.json");
byte[] content = [];
check contentStream.forEach(function(byte[] chunk) {
    content.push(...chunk);
});

Reads a file's full content as UTF-8 text.

Reads a file's full content and binds it as JSON to the target type. Binding is strict: the content must match the target type exactly.

Reads a file's full content and binds it as XML: to an xml value, or to a record projected from the document. Binding is strict.

Reads a file's full content and binds it as CSV: to string[][] rows, or to a record array whose field names are taken from the header row. Binding is strict.

Copies a file within the bound share. The copy is asynchronous; inspect the returned CopyInfo.copyStatus for its state.

Copies a file from an external URL into the bound share. A source outside this storage account must carry its own authorization in the URL (typically a SAS token).

Checks the state of the most recent copy operation that targeted a file.

Aborts a pending asynchronous copy operation.

Writes a range of bytes into a file at a given offset. A single range write is capped at 4 MiB by the service.

Clears a range of bytes in a file.

Lists the valid (written) byte ranges of a file.

Creates a point-in-time, read-only snapshot of the bound share.

Lists the snapshots of the bound share. Requires account-level credentials.

Deletes one snapshot of the bound share. Requires account-level credentials.

Lists how a file's byte ranges changed since a share snapshot.

Acquires a lease on the bound share, locking it against deletion by anyone not holding the lease id.

Renews a fixed-duration lease on the bound share, restarting its duration.

Releases a lease on the bound share, unlocking it immediately.

Breaks the lease on the bound share without needing its id.

Changes the id of the active lease on the bound share.

Acquires a lease on a file, locking it against writes and deletion by anyone not holding the lease id. A file lease is always infinite.

Releases a lease on a file, unlocking it immediately.

Breaks the lease on a file without needing its id. The break is immediate.

Changes the id of the active lease on a file.

Lists the open SMB handles on a file.

Force-closes open SMB handles on a file.

Lists the open SMB handles on a directory.

Force-closes open SMB handles on a directory.

Changes the bound share's quota or access tier. Requires account key credentials.

Updates a file's properties after creation. Only what is set is changed.

Updates a directory's properties after creation. Only what is set is changed.

Gets the bound share's stored access policies.

Replaces the bound share's stored access policies. Removing or editing a policy immediately affects every SAS token minted against it.

Gets a security descriptor (SDDL string) from the bound share's permission store.

Stores a security descriptor (SDDL string) in the bound share's permission store and returns its key.

Creates a hard link to an existing file (NFS shares only).

Creates a symbolic link (NFS shares only). The target need not exist.

Reads the target of a symbolic link (NFS shares only).

Generates a SAS (Shared Access Signature) token scoped to the bound share. Requires shared key credentials.

Generates a SAS (Shared Access Signature) token scoped to a single file. Requires shared key credentials.

Generates a user-delegation SAS token scoped to the bound share.

Generates a user-delegation SAS token scoped to a single file.