Actions

The ballerinax/azure.storage.blob package connects to Microsoft Azure Blob Storage. It exposes the following clients:

Client	Purpose
`Client`	Operations within one container, bound at initialization.
`AdminClient`	Account-level container management, service configuration, and account SAS.

For event-driven integration, see the Trigger Reference.

Client

Operates on a single container, bound at initialization, and on the blobs within it. A blob is addressed by its container-relative path, such as 2026/07/invoice.pdf.

Configuration

Both clients take a ClientConfiguration. Credentials come from the Setup Guide.

Field	Type	Default	Description
`auth`	`AuthConfig`	Required	The authentication configuration: one credential-artifact record (an account key, a bare SAS token, a full SAS URL, a connection string, or a Microsoft Entra ID identity).
`retryConfig`	`RetryConfig`	`{}`	Retry behavior for service requests; the connector's defaults apply when omitted.
`transportConfig`	`TransportConfig`	`{}`	HTTP transport settings (proxy, connection pool, TLS).

AuthConfig is a union of the credential records below. Each member has a unique required field or field combination, so the right member is selected by the fields you supply. The only exception is the credential-chain record EntraIdChainConfig, whose default-chain and managed-identity forms would otherwise share the same field shape; it carries a kind discriminator field. The other Entra ID records have no kind field.

SharedKeyConfig, Shared Key authentication using one of the storage account's access keys:

Field	Type	Default	Description
`accountName`	`string`	Required	The storage account name, used to sign requests and to derive the service URL.
`accountKey`	`string`	Required	A base64-encoded access key of the storage account.
`serviceUrl`	`string`	Optional	The blob service endpoint URL, including the scheme. Omit to use the default `https://{accountName}.blob.core.windows.net`.

SasConfig, Shared Access Signature (SAS) authentication with a bare SAS token, as issued by az storage container generate-sas or the SAS-generation operations:

Field	Type	Default	Description
`accountName`	`string`	Required	The name of the storage account the token belongs to (determines the service URL).
`sasToken`	`string`	Required	A SAS token scoped to the required resources and permissions.

SasUrlConfig, SAS authentication with a full SAS URL, which carries the service URL and the SAS token in one string, as issued by the Azure portal:

Field	Type	Default	Description
`sasUrl`	`string`	Required	A full blob-service SAS URL, including the scheme and the SAS query string (e.g. `https://{account}.blob.core.windows.net/?sv=...&sig=...`).

ConnectionStringConfig, connection-string authentication. The connection string carries the account name, the credential (an account key or a SAS token), and the service endpoints:

Field	Type	Default	Description
`connectionString`	`string`	Required	An Azure Storage connection string, as issued by the Azure portal, the Azure CLI, or infrastructure tooling.

EntraIdConfig is itself a union of four records: a credential chain, or a service principal identified by its client secret, its certificate, or a federated token. The identity authorizes data operations through Azure RBAC: Storage Blob Data Reader covers reads and listings, Storage Blob Data Contributor adds writes and deletes, and Storage Blob Data Owner adds the access policy, index tag, and tag query operations. Obtaining a user delegation key additionally needs the Storage Blob Delegator role (or a blob data role assigned at storage account scope or wider).

EntraIdChainConfig, authentication through a credential chain selected by kind. The default chain tries the environment, a managed identity, and developer sign-ins (Azure CLI, IDE accounts) in turn, so one configuration works both locally and when deployed; the managed-identity chain uses the managed identity alone, for workloads running on Azure compute (VMs, App Service, AKS, Functions):

Field	Type	Default	Description
`kind`	`EntraIdKind`	Required	The credential chain to use: `DEFAULT_AZURE_CREDENTIAL` (the value `"default"`) or `MANAGED_IDENTITY` (the value `"managed-identity"`).
`accountName`	`string`	Required	The storage account name (determines the service URL unless `serviceUrl` overrides it).
`clientId`	`string`	Optional	The client ID of a user-assigned managed identity. Omit to use the system-assigned one.
`serviceUrl`	`string`	Optional	The blob service endpoint URL, including the scheme. Omit to use the default `https://{accountName}.blob.core.windows.net`.

ClientSecretConfig, authentication as a service principal with a client secret:

Field	Type	Default	Description
`accountName`	`string`	Required	The storage account name (determines the service URL unless `serviceUrl` overrides it).
`tenantId`	`string`	Required	The Entra ID tenant the service principal belongs to.
`clientId`	`string`	Required	The application (client) ID of the service principal.
`clientSecret`	`string`	Required	The client secret issued for the service principal.
`serviceUrl`	`string`	Optional	The blob service endpoint URL, including the scheme. Omit to use the default `https://{accountName}.blob.core.windows.net`.

ClientCertificateConfig, authentication as a service principal with a client certificate:

Field	Type	Default	Description
`accountName`	`string`	Required	The storage account name (determines the service URL unless `serviceUrl` overrides it).
`tenantId`	`string`	Required	The Entra ID tenant the service principal belongs to.
`clientId`	`string`	Required	The application (client) ID of the service principal.
`certificatePath`	`string`	Required	Path to the certificate file: a PEM file, or a PFX file when `certificatePassword` is set.
`certificatePassword`	`string`	Optional	The password protecting a PFX certificate. Omit for an unencrypted PEM certificate.
`serviceUrl`	`string`	Optional	The blob service endpoint URL, including the scheme. Omit to use the default `https://{accountName}.blob.core.windows.net`.

WorkloadIdentityConfig, workload-identity authentication, for Kubernetes workloads federated with Entra ID:

Field	Type	Default	Description
`accountName`	`string`	Required	The storage account name (determines the service URL unless `serviceUrl` overrides it).
`tenantId`	`string`	Required	The Entra ID tenant the workload identity belongs to.
`clientId`	`string`	Required	The application (client) ID of the federated identity.
`tokenFilePath`	`string`	Required	Path to the projected service-account token file.
`serviceUrl`	`string`	Optional	The blob service endpoint URL, including the scheme. Omit to use the default `https://{accountName}.blob.core.windows.net`.

RetryConfig, retry behavior for service requests. Omit the record to keep the connector's defaults:

Field	Type	Default	Description
`retryPolicyType`	`RetryPolicyType`	`EXPONENTIAL`	How the delay between tries grows (`EXPONENTIAL` or `FIXED_INTERVAL`).
`maxTries`	`int`	`4`	The maximum number of tries, counting the first attempt.
`tryTimeout`	`decimal`	`60`	The timeout applied to each individual try, in seconds.
`retryDelay`	`decimal`	`4`	The base delay between tries, in seconds.
`maxRetryDelay`	`decimal`	`120`	The upper bound on the delay between tries, in seconds.
`secondaryHostUrl`	`string`	Optional	A secondary endpoint to retry reads against, for geo-redundant accounts.

TransportConfig, HTTP transport settings: proxying, connection pooling, and TLS:

Field	Type	Default	Description
`proxy`	`ProxyConfig`	Optional	Route traffic through this proxy.
`connectionPool`	`ConnectionPoolConfig`	`{}`	Connection-pool tuning.
`secureSocket`	`SecureSocket`	Optional	Custom TLS settings (trust and key material, verification).

ProxyConfig, proxy settings for the connector's traffic:

Field	Type	Default	Description
`proxyType`	`ProxyType`	`HTTP`	The proxy protocol (`HTTP`, `SOCKS4`, or `SOCKS5`).
`host`	`string`	Required	The proxy host name or address.
`port`	`int`	Required	The proxy port.
`username`	`string`	Optional	The user name, when the proxy requires authentication.
`password`	`string`	Optional	The password, when the proxy requires authentication.
`nonProxyHosts`	`string[]`	Optional	Host names that bypass the proxy.

ConnectionPoolConfig, connection-pool settings for the connector's HTTP transport:

Field	Type	Default	Description
`maxConnections`	`int`	`50`	The maximum number of concurrent connections.
`idleTimeout`	`decimal`	`60`	How long an idle connection is kept before being closed, in seconds.
`connectTimeout`	`decimal`	`10`	The timeout for establishing a connection, in seconds.
`readTimeout`	`decimal`	`60`	The timeout for reading a response, in seconds.

SecureSocket, TLS configuration for the connector's HTTPS traffic:

Field	Type	Default	Description
`cert`	`CertStore\|string`	Optional	The trusted CA certificates: a PEM file path, or a truststore with its password.
`'key`	`CertKey\|CertStore`	Optional	The client identity for mutual TLS: a certificate and key pair, or a keystore with its password.
`protocolVersions`	`string[]`	Optional	The TLS protocol versions offered during the handshake (e.g. `["TLSv1.3", "TLSv1.2"]`).
`ciphers`	`string[]`	Optional	The cipher suites offered during the handshake.
`verifyHostName`	`boolean`	`true`	Whether the server's host name is verified against its certificate.
`sessionResumption`	`boolean`	Optional	Whether TLS sessions may be resumed.
`validateRevocation`	`boolean`	Optional	Whether the server certificate's revocation status is checked.
`sniHostName`	`string`	Optional	The Server Name Indication host name sent during the handshake.
`handshakeTimeout`	`decimal`	Optional	The TLS handshake timeout, in seconds.
`sessionTimeout`	`decimal`	Optional	The TLS session timeout, in seconds.

CertStore, a PKCS12 or JKS certificate store and the password that opens it:

Field	Type	Default	Description
`path`	`string`	Required	Path to the store file.
`password`	`string`	Required	The store password.

CertKey, a certificate and private key pair identifying the client for mutual TLS:

Field	Type	Default	Description
`certFile`	`string`	Required	Path to the client certificate file.
`keyFile`	`string`	Required	Path to the client private key file.
`keyPassword`	`string`	Optional	The password protecting the private key, when it is encrypted.

Initializing the client

The client binds to one container at initialization. Client.init makes no call to Azure, so binding to a nonexistent container succeeds and the first operation on it fails with a NotFoundError; check up front with AdminClient.hasContainer.

import ballerinax/azure.storage.blob;

configurable string accountName = ?;
configurable string accountKey = ?;

blob:Client blobClient = check new ("reports", auth = {accountName, accountKey});

With a Microsoft Entra ID service principal instead of an account key:

import ballerinax/azure.storage.blob;

configurable string accountName = ?;
configurable string tenantId = ?;
configurable string clientId = ?;
configurable string clientSecret = ?;

blob:Client blobClient = check new ("reports", auth = {accountName, tenantId, clientId, clientSecret});

The fields present in the auth value select the credential record, so a Config.toml entry can switch auth modes without a code change:

# The fields present select the union member:
[myapp.blobConfig]
auth = {accountName = "myacct", accountKey = "..."}               # SharedKeyConfig
# auth = {accountName = "myacct", sasToken = "sv=..."}            # SasConfig
# auth = {sasUrl = "https://myacct.blob.core.windows.net/?sv=..."}# SasUrlConfig
# auth = {connectionString = "..."}                               # ConnectionStringConfig
# auth = {kind = "default", accountName = "myacct"}               # EntraIdChainConfig (default chain)
# auth = {kind = "managed-identity", accountName = "myacct"}      # EntraIdChainConfig (managed identity)
# auth = {accountName = "myacct", tenantId = "...", clientId = "...", clientSecret = "..."}                # ClientSecretConfig
# auth = {accountName = "myacct", tenantId = "...", clientId = "...", certificatePath = "/path/cert.pem"}  # ClientCertificateConfig
# auth = {accountName = "myacct", tenantId = "...", clientId = "...", tokenFilePath = "/path/token"}       # WorkloadIdentityConfig

Operations

Container operations

Operations on the bound container itself. The service writes the anonymous access level and the stored access policies together, so each of the two setters first reads the current access control list and resends the half it does not change: each call is two requests, and two processes changing the two halves at the same time can overwrite each other (the last writer wins). The connector offers no container lease operations, but it honors a container lease held elsewhere: such a lease gates only the container's deletion, and a wrong leaseId passed to a container write fails with a PreconditionFailedError.

getContainerProperties

Reads the bound container's properties and metadata, including its anonymous access level, lease state, and the immutability and legal hold flags.

Returns: ContainerProperties|Error

Sample code:

blob:ContainerProperties properties = check blobClient->getContainerProperties();

Sample response:

{
    lastModified: [1770307200, 0.0],
    eTag: "\"0x8DDA1B2C3D4E5F6\"",
    publicAccess: "private",
    metadata: {department: "finance"},
    leaseState: "available",
    leaseStatus: "unlocked",
    leaseDuration: (),
    hasImmutabilityPolicy: false,
    hasLegalHold: false
}

setContainerMetadata

Replaces the container's complete metadata set. Any key absent from metadata is removed; read the current metadata back through getContainerProperties.

Parameters:

Name	Type	Required	Description
`metadata`	`map<string>`	Yes	The new complete metadata set; pass `{}` to clear it.
`options`	`ContainerMetadataOptions`	No	Optional options (the lease id, when the container is leased). See ContainerMetadataOptions.

Returns: Error?

Sample code:

check blobClient->setContainerMetadata({department: "finance", year: "2026"});

getContainerAccessPolicy

Reads the container's anonymous access level and its stored access policies together; a private container reads back as PRIVATE.

Returns: ContainerAccessPolicy|Error

Sample code:

blob:ContainerAccessPolicy policy = check blobClient->getContainerAccessPolicy();

Sample response:

{
    access: "private",
    identifiers: [
        {
            id: "read-only-2026",
            startTime: [1770307200, 0.0],
            expiryTime: [1801843200, 0.0],
            permissions: "rl"
        }
    ]
}

setPublicAccess

Sets the container's anonymous access level (PRIVATE, BLOB, or CONTAINER). The stored access policies are left unchanged. Anonymous access also requires the storage account to permit it.

Parameters:

Name	Type	Required	Description
`access`	`PublicAccess`	Yes	The anonymous access level to apply.
`options`	`AccessPolicyOptions`	No	Optional options (the lease id, when the container is leased). See AccessPolicyOptions.

Returns: Error?

Sample code:

check blobClient->setPublicAccess(blob:BLOB);

setContainerAccessPolicy

Replaces the container's stored access policies. The anonymous access level is left unchanged. Container SAS tokens minted against a policy (through the identifier field of the signature values) inherit its window and permissions, so removing or editing a policy immediately revokes or changes every SAS minted against it.

Parameters:

Name	Type	Required	Description
`identifiers`	`SignedIdentifier[]`	Yes	The new complete policy set, at most five (validated locally); pass `[]` to remove them all. See SignedIdentifier.
`options`	`AccessPolicyOptions`	No	Optional options (the lease id, when the container is leased). See AccessPolicyOptions.

Returns: Error?

Sample code:

check blobClient->setContainerAccessPolicy([
    {
        id: "read-only-2026",
        startTime: time:utcNow(),
        expiryTime: time:utcAddSeconds(time:utcNow(), 2592000),
        permissions: "rl"
    }
]);

Blob operations

Blob paths are slash-delimited, container-relative strings such as "2026/07/invoice.pdf"; the leading slash is optional. Blob storage has no directories: the slashes are part of the name. Properties are read whole and written through the narrower setters (setBlobMetadata, setContentHeaders, and setAccessTier); the remaining properties are maintained by the service. There is no rename operation: relocating a blob is a copy to the new name followed by a delete of the old one, and the two steps are individually observable.

listBlobs

Lists the container's blobs as one lazy stream, so memory stays bounded on large containers. In the flat mode (no delimiter) every blob of the container is returned regardless of the slashes in its name. In the hierarchical mode (a delimiter set) the listing covers one level: names extending past the next delimiter collapse into a single entry whose isPrefix flag is set, and such a prefix entry is fed back as the prefix of a further listing to descend one level.

Parameters:

Name	Type	Required	Description
`options`	`BlobListOptions`	No	Optional listing options (prefix, delimiter, inclusion toggles). See BlobListOptions.

Returns: stream<BlobEntry, Error?>|Error

Sample code:

stream<blob:BlobEntry, blob:Error?> entries = check blobClient->listBlobs({prefix: "2026/"});
check entries.forEach(function(blob:BlobEntry entry) {
    // process entry.path
});

Sample response:

{
    path: "2026/q1/report.pdf",
    isPrefix: false,
    contentLength: 524288,
    lastModified: [1770307200, 0.0],
    eTag: "\"0x8DDA1B2C3D4E5F6\"",
    blobType: "BlockBlob",
    accessTier: "Hot"
}

listBlobsPage

Lists one page of the container's blobs, with the marker to resume from. The options extend BlobListOptions with a pageSize (up to the service maximum of 5,000) and the marker to resume from. The marker is plain data, so a listing can be checkpointed and resumed across process restarts; otherwise prefer listBlobs.

Parameters:

Name	Type	Required	Description
`options`	`BlobPageOptions`	No	Optional listing options, plus the page size and marker. See BlobPageOptions.

Returns: BlobList|Error

Sample code:

blob:BlobList page = check blobClient->listBlobsPage({prefix: "2026/", pageSize: 500});

Sample response:

{
    blobs: [
        {
            path: "2026/q1/report.pdf",
            isPrefix: false,
            contentLength: 524288,
            lastModified: [1770307200, 0.0],
            eTag: "\"0x8DDA1B2C3D4E5F6\"",
            blobType: "BlockBlob",
            accessTier: "Hot"
        }
    ],
    nextMarker: "2!108!MDAwMDI1ITIwMjYvcTEvcmVwb3J0LnBkZiEwMDAwMjghOTk5OS0xMi0zMVQyMzo1OTo1OS45OTk5OTk5WiE-"
}

hasBlob

Checks whether a blob exists. It returns false only when Azure confirms the blob is absent (a confirmed 404); an Error means the check itself failed, so an auth problem is never misreported as a missing blob.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.

Returns: boolean|Error

Sample code:

boolean blobExists = check blobClient->hasBlob("2026/q1/report.pdf");

Sample response:

true

deleteBlob

Deletes a blob, or one of its snapshots. A blob that has snapshots cannot be deleted without directing what happens to them through DeleteBlobOptions.deleteSnapshots. When the account's blob soft delete retention policy is enabled, the deleted blob is retained for the configured period and undeleteBlob restores it.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`options`	`DeleteBlobOptions`	No	Optional deletion options (snapshot handling, a snapshot id, the lease id). See DeleteBlobOptions.

Returns: Error?

Sample code:

check blobClient->deleteBlob("2026/q1/report-old.pdf", {deleteSnapshots: blob:INCLUDE});

undeleteBlob

Restores a soft-deleted blob, together with any soft-deleted snapshots it had. Find restorable blobs with listBlobs({includeDeleted: true}).

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the deleted blob.

Returns: Error?

Sample code:

check blobClient->undeleteBlob("2026/q1/report-old.pdf");

getBlobProperties

Reads a blob's properties, metadata, and the state of its most recent copy operation. This is also how a pending copy is watched: the copyStatus field carries the state of the most recent copy. The access tier is reported as the wire's string, since the service's tier set is open-ended, and the type-specific fields (blobSequenceNumber for page blobs, committedBlockCount for append blobs) are present only for their type.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.

Returns: BlobProperties|Error

Sample code:

blob:BlobProperties properties = check blobClient->getBlobProperties("2026/q1/report.pdf");

Sample response:

{
    lastModified: [1770307200, 0.0],
    createdTime: [1770303600, 0.0],
    eTag: "\"0x8DDA1B2C3D4E5F6\"",
    contentLength: 524288,
    contentHeaders: {contentType: "application/pdf", cacheControl: "max-age=3600"},
    metadata: {reviewed: "true"},
    blobType: "BlockBlob",
    accessTier: "Hot",
    accessTierInferred: true,
    leaseState: "available",
    leaseStatus: "unlocked",
    leaseDuration: ()
}

setBlobMetadata

Replaces a blob's complete metadata set. Any key absent from metadata is removed; read the current metadata back through getBlobProperties.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`metadata`	`map<string>`	Yes	The new complete metadata set; pass `{}` to clear it.
`options`	`BlobMetadataOptions`	No	Optional options (the lease id, when the blob is leased). See BlobMetadataOptions.

Returns: Error?

Sample code:

check blobClient->setBlobMetadata("2026/q1/report.pdf", {reviewed: "true"});

setContentHeaders

Replaces a blob's complete content-header set, such as Content-Type and Cache-Control. The wire applies the set as a whole, so any header omitted from the record is cleared on the blob. Metadata is untouched.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`headers`	`ContentHeaders`	Yes	The new complete content-header set. See ContentHeaders.
`options`	`ContentHeaderOptions`	No	Optional options (the lease id, when the blob is leased). See ContentHeaderOptions.

Returns: Error?

Sample code:

check blobClient->setContentHeaders("2026/q1/report.pdf", {
    contentType: "application/pdf",
    cacheControl: "max-age=3600"
});

Transfer operations

uploadFromFile and download move bytes between a local file on disk and the container and do no format detection or type conversion; upload and getBlob carry Ballerina values. Transfer paths are full paths including the file name on both sides. Every upload creates a block blob. An existing block blob at the destination is replaced, and its snapshots are retained. An existing append or page blob fails with an InvalidBlobTypeError (delete it first, then upload), and an archived blob fails with an ArchivedBlobError until it is rehydrated or deleted. There is no overwrite option. Content larger than a single request threshold is transferred as parallel chunks in every direction, so memory stays bounded.

uploadFromFile

Uploads a local file as a block blob (disk to container). The source is not deleted, and no automatic content type is set for a disk upload.

Parameters:

Name	Type	Required	Description
`sourcePath`	`string`	Yes	The local file to upload, including its name.
`destinationPath`	`string`	Yes	The container-relative path to write, including the blob's name.
`options`	`UploadOptions`	No	Optional upload options (content headers, metadata, tags, tier, lease id). See UploadOptions.

Returns: Error?

Sample code:

check blobClient->uploadFromFile("./reports/q1.pdf", "2026/q1/report.pdf");

upload

Uploads in-memory or streamed content to the bound container. The serialization format resolves first: the explicit UploadContentOptions.fileFormat override wins, else the destination path's extension (.json, .xml, .csv) decides; the value is then checked against the resolved format. byte[], string, and a byte stream pass through untouched under every format, so content you already serialized is never re-encoded. Under JSON a json value or a record (which includes any map of anydata members) becomes a JSON document. Under XML an xml value is written in its textual form and a record becomes a single-element document whose root element is named root. Under CSV a record array becomes rows headed by the union of every record's field names in first-seen order (nil or absent members as empty cells), and a record stream is written row by row as it is pulled, so its header is the first record's field names. A record array is never JSON or XML, and a single record is never CSV. A byte stream is staged as blocks and committed at the end of the stream with no content length needed up front; until that commit the destination blob does not exist, so a failed stream upload leaves no partial blob. A source stream failure aborts with a client-side Error, and every failure closes the source stream. A structured value whose format resolves to neither an override nor a known extension, and any value-to-format pairing outside these rules, is refused with a client-side Error. When the connector chose the serialization (a json value, a record, a record array, a record stream, or an xml value) and you set no explicit contentType, the blob's content type is set to match: application/json, application/xml, or text/csv. Positional or headerless CSV has no union member: write the text and upload it as a string or byte[].

Parameters:

Name	Type	Required	Description
`content`	`UploadContent`	Yes	The content to upload: `byte[]\|string\|json\|xml\|record \|record []\|stream<byte[], error?>\|stream<record , error?>`. `byte[]`, `string`, and a byte stream are written as-is; `json`, `xml`, a record, a record array, and a record stream are serialized per the resolved format.
`destinationPath`	`string`	Yes	The container-relative path, including the blob name. Its extension selects the format unless `fileFormat` overrides it.
`options`	`UploadContentOptions`	No	Every UploadOptions field plus `fileFormat` (`JSON`, `XML`, or `CSV`), the serialization format override. See UploadContentOptions.

Returns: Error?

Sample code:

Metric q1 = {quarter: "q1", revenue: 1250000};
check blobClient->upload(q1, "2026/q1/metrics.json");

Metric[] quarters = [{quarter: "q1", revenue: 1250000}, {quarter: "q2", revenue: 1310000}];
check blobClient->upload(quarters, "2026/summary.dat", {fileFormat: blob:CSV});

stream<byte[], io:Error?> fileStream = check io:fileReadBlocksAsStream("./reports/q1.pdf");
check blobClient->upload(fileStream, "2026/q1/report.pdf");

download

Downloads a blob to a local file (container to disk). The download fails with a client-side Error when a local file already exists at destinationPath, so it never overwrites local data.

Parameters:

Name	Type	Required	Description
`sourcePath`	`string`	Yes	The container-relative path of the blob.
`destinationPath`	`string`	Yes	The local path to write, including the file name (must not exist).
`options`	`DownloadOptions`	No	Optional download options (a byte range, a snapshot id). See DownloadOptions.

Returns: Error?

Sample code:

check blobClient->download("2026/q1/report.pdf", "./downloads/report.pdf");

getBlob

Retrieves a blob's content in the form the target type selects. The target type is inferred from the call site, so no cast is needed: byte[] gives the raw content, materialized in one call; string decodes the content as UTF-8 text and fails with a client-side Error on content that is not valid UTF-8; json and xml parse the document (an xml subtype such as xml:Element takes only a document of that shape); record {} and record {}[] bind the content to the record shape per a resolved format, where the explicit GetBlobOptions.fileFormat override wins, else the path's extension (.json, .xml, .csv) decides; stream<byte[], error?> streams the content lazily, so memory stays bounded for any blob size; and stream<record {}, error?> binds CSV rows lazily, one record per pull, where a row that fails to bind surfaces as the error entry of that pull. A single record binds from JSON or XML (never CSV), a record array binds from a JSON array or CSV rows (never XML), and a format that resolves to neither an override nor a known extension is refused with a client-side Error. CSV binding consumes the header row for field names; for positional or headerless CSV, read the content as string or byte[] and parse it yourself. A union of these members binds through the JSON parser, and a readonly intersection such as Person & readonly binds as its underlying member. The materialized targets download the full content before binding. Binding is strict: content that does not match the target type fails with a client-side Error.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob. Its extension selects the format for record targets unless `fileFormat` overrides it.
`options`	`GetBlobOptions`	No	Optional retrieval options (a byte range, a snapshot id, the binding format). See GetBlobOptions.
`targetType`	`typedesc<RetrievableType>`	No	The expected return type, used for automatic data binding; inferred from the assignment target. Accepts `byte[]\|string\|json\|xml\|record \|record []\|stream<byte[], error?>\|stream<record , error?>`.

Returns: targetType|Error, the content in the requested form, or an Error on a failed retrieval or a data binding failure.

Sample code:

byte[] raw = check blobClient->getBlob("2026/q1/report.pdf");
Metric stored = check blobClient->getBlob("2026/q1/metrics.json");
Person[] people = check blobClient->getBlob("2026/q1/people.csv");
stream<byte[], error?> chunks = check blobClient->getBlob("2026/q1/large.bin");

Sample response:

{quarter: "q1", revenue: 1250000}

Copy operations

Copies are asynchronous: the service accepts the request and copies in the background. Inspect the returned CopyInfo.copyStatus and, if pending, observe progress through getBlobProperties, whose copyStatus carries the state of the blob's most recent copy, or cancel it with abortCopy. The destination inherits the source's metadata unless the copy sets metadata, but it carries no index tags unless the copy sets them. The service accepts a copy over a leased destination only when its lease is infinite.

copyBlob

Copies a blob within the bound container under this client's credentials. The service authorizes the copy source separately from the request, so a client authenticated with a SAS attaches that SAS to the source URL; a shared key authorizes a source in the same account on its own.

Parameters:

Name	Type	Required	Description
`sourcePath`	`string`	Yes	The container-relative path of the source blob.
`destinationPath`	`string`	Yes	The container-relative path of the destination blob.
`options`	`CopyOptions`	No	Optional copy options (destination metadata, tags, tier, lease id). See CopyOptions.

Returns: CopyInfo|Error

Sample code:

blob:CopyInfo copy = check blobClient->copyBlob("2026/q1/report.pdf", "archive/2026-q1-report.pdf");

Sample response:

{
    copyId: "1c556d19-8b45-42d1-a4b5-6a1e73923d20",
    copyStatus: "pending"
}

copyBlobFromUrl

Copies into the bound container from any Azure Storage URL the service can read: a blob in another container or account, or a file in Azure Files. A source in the same storage account is authorized by this client's own credential: a client authenticated with a SAS attaches that SAS to a same-account blob source that carries none, since the service authorizes the source separately from the request. A source elsewhere that is not publicly readable must carry its own authorization in the URL, typically a SAS token. Copying an archived blob to a destination with an online accessTier rehydrates the content while keeping the archived original.

Parameters:

Name	Type	Required	Description
`sourceUrl`	`string`	Yes	The URL of the source. A source in this storage account is authorized by the client's credential, a SAS being attached to the URL unless it already carries one; a source elsewhere carries its own authorization, typically a SAS token.
`destinationPath`	`string`	Yes	The container-relative path of the destination blob.
`options`	`CopyOptions`	No	Optional copy options (destination metadata, tags, tier, lease id). See CopyOptions.

Returns: CopyInfo|Error

Sample code:

blob:CopyInfo copy = check blobClient->copyBlobFromUrl(
    "https://otheracct.blob.core.windows.net/backups/2026/q1/report.pdf?sv=2025-05-05&sig=...",
    "2026/q1/report.pdf"
);

Sample response:

{
    copyId: "8d1f3a52-6c07-4e4b-9f21-b3a8c5d4e6f7",
    copyStatus: "pending"
}

abortCopy

Cancels a pending copy. It fails with a ConflictError when no copy is pending, or when copyId does not match the pending one.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the destination blob.
`copyId`	`string`	Yes	The identifier from the `CopyInfo` the copy returned.
`options`	`AbortCopyOptions`	No	Optional options (the lease id, when the destination is leased). See AbortCopyOptions.

Returns: Error?

Sample code:

check blobClient->abortCopy("archive/2026-q1-report.pdf", "1c556d19-8b45-42d1-a4b5-6a1e73923d20");

Access tier operations

An archived blob's content cannot be read or replaced until it is rehydrated: reads of an archived blob fail with an ArchivedBlobError, while its properties, metadata, and index tags stay readable.

setAccessTier

Moves a blob to another access tier: HOT, COOL, or COLD (the online tiers), or ARCHIVE (offline). Moving an archived blob to an online tier starts a rehydration that takes hours; the rehydratePriority option (STANDARD, up to fifteen hours, or HIGH, typically under one) applies to that move, and the pending rehydration is observable in BlobProperties.archiveStatus. A copy to a new destination with an online tier rehydrates while keeping the archived original.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`accessTier`	`AccessTier`	Yes	The tier to move the blob to.
`options`	`SetAccessTierOptions`	No	Optional options (the rehydration priority, the lease id). See SetAccessTierOptions.

Returns: Error?

Sample code:

check blobClient->setAccessTier("2026/q1/report.pdf", blob:COOL);

Blob index tag operations

Index tags differ from metadata: the service indexes them, so they answer queries without listing, and they carry their own SAS permission (tag, and filter for queries). Tags are set and read whole. A blob carries at most ten tags; a tag key is 1 to 128 characters and a value 0 to 256, both case sensitive, and both admit only letters, digits, and the characters +-.:=_/. The tag index is eventually consistent: a findBlobsByTags query may briefly lag a setTags write, while getTags always reads the blob's current tags. The service refuses index tags on an account with a hierarchical namespace, so the three operations fail there with the service's error.

setTags

Replaces a blob's complete index-tag set, at most ten tags. The tag rules are checked locally before any request. On a leased blob, a missing or mismatched lease id fails with a PreconditionFailedError, as on the other leased writes.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`tags`	`map<string>`	Yes	The new complete tag set; pass `{}` to clear it.
`options`	`TagOptions`	No	Optional options (the lease id, when the blob is leased). See TagOptions.

Returns: Error?

Sample code:

check blobClient->setTags("2026/q1/report.pdf", {status: "processed", year: "2026"});

getTags

Reads a blob's index tags; the map is empty when the blob has none.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.

Returns: map<string>|Error

Sample code:

map<string> tags = check blobClient->getTags("2026/q1/report.pdf");

Sample response:

{status: "processed", year: "2026"}

findBlobsByTags

Finds the bound container's blobs whose index tags match a query, as a lazy stream. The query is the service's filter expression: tag keys in double quotes, values in single quotes, the operators =, >, >=, <, and <=, and conditions joined by AND. Before any request the connector checks that the quotes balance, that only those operators appear, and that the quoted parts use the tag character set, and it adds the @container clause for the bound container; an expression that supplies its own @container is refused with a client-side Error.

Parameters:

Name	Type	Required	Description
`query`	`string`	Yes	The filter expression, such as `"status" = 'done' AND "priority" >= '05'`.

Returns: stream<TaggedBlobEntry, Error?>|Error

Sample code:

stream<blob:TaggedBlobEntry, blob:Error?> matches =
    check blobClient->findBlobsByTags("\"status\" = 'processed' AND \"year\" >= '2026'");
check matches.forEach(function(blob:TaggedBlobEntry entry) {
    // process entry.path
});

Sample response:

{
    path: "2026/q1/report.pdf",
    tags: {status: "processed", year: "2026"}
}

Snapshot operations

A snapshot is a point-in-time, read-only copy of a blob. Snapshot contents are read through the regular read operations by passing the snapshot id as the snapshotId of GetBlobOptions or DownloadOptions. Snapshots are listed with listBlobs({includeSnapshots: true}), where each snapshot entry carries its snapshotId, and deleted through deleteBlob (one snapshot through snapshotId, or all of a blob's snapshots through deleteSnapshots).

createSnapshot

Creates a point-in-time, read-only copy of a blob and returns the snapshot identifier. A snapshot of a leased blob succeeds without the lease id, the one blob write that does; a lease id that is given is checked, and a wrong one fails with a PreconditionFailedError.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`options`	`CreateSnapshotOptions`	No	Optional options (the snapshot's metadata, the lease id). See CreateSnapshotOptions.

Returns: string|Error

Sample code:

string snapshotId = check blobClient->createSnapshot("2026/q1/report.pdf");

Sample response:

"2026-08-06T09:15:22.0000000Z"

Lease operations

Blob leases lock a blob against writes and deletion by anyone not holding the lease id; reads stay open to all. While a blob is leased, the write operations pass the lease id through the leaseId field of their options, setAccessTier and the index tag operations included; a write without the current lease id, or with a wrong one, fails with a PreconditionFailedError. The one exception is createSnapshot, which succeeds without the lease id. Failures of the lease operations themselves, against a stale id or the wrong lease state, surface as a ConflictError, and the error code in the detail names the exact condition.

acquireLease

Acquires a lease on a blob, locking it against writes and deletion by others. The duration is validated locally, so a value outside the range fails without a round trip. It fails with a ConflictError when the blob is already leased.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`leaseDurationSeconds`	`int`	Yes	15 to 60 for a fixed lease, or -1 for an infinite one.
`proposedLeaseId`	`string`	No	A lease id to use; omit and the service generates one.

Returns: string|Error

Sample code:

string leaseId = check blobClient->acquireLease("2026/q1/report.pdf", 60);

Sample response:

"5f3a9c2e-1b4d-4e8f-9a7c-2d6b8e0f1a3c"

renewLease

Renews a fixed-duration lease, restarting its clock.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`leaseId`	`string`	Yes	The current lease id.

Returns: Error?

Sample code:

check blobClient->renewLease("2026/q1/report.pdf", "5f3a9c2e-1b4d-4e8f-9a7c-2d6b8e0f1a3c");

releaseLease

Releases a lease, making the blob immediately available to other clients.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`leaseId`	`string`	Yes	The current lease id.

Returns: Error?

Sample code:

check blobClient->releaseLease("2026/q1/report.pdf", "5f3a9c2e-1b4d-4e8f-9a7c-2d6b8e0f1a3c");

breakLease

Breaks a lease without holding its id, for when the holder is gone. With no break period a fixed lease runs out its remaining time and an infinite lease breaks immediately; an explicit period can only shorten the break, never lengthen it. A broken lease cannot be renewed, and no new lease can be acquired until the period elapses.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`breakPeriodSeconds`	`int`	No	How long the lease keeps running before it breaks, 0 to 60.

Returns: int|Error, the seconds until the lease is actually free; 0 means it is free now.

Sample code:

int secondsRemaining = check blobClient->breakLease("2026/q1/report.pdf", 0);

Sample response:

changeLease

Changes a lease's id, handing it over without a window in which another client could acquire it.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`leaseId`	`string`	Yes	The current lease id.
`proposedLeaseId`	`string`	Yes	The new lease id.

Returns: string|Error

Sample code:

string newLeaseId = check blobClient->changeLease("2026/q1/report.pdf",
    "5f3a9c2e-1b4d-4e8f-9a7c-2d6b8e0f1a3c", "9b1e4d7a-3c5f-4a2b-8d6e-0f2a4c6e8b1d");

Sample response:

"9b1e4d7a-3c5f-4a2b-8d6e-0f2a4c6e8b1d"

Append blob operations

Append blobs grow only at the end, which suits log-style accumulation. The transfer operations always create block blobs, so use these to create and extend an append blob; applying them to a blob of another type fails with an InvalidBlobTypeError. The committedBlockCount of BlobProperties reports an append blob's progress.

createAppendBlob

Creates an empty append blob. Append blobs grow only through the append operations.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob to create.
`options`	`CreateBlobOptions`	No	Optional creation options (content headers, metadata, tags, lease id). See CreateBlobOptions.

Returns: Error?

Sample code:

check blobClient->createAppendBlob("logs/2026-08.log");

appendBlock

Appends a block of content at the blob's end. Blocks append in arrival order; each block may be at most 4 MiB, and a blob holds at most 50,000 blocks.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the append blob.
`content`	`byte[]`	Yes	The content to append.
`options`	`AppendBlockOptions`	No	Optional options (the lease id, when the blob is leased). See AppendBlockOptions.

Returns: Error?

Sample code:

check blobClient->appendBlock("logs/2026-08.log", "2026-08-06T09:15:22Z order 1042 shipped\n".toBytes());

appendBlockFromUrl

Appends content the service reads from a URL, with the same source rules as copyBlobFromUrl.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the append blob.
`sourceUrl`	`string`	Yes	The URL of the source.
`options`	`AppendBlockOptions`	No	Optional options (the lease id, when the blob is leased). See AppendBlockOptions.

Returns: Error?

Sample code:

check blobClient->appendBlockFromUrl("logs/2026-08.log",
    "https://otheracct.blob.core.windows.net/logs/2026-08-06.log?sv=2025-05-05&sig=...");

Page blob operations

Page blobs are fixed-capacity, 512-byte-aligned random-access blobs. The capacity is reserved sparsely: unwritten pages read as zeros and only written pages are billed. Page writes to a blob of another type fail with an InvalidBlobTypeError, and misaligned offsets or lengths are refused with a client-side Error before any request is made. The blobSequenceNumber of BlobProperties is the page blob's write sequence marker.

createPageBlob

Creates an empty page blob of a fixed capacity.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob to create.
`sizeInBytes`	`int`	Yes	The blob's fixed capacity, a multiple of 512 up to 8 TiB.
`options`	`CreateBlobOptions`	No	Optional creation options (content headers, metadata, tags, lease id). See CreateBlobOptions.

Returns: Error?

Sample code:

check blobClient->createPageBlob("disks/data.vhd", 1048576);

uploadPages

Writes content at the given offset of a page blob. The offset must be 512-byte aligned and the content length a multiple of 512, at most 4 MiB per call.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the page blob.
`offset`	`int`	Yes	The 512-byte-aligned offset to write at.
`content`	`byte[]`	Yes	The content to write.
`options`	`PageOptions`	No	Optional options (the lease id, when the blob is leased). See PageOptions.

Returns: Error?

Sample code:

byte[] content = check io:fileReadBytes("./chunks/page-000.bin");
check blobClient->uploadPages("disks/data.vhd", 0, content);

clearPages

Resets a 512-byte-aligned range of a page blob to zeros, releasing its storage.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the page blob.
`offset`	`int`	Yes	The 512-byte-aligned offset to clear from.
`length`	`int`	Yes	The 512-byte-aligned number of bytes to clear.
`options`	`PageOptions`	No	Optional options (the lease id, when the blob is leased). See PageOptions.

Returns: Error?

Sample code:

check blobClient->clearPages("disks/data.vhd", 524288, 524288);

listPageRanges

Lists the written byte ranges of a page blob.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the page blob.
`options`	`PageRangeOptions`	No	Optional options (a byte range to restrict the listing, a snapshot id). See PageRangeOptions.

Returns: PageRange[]|Error

Sample code:

blob:PageRange[] ranges = check blobClient->listPageRanges("disks/data.vhd");

Sample response:

[{offset: 0, length: 524288}]

Block operations

The block operations expose block blob composition directly. They are not the path for ordinary large uploads, which upload and uploadFromFile chunk internally. They serve composing a blob from remote pieces without the content passing through your program, and staging content across process restarts before committing it. All block ids of one blob must be equal in length. Staged blocks expire seven days after the blob's most recent successful staging; until a commit, the visible blob (if any) is unchanged.

stageBlock

Stages a block of content under a base64 block id, without changing the visible blob. The caller supplies the id already base64 encoded; an id that is not valid base64 fails with a client-side Error before any request is made.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`blockId`	`string`	Yes	The block's base64 identifier; all ids of one blob must be equal in length.
`content`	`byte[]`	Yes	The content to stage, at most 4,000 MiB.
`options`	`StageBlockOptions`	No	Optional options (the lease id, when the blob is leased). See StageBlockOptions.

Returns: Error?

Sample code:

byte[] part = check io:fileReadBytes("./chunks/part-000.bin");
check blobClient->stageBlock("2026/combined.bin", "MDAwMDAw", part);

stageBlockFromUrl

Stages a block the service reads from a URL, so the content never passes through the caller. The source rules are those of copyBlobFromUrl.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`blockId`	`string`	Yes	The block's base64 identifier; all ids of one blob must be equal in length.
`sourceUrl`	`string`	Yes	The URL of the source.
`options`	`StageBlockFromUrlOptions`	No	Optional options (a source byte range, the lease id). See StageBlockFromUrlOptions.

Returns: Error?

Sample code:

check blobClient->stageBlockFromUrl("2026/combined.bin", "MDAwMDAx",
    "https://otheracct.blob.core.windows.net/parts/part-001.bin?sv=2025-05-05&sig=...");

commitBlockList

Commits an ordered list of staged block ids as the blob's content, creating or replacing it in one atomic step. All block ids must be equal in length; an unequal set fails with a client-side Error before the request is made.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.
`blockIds`	`string[]`	Yes	The block ids to commit, in order.
`options`	`UploadOptions`	No	Optional options (content headers, metadata, tags, tier, lease id). See UploadOptions.

Returns: Error?

Sample code:

check blobClient->commitBlockList("2026/combined.bin", ["MDAwMDAw", "MDAwMDAx"]);

listBlocks

Reports a blob's committed blocks and its staged, uncommitted blocks. This is how a restarted producer finds what it already staged.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob.

Returns: BlockList|Error

Sample code:

blob:BlockList blocks = check blobClient->listBlocks("2026/combined.bin");

Sample response:

{
    committedBlocks: [{blockId: "MDAwMDAw", sizeBytes: 4194304}],
    uncommittedBlocks: [{blockId: "MDAwMDAx", sizeBytes: 1048576}]
}

SAS generation

These are ordinary methods, not remote functions: they sign locally without a service call, so invoke them with . rather than ->. generateContainerSas and generateSas sign with the account key, so the client must hold a SharedKeyConfig (or a connection string carrying an account key); rotating the account key revokes every SAS minted from it. The user-delegation variants sign with a UserDelegationKey obtained from AdminClient.getUserDelegationKey, so no storage key is handled. Each returns the token without a leading ?, to append to a blob or container URL as the query string.

generateContainerSas

Mints a SAS (Shared Access Signature) token scoped to the whole container, signed locally with the account key; the client must hold shared key credentials. Generation fails with a client-side Error when no identifier is supplied and the expiryTime or the permissions are missing.

Parameters:

Name	Type	Required	Description
`values`	`ContainerSasSignatureValues`	Yes	The values signed into the token: validity window and permissions, or a stored policy identifier. See ContainerSasSignatureValues.

Returns: string|Error

Sample code:

string sasToken = check blobClient.generateContainerSas({
    expiryTime: time:utcAddSeconds(time:utcNow(), 3600),
    permissions: {read: true, list: true}
});

Sample response:

"sv=2025-05-05&sr=c&sp=rl&se=2026-08-06T10%3A00%3A00Z&sig=nJd7..."

generateSas

Mints a SAS (Shared Access Signature) token scoped to a single blob, signed locally with the account key; the client must hold shared key credentials. Generation fails with a client-side Error when no identifier is supplied and the expiryTime or the permissions are missing.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob the token grants access to.
`values`	`BlobSasSignatureValues`	Yes	The values signed into the token: validity window and permissions, or a stored policy identifier. See BlobSasSignatureValues.

Returns: string|Error

Sample code:

string sasToken = check blobClient.generateSas("2026/q1/report.pdf", {
    expiryTime: time:utcAddSeconds(time:utcNow(), 3600),
    permissions: {read: true}
});

Sample response:

"sv=2025-05-05&sr=b&sp=r&se=2026-08-06T10%3A00%3A00Z&sig=Xk2p..."

generateContainerUserDelegationSas

Mints a container-scoped user-delegation SAS token, signed with an Entra ID user-delegation key instead of the account key. A user-delegation SAS is valid at most 7 days (the key's lifetime), and stored access policies do not apply to it: the generator rejects an identifier and requires an explicit expiryTime and permissions.

Parameters:

Name	Type	Required	Description
`values`	`ContainerSasSignatureValues`	Yes	The values signed into the token; an explicit window and permissions are required. See ContainerSasSignatureValues.
`key`	`UserDelegationKey`	Yes	The user-delegation key from `AdminClient.getUserDelegationKey`. See UserDelegationKey.

Returns: string|Error

Sample code:

// An Entra ID-authenticated AdminClient mints the delegation key.
blob:AdminClient admin = check new (auth = {accountName, tenantId, clientId, clientSecret});
blob:UserDelegationKey key = check admin->getUserDelegationKey(
    time:utcNow(), time:utcAddSeconds(time:utcNow(), 86400));
string sasToken = check blobClient.generateContainerUserDelegationSas({
    expiryTime: time:utcAddSeconds(time:utcNow(), 3600),
    permissions: {read: true, list: true}
}, key);

Sample response:

"sv=2025-05-05&sr=c&sp=rl&se=2026-08-06T10%3A00%3A00Z&skoid=3d1e2f3a-...&sig=Qm9r..."

generateUserDelegationSas

Mints a blob-scoped user-delegation SAS token, signed with an Entra ID user-delegation key instead of the account key. A user-delegation SAS is valid at most 7 days (the key's lifetime), and stored access policies do not apply to it: the generator rejects an identifier and requires an explicit expiryTime and permissions.

Parameters:

Name	Type	Required	Description
`path`	`string`	Yes	The container-relative path of the blob the token grants access to.
`values`	`BlobSasSignatureValues`	Yes	The values signed into the token; an explicit window and permissions are required. See BlobSasSignatureValues.
`key`	`UserDelegationKey`	Yes	The user-delegation key from `AdminClient.getUserDelegationKey`. See UserDelegationKey.

Returns: string|Error

Sample code:

// An Entra ID-authenticated AdminClient mints the delegation key.
blob:AdminClient admin = check new (auth = {accountName, tenantId, clientId, clientSecret});
blob:UserDelegationKey key = check admin->getUserDelegationKey(
    time:utcNow(), time:utcAddSeconds(time:utcNow(), 86400));
string sasToken = check blobClient.generateUserDelegationSas("2026/q1/report.pdf", {
    expiryTime: time:utcAddSeconds(time:utcNow(), 3600),
    permissions: {read: true}
}, key);

Sample response:

"sv=2025-05-05&sr=b&sp=r&se=2026-08-06T10%3A00%3A00Z&skoid=3d1e2f3a-...&sig=Ttw4..."

AdminClient

Account-level administration: container lifecycle and existence checks, the account's blob service configuration, account information, the user delegation key, and account SAS.

Configuration

The AdminClient takes the same ClientConfiguration as the Client; see the Client configuration tables above.

Under Microsoft Entra ID credentials, creating and deleting containers and setting container metadata need Storage Blob Data Contributor assigned at storage account scope or wider. Reading and setting the blob service properties need the storage account's blobServices/read and blobServices/write actions, whose least privileged built-in role is Storage Account Contributor. getUserDelegationKey requires the Storage Blob Delegator role (or a blob data role assigned at storage account scope or wider). See the Setup Guide for the role split.

Initializing the client

import ballerinax/azure.storage.blob;

configurable string accountName = ?;
configurable string accountKey = ?;

blob:AdminClient admin = check new (auth = {accountName, accountKey});

Operations

Container management

hasContainer

Checks whether a container exists in the storage account. It returns false only when Azure confirms the container is absent (a confirmed 404); an Error means the check itself failed, so an auth problem is never misreported as a missing container.

Parameters:

Name	Type	Required	Description
`containerName`	`string`	Yes	The name of the container to check.

Returns: boolean|Error

Sample code:

boolean containerExists = check admin->hasContainer("reports");

Sample response:

true

listContainers

Lists the containers in the storage account. Without a 'limit every container is returned and nextMarker is absent; with one, up to that many are returned and nextMarker is present when more remain, to be passed back as the next call's marker. The marker is plain data, so a listing survives a process restart.

Parameters:

Name	Type	Required	Description
`options`	`ContainerListOptions`	No	Optional listing options (prefix, inclusion toggles, a result limit and marker). See ContainerListOptions.

Returns: ContainerList|Error

Sample code:

blob:ContainerList containers = check admin->listContainers({includeMetadata: true});

Sample response:

{
    containers: [
        {
            name: "reports",
            lastModified: [1770307200, 0.0],
            eTag: "\"0x8DDA1B2C3D4E5F6\"",
            publicAccess: "private",
            leaseState: "available",
            leaseStatus: "unlocked",
            leaseDuration: (),
            metadata: {department: "finance"}
        }
    ]
}

createContainer

Creates a new container in the storage account. It fails with a ConflictError if the container already exists.

Parameters:

Name	Type	Required	Description
`containerName`	`string`	Yes	The name of the container to create.
`options`	`ContainerCreateOptions`	No	Optional creation options (metadata, anonymous access level). See ContainerCreateOptions.

Returns: Error?

Sample code:

check admin->createContainer("reports", {metadata: {department: "finance"}});

deleteContainer

Deletes a container and every blob in it. Where the account's container soft-delete retention policy is enabled, the container is retained for the configured period and can be restored with undeleteContainer.

Parameters:

Name	Type	Required	Description
`containerName`	`string`	Yes	The name of the container to delete.
`options`	`DeleteContainerOptions`	No	Optional deletion options (the lease id, when the container is leased). See DeleteContainerOptions.

Returns: Error?

Sample code:

check admin->deleteContainer("reports-2024");

undeleteContainer

Restores a soft-deleted container. Find restorable containers with listContainers({includeDeleted: true}), where each carries the deletedVersion this operation takes.

Parameters:

Name	Type	Required	Description
`containerName`	`string`	Yes	The name of the soft-deleted container to restore.
`deletedContainerVersion`	`string`	Yes	The version of the soft-deleted container (from `ContainerInfo.deletedVersion`).

Returns: Error?

Sample code:

check admin->undeleteContainer("reports-2024", "01D9E9CE4B0316F0");

Service configuration and account information

getServiceProperties

Reads the account's blob service configuration: request-metrics collection, classic logging, CORS rules, the blob soft delete retention policy, the static website settings, and the default service version.

Returns: ServiceProperties|Error

Sample code:

blob:ServiceProperties properties = check admin->getServiceProperties();

Sample response:

{
    hourMetrics: {version: "1.0", enabled: true, includeApis: true, retentionPolicy: {enabled: true, days: 7}},
    minuteMetrics: {version: "1.0", enabled: false},
    logging: {version: "1.0", read: false, write: false, delete: false, retentionPolicy: {enabled: false}},
    cors: [],
    deleteRetentionPolicy: {enabled: true, days: 7},
    staticWebsite: {enabled: false},
    defaultServiceVersion: "2025-05-05"
}

setServiceProperties

Writes the account's blob service configuration. Each configuration group is an optional field of the record: a group present in the record replaces that group whole, and a group absent is left unchanged. An empty cors array therefore deletes every CORS rule, while omitting the cors field preserves them. To change one group, read the current configuration, modify it, and pass the result back. Enabling the blob soft delete retention policy here is the prerequisite for undeleteBlob; container soft delete is a storage account setting, enabled on the account rather than through the service properties.

Parameters:

Name	Type	Required	Description
`properties`	`ServiceProperties`	Yes	The configuration groups to apply. See ServiceProperties.

Returns: Error?

Sample code:

check admin->setServiceProperties({
    deleteRetentionPolicy: {enabled: true, days: 7}
});

getAccountInfo

Reads the storage account's SKU, kind, and whether it has a hierarchical namespace. On hierarchical namespace accounts (Azure Data Lake Storage Gen2) directories are real and renames exist through a different endpoint; the connector models neither.

Returns: AccountInfo|Error

Sample code:

blob:AccountInfo info = check admin->getAccountInfo();

Sample response:

{
    skuName: "Standard_LRS",
    accountKind: "StorageV2",
    isHierarchicalNamespaceEnabled: false
}

User delegation key and account SAS

generateAccountSas is an ordinary method that signs locally without a service call; invoke it with . rather than ->.

getUserDelegationKey

Obtains a key for signing user-delegation SAS tokens; the key is valid at most 7 days, and the tokens signed with it cannot outlive it. This operation requires a Microsoft Entra ID credential whose identity holds the generateUserDelegationKey action at storage account scope or wider, which Storage Blob Delegator or any blob data role assigned there grants; any other credential, or an identity without the action, fails with an AuthorizationError.

Parameters:

Name	Type	Required	Description
`startTime`	`time:Utc`	Yes	When the key becomes valid.
`expiryTime`	`time:Utc`	Yes	When the key expires; at most 7 days after `startTime`.

Returns: UserDelegationKey|Error

Sample code:

blob:UserDelegationKey key = check admin->getUserDelegationKey(
    time:utcNow(), time:utcAddSeconds(time:utcNow(), 86400));

Sample response:

{
    signedObjectId: "3d1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a",
    signedTenantId: "72f988bf-86f1-41af-91ab-2d7cd011db47",
    signedStart: [1770307200, 0.0],
    signedExpiry: [1770393600, 0.0],
    signedService: "b",
    signedVersion: "2025-05-05",
    value: "aGVsbG8gd29ybGQ="
}

generateAccountSas

Mints an account-level SAS (Shared Access Signature) token, signed locally with the account key; the client must hold shared key credentials (or a connection string carrying an account key), and any other credential fails with a client-side Error. The signature values select the covered services (blob, queue), the resource types, the permissions, and the validity window. An account SAS covering the blob and queue services, the container and 'object resource types, and the permissions read, add, create, update, and process is the credential a Listener needs; see the Trigger Reference. Rotating the account key revokes every SAS minted from it.

Parameters:

Name	Type	Required	Description
`values`	`AccountSasSignatureValues`	Yes	The values signed into the token (services, resource types, permissions, window). See AccountSasSignatureValues.

Returns: string|Error

Sample code:

string sasToken = check admin.generateAccountSas({
    expiryTime: time:utcAddSeconds(time:utcNow(), 3600),
    permissions: {read: true, list: true},
    services: {blob: true},
    resourceTypes: {'service: true, container: true, 'object: true}
});

Sample response:

"sv=2025-05-05&ss=b&srt=sco&sp=rl&se=2026-08-06T10%3A00%3A00Z&sig=Bv3k..."

Supporting types

The option, SAS, and result records used by the operations above, documented once.

ContentHeaders

A blob's standard content headers. Written as a whole set: a field omitted from the record is cleared on the blob.

Field	Type	Default	Description
`contentType`	`string`	Optional	The media type of the blob's content.
`contentEncoding`	`string`	Optional	The content encoding applied to the blob.
`contentLanguage`	`string`	Optional	The natural language of the blob's content.
`contentDisposition`	`string`	Optional	How a user agent should present the content.
`cacheControl`	`string`	Optional	The caching directives for the blob.
`contentMd5`	`string`	Optional	The MD5 hash of the blob's content.

ByteRange

A byte range, with inclusive start and end offsets.

Field	Type	Default	Description
`startByte`	`int`	Required	The first byte of the range.
`endByte`	`int`	Required	The last byte of the range.

LeaseOptions

The lease a write must carry. Included by every option record of a lease-guarded write.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the target is leased.

ContainerListOptions

Options for AdminClient.listContainers.

Field	Type	Default	Description
`prefix`	`string`	Optional	Return only containers whose name begins with this prefix.
`includeMetadata`	`boolean`	`false`	Include each container's metadata.
`includeDeleted`	`boolean`	`false`	Include soft-deleted containers.
`'limit`	`int`	Optional	The maximum number of containers to return; omit for all.
`marker`	`string`	Optional	Resume from a previous `ContainerList.nextMarker`.

ContainerCreateOptions

Options for AdminClient.createContainer.

Field	Type	Default	Description
`metadata`	`map<string>`	Optional	The container's initial metadata.
`publicAccess`	`PublicAccess`	Optional	The anonymous access level. Omit to create a private container. Anonymous access also requires the storage account to permit it.

DeleteContainerOptions

Options for AdminClient.deleteContainer.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the container is leased.

ContainerMetadataOptions

Options for Client.setContainerMetadata.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, when the container is leased.

AccessPolicyOptions

Options for Client.setPublicAccess and Client.setContainerAccessPolicy.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, when the container is leased.

BlobListOptions

Options for Client.listBlobs.

Field	Type	Default	Description
`prefix`	`string`	Optional	Return only blobs whose name begins with this prefix.
`delimiter`	`string`	Optional	Group names that extend past this delimiter into a single prefix entry.
`includeMetadata`	`boolean`	`false`	Include each blob's metadata.
`includeTags`	`boolean`	`false`	Include each blob's index tags.
`includeSnapshots`	`boolean`	`false`	Include blob snapshots.
`includeDeleted`	`boolean`	`false`	Include soft-deleted blobs.

BlobPageOptions

Options for Client.listBlobsPage: every BlobListOptions field, plus the page size and marker.

Field	Type	Default	Description
`pageSize`	`int`	Optional	The maximum number of blobs in the page, up to the service maximum of 5,000.
`marker`	`string`	Optional	Resume from a previous `BlobList.nextMarker`.

DeleteBlobOptions

Options for Client.deleteBlob.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.
`deleteSnapshots`	`DeleteSnapshotsOption`	Optional	What happens to the blob's snapshots (`INCLUDE` or `ONLY_SNAPSHOTS`). Required when the blob has snapshots.
`snapshotId`	`string`	Optional	Deletes this snapshot instead of the blob.

BlobMetadataOptions

Options for Client.setBlobMetadata.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.

ContentHeaderOptions

Options for Client.setContentHeaders.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.

UploadOptions

Options for Client.uploadFromFile and Client.commitBlockList (upload takes UploadContentOptions).

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the destination blob is leased.
`contentHeaders`	`ContentHeaders`	Optional	The content headers stored with the new blob.
`metadata`	`map<string>`	Optional	The metadata stored with the new blob.
`tags`	`map<string>`	Optional	The index tags stored with the new blob.
`accessTier`	`AccessTier`	Optional	The access tier the new blob starts in.

UploadContentOptions

Options for Client.upload: every UploadOptions field, plus the serialization format override.

Field	Type	Default	Description
`fileFormat`	`FileFormat`	Optional	The serialization format for structured content: `JSON`, `XML`, or `CSV`. When absent, the format is inferred from the destination path's extension (`.json`, `.xml`, `.csv`).

DownloadOptions

Options for Client.download, included by getBlob's GetBlobOptions.

Field	Type	Default	Description
`range`	`ByteRange`	Optional	Reads only this byte range of the blob.
`snapshotId`	`string`	Optional	Reads this snapshot instead of the live blob.

GetBlobOptions

Options for Client.getBlob: every DownloadOptions field, plus the binding format override.

Field	Type	Default	Description
`fileFormat`	`FileFormat`	Optional	The binding format for record targets: `JSON`, `XML`, or `CSV`. When absent, the format is inferred from the path's extension (`.json`, `.xml`, `.csv`).

CopyOptions

Options for Client.copyBlob and Client.copyBlobFromUrl. An asynchronous copy over a leased destination requires that lease to be infinite.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The destination's active lease id, required when the destination is leased.
`metadata`	`map<string>`	Optional	The metadata stored with the destination blob; when omitted, the destination inherits the source's metadata.
`tags`	`map<string>`	Optional	The index tags stored with the destination blob.
`accessTier`	`AccessTier`	Optional	The access tier the destination blob starts in.

AbortCopyOptions

Options for Client.abortCopy.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The destination's active lease id, required when the destination is leased.

SetAccessTierOptions

Options for Client.setAccessTier.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.
`rehydratePriority`	`RehydratePriority`	Optional	How quickly an archived blob is rehydrated; meaningful when leaving the archive tier.

TagOptions

Options for Client.setTags.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.

CreateSnapshotOptions

Options for Client.createSnapshot.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id; not required on a leased blob, but checked when given.
`metadata`	`map<string>`	Optional	The snapshot's own metadata; when omitted, the snapshot inherits the blob's metadata.

CreateBlobOptions

Options for Client.createAppendBlob and Client.createPageBlob.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.
`contentHeaders`	`ContentHeaders`	Optional	The content headers stored with the new blob.
`metadata`	`map<string>`	Optional	The metadata stored with the new blob.
`tags`	`map<string>`	Optional	The index tags stored with the new blob.

AppendBlockOptions

Options for Client.appendBlock and Client.appendBlockFromUrl.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.

PageOptions

Options for Client.uploadPages and Client.clearPages.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.

PageRangeOptions

Options for Client.listPageRanges.

Field	Type	Default	Description
`range`	`ByteRange`	Optional	Restricts the listing to this byte range.
`snapshotId`	`string`	Optional	Lists the ranges of this snapshot instead of the live blob.

StageBlockOptions

Options for Client.stageBlock.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.

StageBlockFromUrlOptions

Options for Client.stageBlockFromUrl.

Field	Type	Default	Description
`leaseId`	`string`	Optional	The active lease id, required when the blob is leased.
`sourceRange`	`ByteRange`	Optional	Stages only this byte range of the source instead of its whole content.

ContainerSasSignatureValues

The values signed into a container SAS token, for Client.generateContainerSas and Client.generateContainerUserDelegationSas. A parameter may be carried by the stored access policy or by the token, but not both; a parameter set in both places fails at use time with HTTP 400.

Field	Type	Default	Description
`expiryTime`	`time:Utc`	Optional	When the token expires. May be omitted only when `identifier` supplies it.
`identifier`	`string`	Optional	A stored access policy on the container whose window and permissions the token inherits. Not valid for the user delegation variants, which reject it.
`startTime`	`time:Utc`	Optional	When the token becomes valid; omit for immediately valid.
`protocol`	`SasProtocol`	Optional	The protocols a request presenting the token may use.
`ipRange`	`string`	Optional	An IP address or range the requests must come from (e.g. `168.1.5.60-168.1.5.70`).
`permissions`	`ContainerSasPermissions`	Optional	The permissions granted. May be omitted only when `identifier` supplies them.

Generation fails with an Error when no identifier is supplied and the expiryTime or the permissions are missing.

ContainerSasPermissions

The permissions granted by a container SAS: the blob permissions, plus listing and tag queries. Every permission is off unless enabled.

Field	Type	Default	Description
`read`	`boolean`	`false`	Read the blob's content, properties, and metadata.
`add`	`boolean`	`false`	Append a block to the append blob.
`create`	`boolean`	`false`	Create the blob.
`write`	`boolean`	`false`	Write the blob's content, properties, and metadata.
`delete`	`boolean`	`false`	Delete the blob.
`tag`	`boolean`	`false`	Read and write the blob's index tags.
`list`	`boolean`	`false`	List the container's blobs.
`filter`	`boolean`	`false`	Run an index-tag query.

BlobSasSignatureValues

The values signed into a blob SAS token, for Client.generateSas and Client.generateUserDelegationSas. A parameter may be carried by the stored access policy or by the token, but not both; a parameter set in both places fails at use time with HTTP 400.

Field	Type	Default	Description
`expiryTime`	`time:Utc`	Optional	When the token expires. May be omitted only when `identifier` supplies it.
`identifier`	`string`	Optional	A stored access policy on the container whose window and permissions the token inherits. Not valid for the user delegation variants, which reject it.
`startTime`	`time:Utc`	Optional	When the token becomes valid; omit for immediately valid.
`protocol`	`SasProtocol`	Optional	The protocols a request presenting the token may use.
`ipRange`	`string`	Optional	An IP address or range the requests must come from (e.g. `168.1.5.60-168.1.5.70`).
`permissions`	`BlobSasPermissions`	Optional	The permissions granted. May be omitted only when `identifier` supplies them.

Generation fails with an Error when no identifier is supplied and the expiryTime or the permissions are missing.

BlobSasPermissions

The permissions granted by a blob SAS. Every permission is off unless enabled.

Field	Type	Default	Description
`read`	`boolean`	`false`	Read the blob's content, properties, and metadata.
`add`	`boolean`	`false`	Append a block to the append blob.
`create`	`boolean`	`false`	Create the blob.
`write`	`boolean`	`false`	Write the blob's content, properties, and metadata.
`delete`	`boolean`	`false`	Delete the blob.
`tag`	`boolean`	`false`	Read and write the blob's index tags.

AccountSasSignatureValues

The values signed into an account-level SAS token, for AdminClient.generateAccountSas.

Field	Type	Default	Description
`expiryTime`	`time:Utc`	Required	When the token expires.
`permissions`	`AccountSasPermissions`	Required	The permissions granted.
`services`	`AccountSasServices`	Required	The services the token covers.
`resourceTypes`	`AccountSasResourceTypes`	Required	The resource types the token covers.
`startTime`	`time:Utc`	Optional	When the token becomes valid; omit for immediately valid.
`protocol`	`SasProtocol`	Optional	The protocols a request presenting the token may use.
`ipRange`	`string`	Optional	An IP address or range the requests must come from (e.g. `168.1.5.60-168.1.5.70`).

AccountSasPermissions

The permissions granted by an account-level SAS. Every permission is off unless enabled.

Field	Type	Default	Description
`read`	`boolean`	`false`	Read content, properties, and metadata.
`write`	`boolean`	`false`	Write content, properties, and metadata.
`delete`	`boolean`	`false`	Delete resources.
`list`	`boolean`	`false`	List containers and their blobs.
`add`	`boolean`	`false`	Add content (append-style operations).
`create`	`boolean`	`false`	Create new resources.
`update`	`boolean`	`false`	Update a queued message; required by the `Listener`.
`process`	`boolean`	`false`	Get and delete queued messages; required by the `Listener`.
`tag`	`boolean`	`false`	Read and write blob index tags.
`filter`	`boolean`	`false`	Query blobs by their index tags.

AccountSasServices

The storage services an account SAS covers.

Field	Type	Default	Description
`blob`	`boolean`	`false`	The blob service.
`queue`	`boolean`	`false`	The queue service; enable it for a `Listener` credential.

AccountSasResourceTypes

The resource types an account SAS covers.

Field	Type	Default	Description
`'service`	`boolean`	`false`	Service-level operations, such as reading the service properties.
`container`	`boolean`	`false`	Container-level operations, such as creating or listing containers.
`'object`	`boolean`	`false`	Object-level operations on a blob.

ContainerInfo

A container as returned by AdminClient.listContainers.

Field	Type	Description
`name`	`string`	The container name.
`lastModified`	`time:Utc`	When the container was last modified.
`eTag`	`string`	The container's entity tag.
`publicAccess`	`PublicAccess`	The anonymous access level.
`leaseState`	`LeaseState`	The lease state.
`leaseStatus`	`LeaseStatus`	Whether the container is locked by a lease.
`leaseDuration`	`LeaseDuration?`	Whether a held lease is fixed-duration or infinite, or `()` when no lease is held.
`metadata`	`map<string>`	The container's metadata; present only when the listing requested it.
`isDeleted`	`boolean`	Whether the container is soft-deleted; present only on soft-deleted entries.
`deletedVersion`	`string`	The restore version of a soft-deleted container; pass to `AdminClient.undeleteContainer`.
`deletedTime`	`time:Utc`	When the container was deleted; present only on soft-deleted entries.
`remainingRetentionDays`	`int`	Days remaining before the soft-deleted container is purged.

ContainerList

The result of AdminClient.listContainers.

Field	Type	Description
`containers`	`ContainerInfo[]`	The containers returned.
`nextMarker`	`string`	The marker to resume the listing from; present only when more containers remain.

ContainerProperties

The bound container's properties and metadata, as returned by Client.getContainerProperties.

Field	Type	Description
`lastModified`	`time:Utc`	When the container was last modified.
`eTag`	`string`	The container's entity tag.
`publicAccess`	`PublicAccess`	The anonymous access level.
`metadata`	`map<string>`	The container's complete metadata set.
`leaseState`	`LeaseState`	The lease state.
`leaseStatus`	`LeaseStatus`	Whether the container is locked by a lease.
`leaseDuration`	`LeaseDuration?`	Whether a held lease is fixed-duration or infinite, or `()` when no lease is held.
`hasImmutabilityPolicy`	`boolean`	Whether an immutability policy is set on the container.
`hasLegalHold`	`boolean`	Whether a legal hold is set on the container.

SignedIdentifier

One stored access policy: a validity window and a permission string under an identifier.

Field	Type	Default	Description
`id`	`string`	Required	The identifier a SAS token references to inherit this policy.
`startTime`	`time:Utc`	Optional	When the policy becomes valid.
`expiryTime`	`time:Utc`	Optional	When the policy expires.
`permissions`	`string`	Optional	The permissions the policy grants, as the wire's permission string.

ContainerAccessPolicy

A container's anonymous access level and its stored access policies, as returned by Client.getContainerAccessPolicy.

Field	Type	Description
`access`	`PublicAccess`	The anonymous access level.
`identifiers`	`SignedIdentifier[]`	The stored access policies, at most five.

BlobEntry

One entry of a blob listing, as returned by Client.listBlobs and inside BlobList. In the hierarchical mode an entry whose isPrefix is set is a collapsed group of names rather than a blob.

Field	Type	Description
`path`	`string`	The blob's container-relative path, which feeds the path-taking operations directly.
`isPrefix`	`boolean`	Whether this entry is a collapsed prefix rather than a blob; `false` by default.
`contentLength`	`int`	The blob's size in bytes; absent on prefix entries.
`lastModified`	`time:Utc`	When the blob was last modified.
`eTag`	`string`	The blob's entity tag.
`blobType`	`string`	The blob type (`BlockBlob`, `AppendBlob`, or `PageBlob`).
`accessTier`	`string`	The blob's access tier, as the wire's string.
`metadata`	`map<string>`	The blob's metadata; present only when the listing requested it.
`tags`	`map<string>`	The blob's index tags; present only when the listing requested it.
`snapshotId`	`string`	The snapshot identifier; present on snapshot entries.
`isDeleted`	`boolean`	Whether the blob is soft-deleted; present on soft-deleted entries.

BlobList

One page of a blob listing, as returned by Client.listBlobsPage.

Field	Type	Description
`blobs`	`BlobEntry[]`	The blobs returned.
`nextMarker`	`string`	The marker to resume the listing from; present only when more blobs remain.

BlobProperties

A blob's properties, metadata, and the state of its most recent copy, as returned by Client.getBlobProperties.

Field	Type	Description
`lastModified`	`time:Utc`	When the blob was last modified.
`createdTime`	`time:Utc`	When the blob was created.
`eTag`	`string`	The blob's entity tag.
`contentLength`	`int`	The blob's size in bytes.
`contentHeaders`	`ContentHeaders`	The blob's content headers.
`metadata`	`map<string>`	The blob's complete metadata set.
`blobType`	`string`	The blob type (`BlockBlob`, `AppendBlob`, or `PageBlob`).
`accessTier`	`string`	The access tier, as the wire's string, since the service's tier set is open-ended.
`accessTierInferred`	`boolean`	Whether the tier was inferred rather than set explicitly; present whenever the blob has a tier.
`archiveStatus`	`string`	The rehydration state, set while a rehydration from the archive tier is pending.
`leaseState`	`LeaseState`	The lease state.
`leaseStatus`	`LeaseStatus`	Whether the blob is locked by a lease.
`leaseDuration`	`LeaseDuration?`	Whether a held lease is fixed-duration or infinite, or `()` when no lease is held.
`copyStatus`	`CopyStatusInfo`	The most recent copy operation; absent when the blob was never a copy destination.
`blobSequenceNumber`	`int`	The page blob's write sequence marker; present only on page blobs.
`committedBlockCount`	`int`	The append blob's committed block count; present only on append blobs.

CopyStatusInfo

The state of a blob's most recent copy operation, carried by BlobProperties.copyStatus.

Field	Type	Description
`copyId`	`string`	The identifier of the copy operation.
`copyStatus`	`CopyStatus`	The copy's state.
`copySource`	`string`	The URL the content was copied from.
`copyProgress`	`string`	The bytes copied so far, as `copied/total`.
`copyCompletionTime`	`time:Utc`	When the copy completed.
`copyStatusDescription`	`string`	The service's description of a failed or aborted copy.

CopyInfo

The identifier and state of a copy at the moment the service accepted it, as returned by Client.copyBlob and Client.copyBlobFromUrl.

Field	Type	Description
`copyId`	`string`	The identifier of the copy operation, which `abortCopy` cancels.
`copyStatus`	`CopyStatus`	The copy's state at acceptance, which may already be `SUCCESS` for a small copy.

TaggedBlobEntry

One blob matched by an index-tag query, as returned by Client.findBlobsByTags.

Field	Type	Description
`path`	`string`	The blob's container-relative path.
`tags`	`map<string>`	The blob's index tags.

PageRange

One written byte range of a page blob, as returned by Client.listPageRanges.

Field	Type	Description
`offset`	`int`	The range's start offset in bytes.
`length`	`int`	The range's length in bytes.

BlockInfo

One block of a block blob.

Field	Type	Description
`blockId`	`string`	The block's base64 identifier.
`sizeBytes`	`int`	The block's size in bytes.

BlockList

A block blob's committed and staged blocks, as returned by Client.listBlocks.

Field	Type	Description
`committedBlocks`	`BlockInfo[]`	The blocks that make up the blob's current content.
`uncommittedBlocks`	`BlockInfo[]`	The blocks staged but not yet committed.

ServiceProperties

The account's blob service configuration, as returned by AdminClient.getServiceProperties and taken by setServiceProperties. A group present in the record replaces that group whole; a group absent is left unchanged.

Field	Type	Description
`hourMetrics`	`MetricsProperties`	Hourly request-metrics collection.
`minuteMetrics`	`MetricsProperties`	Per-minute request-metrics collection.
`logging`	`LoggingProperties`	Classic request logging.
`cors`	`CorsRule[]`	The CORS rules; an empty array deletes every rule.
`deleteRetentionPolicy`	`RetentionPolicy`	The blob soft-delete retention policy, the prerequisite for `undeleteBlob`.
`staticWebsite`	`StaticWebsiteProperties`	The static website settings.
`defaultServiceVersion`	`string`	The service version applied to requests that do not name one.

MetricsProperties

Request-metrics collection for the blob service.

Field	Type	Description
`version`	`string`	The metrics configuration version.
`enabled`	`boolean`	Whether metrics collection is enabled.
`includeApis`	`boolean`	Whether per-API metrics are collected.
`retentionPolicy`	`RetentionPolicy`	How long the metrics data is retained.

LoggingProperties

Classic request logging for the blob service.

Field	Type	Description
`version`	`string`	The logging configuration version.
`read`	`boolean`	Whether read requests are logged.
`write`	`boolean`	Whether write requests are logged.
`delete`	`boolean`	Whether delete requests are logged.
`retentionPolicy`	`RetentionPolicy`	How long the log data is retained.

RetentionPolicy

How long soft-deleted blobs, or metrics and log data, are retained.

Field	Type	Description
`enabled`	`boolean`	Whether the retention policy is enabled.
`days`	`int`	The number of days a deleted resource is retained.

CorsRule

One cross-origin resource sharing rule of the blob service.

Field	Type	Description
`allowedOrigins`	`string[]`	The origins allowed to make cross-origin requests.
`allowedMethods`	`string[]`	The HTTP methods allowed in cross-origin requests.
`allowedHeaders`	`string[]`	The request headers the origin may specify.
`exposedHeaders`	`string[]`	The response headers exposed to the client.
`maxAgeInSeconds`	`int`	How long a browser may cache the preflight response, in seconds.

StaticWebsiteProperties

The account's static website settings. The connector offers no operations against the static website endpoint itself.

Field	Type	Description
`enabled`	`boolean`	Whether static website hosting is enabled.
`indexDocument`	`string`	The blob served for a directory request.
`errorDocument404Path`	`string`	The blob served when a request matches nothing.
`defaultIndexDocumentPath`	`string`	The default index document path.

AccountInfo

The storage account's SKU, kind, and namespace type, as returned by AdminClient.getAccountInfo.

Field	Type	Description
`skuName`	`string`	The account's SKU name (e.g. `Standard_LRS`).
`accountKind`	`string`	The account kind (e.g. `StorageV2`).
`isHierarchicalNamespaceEnabled`	`boolean`	Whether the account has a hierarchical namespace (Azure Data Lake Storage Gen2), on which directories are real and renames exist through a different endpoint.

UserDelegationKey

A key for signing user-delegation SAS tokens, obtained from AdminClient.getUserDelegationKey.

Field	Type	Description
`signedObjectId`	`string`	The object ID of the Entra ID identity the key was issued to.
`signedTenantId`	`string`	The tenant the identity belongs to.
`signedStart`	`time:Utc`	When the key becomes valid.
`signedExpiry`	`time:Utc`	When the key expires; tokens signed with it cannot outlive this.
`signedService`	`string`	The service the key applies to.
`signedVersion`	`string`	The service version that issued the key.
`value`	`string`	The key value used to sign tokens.

Enums

AccessTier: HOT ("Hot"), COOL ("Cool"), COLD ("Cold"), ARCHIVE ("Archive"). The tiers the connector sets on a blob; the tier a blob reports is a plain string, because the service's tier set is open-ended.
RehydratePriority: STANDARD ("Standard", documented at up to fifteen hours), HIGH ("High", typically under one hour).
PublicAccess: PRIVATE ("private"), BLOB ("blob", anonymous read access to blobs), CONTAINER ("container", anonymous read access to blobs and anonymous listing of the container).
DeleteSnapshotsOption: INCLUDE ("include", delete the blob together with its snapshots), ONLY_SNAPSHOTS ("only", delete only the snapshots, keeping the blob).
FileFormat: JSON, XML, CSV.
CopyStatus: PENDING ("pending"), SUCCESS ("success"), ABORTED ("aborted"), FAILED ("failed").
LeaseState: AVAILABLE ("available"), LEASED ("leased"), EXPIRED ("expired"), BREAKING ("breaking"), BROKEN ("broken").
LeaseStatus: LOCKED ("locked"), UNLOCKED ("unlocked").
LeaseDuration: INFINITE ("infinite"), FIXED ("fixed").
SasProtocol: HTTPS ("https"), HTTPS_HTTP ("https,http").
EntraIdKind: DEFAULT_AZURE_CREDENTIAL ("default"), MANAGED_IDENTITY ("managed-identity").
RetryPolicyType: EXPONENTIAL ("exponential"), FIXED_INTERVAL ("fixed").
ProxyType: HTTP, SOCKS4, SOCKS5.

Errors

Every operation returns the module's Error on failure. The hierarchy splits by origin:

Error: the root type, and the type of every client-side failure (invalid configuration, local I/O, content that fails to bind or serialize, a value refused by a local check). It carries no detail fields. The listener adds three direct subtypes that are never mapped from an Azure error code: ContentBindingError (a blob's content could not be bound to a handler's parameter type; its detail carries containerName, path, and, when the content was already read into memory, content), and DeadLetterError and RetryError (returned by a handler to steer settlement). See the Trigger Reference.
ServiceError: any error the Azure service raised, always carrying httpStatus and errorCode in its detail. Its subtypes are NotFoundError (404), ConflictError (409), AuthorizationError (403), PreconditionFailedError (412), RangeNotSatisfiableError (416), ArchivedBlobError (409, the blob is still archived or currently rehydrating), and InvalidBlobTypeError (409, the operation applies to another blob type). An unmapped service code lands on the generic ServiceError.

The mapping keys on the Azure error-code string rather than the HTTP status alone, so BlobArchived, BlobBeingRehydrated, and InvalidBlobType (each 409) become their own types while a state conflict such as ContainerAlreadyExists (also 409) becomes a ConflictError. Check the more specific error types before the general ones.

Client​

Configuration​

Initializing the client​

Operations​

Container operations​

Blob operations​

Transfer operations​

Copy operations​

Access tier operations​

Blob index tag operations​

Snapshot operations​

Lease operations​

Append blob operations​

Page blob operations​

Block operations​

SAS generation​

AdminClient​

Configuration​

Initializing the client​

Operations​

Container management​

Service configuration and account information​

User delegation key and account SAS​

Supporting types​

ContentHeaders​

ByteRange​

LeaseOptions​

ContainerListOptions​

ContainerCreateOptions​

DeleteContainerOptions​

ContainerMetadataOptions​

AccessPolicyOptions​

BlobListOptions​

BlobPageOptions​

DeleteBlobOptions​

BlobMetadataOptions​

ContentHeaderOptions​

UploadOptions​

UploadContentOptions​

DownloadOptions​

GetBlobOptions​

CopyOptions​

AbortCopyOptions​

SetAccessTierOptions​

TagOptions​

CreateSnapshotOptions​

CreateBlobOptions​

AppendBlockOptions​

PageOptions​

PageRangeOptions​

StageBlockOptions​

StageBlockFromUrlOptions​

ContainerSasSignatureValues​

ContainerSasPermissions​

BlobSasSignatureValues​

BlobSasPermissions​

AccountSasSignatureValues​

AccountSasPermissions​

AccountSasServices​

AccountSasResourceTypes​

ContainerInfo​

ContainerList​

ContainerProperties​

SignedIdentifier​

ContainerAccessPolicy​

BlobEntry​

BlobList​

BlobProperties​

CopyStatusInfo​

CopyInfo​

TaggedBlobEntry​

PageRange​

BlockInfo​

BlockList​

ServiceProperties​

MetricsProperties​

LoggingProperties​

RetentionPolicy​

CorsRule​

StaticWebsiteProperties​

Client

Configuration

Initializing the client

Operations

Container operations

Blob operations

Transfer operations

Copy operations

Access tier operations

Blob index tag operations

Snapshot operations

Lease operations

Append blob operations

Page blob operations

Block operations

SAS generation

AdminClient

Configuration

Initializing the client

Operations

Container management

Service configuration and account information

User delegation key and account SAS

Supporting types

ContentHeaders

ByteRange

LeaseOptions

ContainerListOptions

ContainerCreateOptions

DeleteContainerOptions

ContainerMetadataOptions

AccessPolicyOptions

BlobListOptions

BlobPageOptions

DeleteBlobOptions

BlobMetadataOptions

ContentHeaderOptions

UploadOptions

UploadContentOptions

DownloadOptions

GetBlobOptions

CopyOptions

AbortCopyOptions

SetAccessTierOptions

TagOptions

CreateSnapshotOptions

CreateBlobOptions

AppendBlockOptions

PageOptions

PageRangeOptions

StageBlockOptions

StageBlockFromUrlOptions

ContainerSasSignatureValues

ContainerSasPermissions

BlobSasSignatureValues

BlobSasPermissions

AccountSasSignatureValues

AccountSasPermissions

AccountSasServices

AccountSasResourceTypes

ContainerInfo

ContainerList

ContainerProperties

SignedIdentifier

ContainerAccessPolicy

BlobEntry

BlobList

BlobProperties

CopyStatusInfo

CopyInfo

TaggedBlobEntry

PageRange

BlockInfo

BlockList

ServiceProperties

MetricsProperties

LoggingProperties

RetentionPolicy

CorsRule

StaticWebsiteProperties