diff --git a/en/docs/connectors/catalog/index.mdx b/en/docs/connectors/catalog/index.mdx index 2ca6922ac01..1f631646e81 100644 --- a/en/docs/connectors/catalog/index.mdx +++ b/en/docs/connectors/catalog/index.mdx @@ -45,6 +45,7 @@ Find the right connector for your integration. Use the search bar or filter by c { name: "AWS SQS", description: "Fully managed message queuing with standard and FIFO queues, batch operations, and event-driven consumption", operations: "Send, Receive, Delete, Batch Send, Batch Delete, Queue Management", auth: "AWS IAM (Access Key + Secret Key)", link: "messaging/aws.sqs/aws-sqs-connector-overview", category: "Messaging", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_aws.sqs_4.1.3.png" }, { name: "Azure AI Search", description: "Azure AI Search service management for indexes, indexers, data sources, skillsets, and synonym maps", operations: "Create, Read, Update, Delete, List, Run, Reset, Analyze, Statistics", auth: "API Key", link: "ai-ml/azure.ai.search/azure-ai-search-connector-overview", category: "AI & ML", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_azure.ai.search_1.0.1.png" }, { name: "Azure AI Search Index", description: "AI-powered cloud search with full-text, semantic, and vector search over indexed documents", operations: "Search, Lookup, Index, Suggest, Autocomplete, Count", auth: "API Key", link: "ai-ml/azure.ai.search.index/azure-ai-search-index-connector-overview", category: "AI & ML", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_azure.ai.search.index_1.0.1.png" }, + { name: "Azure Files", description: "Azure Files shares with directory and file management, transfers, copies, SAS generation, and event-driven file monitoring", operations: "Upload, Download, List, Copy, Delete, Rename, Snapshot, Poll", auth: "Access Key / SAS / Connection String / Entra ID", link: "storage-file/azure.storage.files/overview", category: "Storage & Files" }, { name: "Azure Service Bus", description: "Enterprise message broker with queues, topics, subscriptions, and event-driven message processing", operations: "Send, Receive, Schedule, Settle, Admin, Listen", auth: "Connection String", link: "messaging/asb/azure-service-bus-connector-overview", category: "Messaging", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_asb_3.9.1.png" }, { name: "Azure Storage Service", description: "Azure Blob Storage with container management, blob CRUD, and SAS token support", operations: "Create, Read, Delete, List, Upload, Download", auth: "Connection String / SAS Token", link: "storage-file/azure_storage_service/overview", category: "Storage & Files" }, { name: "Candid", description: "Nonprofit data platform with search, profiles, financials, and PDF report downloads", operations: "Search, Profile, Lookup, PDF Download", auth: "API Key", link: "productivity-collaboration/candid/connector-overview", category: "Productivity & Collaboration", icon: "https://bcentral-packageicons.azureedge.net/images/ballerinax_candid_0.2.0.png" }, diff --git a/en/docs/connectors/catalog/storage-file/azure.storage.files/action-reference.md b/en/docs/connectors/catalog/storage-file/azure.storage.files/action-reference.md new file mode 100644 index 00000000000..1371268081e --- /dev/null +++ b/en/docs/connectors/catalog/storage-file/azure.storage.files/action-reference.md @@ -0,0 +1,2152 @@ +--- +connector: true +connector_name: "azure.storage.files" +title: "Actions" +description: "Available operations in the ballerinax/azure.storage.files connector." +toc_max_heading_level: 4 +--- + +# Actions + +The `ballerinax/azure.storage.files` package connects to Microsoft Azure Files. It exposes the following clients: + +| Client | Purpose | +|--------|---------| +| [`Client`](#client) | Operations within one share, bound at initialization. | +| [`AdminClient`](#adminclient) | Account-level share management and service configuration. | + +For event-driven integration, see the [Trigger Reference](trigger-reference.md). + +--- + +## Client + +Operates on a single file share, bound at initialization, and on the directories and files within it. + +### Configuration + +Both clients take a `ClientConfiguration`. Credentials come from the [Setup Guide](setup-guide.md). + +| 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; omit for the service defaults. | +| `transportConfig` | TransportConfig | () | HTTP transport settings (proxy, connection pool, TLS); omit for the defaults. | + +`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 pair `DefaultEntraIdConfig` and `ManagedIdentityConfig`, which would otherwise share the same field shape; these two, and only these two, carry 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 | () | The file service endpoint URL, including the scheme. Omit to use the default https://{accountName}.file.core.windows.net. | + +**`SasConfig`**, Shared Access Signature (SAS) authentication with a bare SAS token: + +| 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 file-service SAS URL, including the scheme and the SAS query string (e.g. https://{account}.file.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 five records, one per Microsoft Entra ID credential kind. The identity must hold the `Storage File Data Privileged Reader` or `Storage File Data Privileged Contributor` role. + +**`DefaultEntraIdConfig`**, authentication through the default credential chain. The 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: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `kind` | DEFAULT_AZURE_CREDENTIAL | Required | Selects the default credential chain (the value `"default"`). | +| `accountName` | string | Required | The storage account name (determines the service URL unless `serviceUrl` overrides it). | +| `serviceUrl` | string | () | The file service endpoint URL, including the scheme. Omit to use the default https://{accountName}.file.core.windows.net. | + +**`ManagedIdentityConfig`**, authentication as an Azure managed identity, for workloads running on Azure compute (VMs, App Service, AKS, Functions): + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `kind` | MANAGED_IDENTITY | Required | Selects the managed-identity credential (the value `"managed-identity"`). | +| `accountName` | string | Required | The storage account name (determines the service URL unless `serviceUrl` overrides it). | +| `clientId` | string | () | The client id of a user-assigned managed identity; omit to use the system-assigned identity. | +| `serviceUrl` | string | () | The file service endpoint URL, including the scheme. Omit to use the default https://{accountName}.file.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 (directory) id. | +| `clientId` | string | Required | The application (client) id of the service principal. | +| `clientSecret` | string | Required | The client secret of the service principal. | +| `serviceUrl` | string | () | The file service endpoint URL, including the scheme. Omit to use the default https://{accountName}.file.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 (directory) id. | +| `clientId` | string | Required | The application (client) id of the service principal. | +| `certificatePath` | string | Required | The path to the certificate file (PEM, or PFX when `certificatePassword` is set). | +| `certificatePassword` | string | () | The password protecting the certificate file, when it has one. | +| `serviceUrl` | string | () | The file service endpoint URL, including the scheme. Omit to use the default https://{accountName}.file.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 (directory) id. | +| `clientId` | string | Required | The application (client) id federated with the workload. | +| `tokenFilePath` | string | Required | The path to the file holding the federated service-account token. | +| `serviceUrl` | string | () | The file service endpoint URL, including the scheme. Omit to use the default https://{accountName}.file.core.windows.net. | + +**`RetryConfig`**, retry behavior for service requests: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `retryPolicyType` | RetryPolicyType | EXPONENTIAL | How the delay between tries grows (`EXPONENTIAL` or `FIXED`). | +| `maxTries` | int | 4 | The maximum number of tries (the first attempt plus retries). | +| `tryTimeoutSeconds` | decimal | 60 | The timeout applied to each individual try, in seconds. | +| `retryDelaySeconds` | decimal | 4 | The base delay between tries, in seconds. | +| `maxRetryDelaySeconds` | decimal | 120 | The upper bound on the delay between tries, in seconds. | +| `secondaryHostUrl` | string | () | A secondary endpoint to retry reads against (geo-redundant accounts). | + +**`TransportConfig`**, HTTP transport settings, proxying, connection pooling, and TLS: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `proxy` | ProxyConfig | () | Route traffic through this proxy. | +| `connectionPool` | ConnectionPoolConfig | {} | Connection-pool tuning. | +| `secureSocket` | SecureSocket | () | Custom TLS settings (trust and key material, verification). | + +**`ProxyConfig`**, routes the connector's traffic through a proxy server: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `proxyType` | ProxyType | Required | The proxy protocol (`HTTP`, `SOCKS4`, or `SOCKS5`). | +| `host` | string | Required | The proxy host name or IP address. | +| `port` | int | Required | The proxy port. | +| `username` | string | () | The user name, when the proxy requires authentication. | +| `password` | string | () | The password, when the proxy requires authentication. | +| `nonProxyHosts` | string[] | [] | Hosts reached directly, bypassing the proxy. | + +**`ConnectionPoolConfig`**, tunes the connector's HTTP connection pool: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `maxConnections` | int | 50 | The maximum number of concurrent connections. | +| `idleTimeoutSeconds` | decimal | 60 | How long an idle connection is kept before being closed, in seconds. | +| `connectTimeoutSeconds` | decimal | 10 | The timeout for establishing a connection, in seconds. | +| `readTimeoutSeconds` | decimal | 60 | The timeout for reading a response, in seconds. | + +**`SecureSocket`**, custom TLS settings for the connection to the service: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `cert` | crypto:TrustStore|string | () | The trust material for verifying the server: a PKCS12 or JKS truststore, or the path to a PEM certificate file. Omit to trust the platform's default certificate authorities. | +| `'key` | crypto:KeyStore|CertKey | () | The client's own identity for mutual TLS: a PKCS12 or JKS keystore, or a certificate and private key pair. Omit when the server does not request a client certificate. | +| `tlsVersions` | string[] | () | The TLS versions offered during the handshake (e.g. `TLSv1.3`, `TLSv1.2`). Omit to use the platform defaults. | +| `ciphers` | string[] | () | The cipher suites offered during the handshake. Omit to use the platform defaults. | +| `verifyHostName` | boolean | true | Verify that the server certificate matches the host being called. Disabling this removes protection against man-in-the-middle attacks, so it is meant for testing only. | +| `shareSession` | boolean | true | Allow TLS sessions to be reused across connections. | +| `validateRevocation` | boolean | false | Check the server certificate against revocation information: a stapled OCSP response when the server sends one, otherwise an OCSP or CRL fetch. Requires `cert` to be set. | +| `serverName` | string | () | The SNI (Server Name Indication) host name presented during the handshake; omit to use the host being called. | +| `handshakeTimeoutSeconds` | decimal | () | The TLS handshake timeout, in seconds. | +| `sessionTimeoutSeconds` | decimal | () | How long a TLS session stays reusable, in seconds. | + +**`CertKey`**, a client certificate and private key pair, as files: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `certFile` | string | Required | The path to the certificate file. | +| `keyFile` | string | Required | The path to the private key file. | +| `keyPassword` | string | () | The password protecting the private key, when it has one. | + +### Initializing the client + +The client binds to one share at initialization. `Client.init` makes no call to Azure, so binding to a nonexistent share succeeds and the first operation on it fails with a `NotFoundError`; check up front with `AdminClient.hasShare`. + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string accountKey = ?; + +files:Client fileShare = check new ("reports", auth = {accountName, accountKey}); +``` + +With a Microsoft Entra ID service principal instead of an account key: + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string tenantId = ?; +configurable string clientId = ?; +configurable string clientSecret = ?; + +files:Client fileShare = 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: + +```toml +# The fields present select the union member: +[myapp.filesConfig] +auth = {accountName = "myacct", accountKey = "..."} # SharedKeyConfig +# auth = {accountName = "myacct", sasToken = "sv=..."} # SasConfig +# auth = {sasUrl = "https://myacct.file.core.windows.net/?sv=..."}# SasUrlConfig +# auth = {connectionString = "..."} # ConnectionStringConfig +# auth = {kind = "default", accountName = "myacct"} # DefaultEntraIdConfig +# auth = {kind = "managed-identity", accountName = "myacct"} # ManagedIdentityConfig +# 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 + +#### Share operations + +Operations on the bound share itself. + +
+getShareProperties + +
+ +Gets the properties of the bound share (quota, tier, protocols). This is a share-level operation, so it needs account-level credentials at runtime; a share- or file-scoped SAS fails. + +**Returns:** `ShareProperties|Error` + +**Sample code:** + +```ballerina +files:ShareProperties properties = check fileShare->getShareProperties(); +``` + +**Sample response:** + +```ballerina +{ + quotaInGb: 100, + accessTier: "TransactionOptimized", + eTag: "\"0x8DDA1B2C3D4E5F6\"", + lastModified: [1770307200, 0.0], + metadata: {department: "finance"} +} +``` + +
+ +
+ +
+setShareMetadata + +
+ +Replaces the metadata of the bound share. The supplied map replaces the complete metadata set, so any entry omitted from it is cleared. This is a share-level operation, so it needs account-level credentials at runtime; a share- or file-scoped SAS fails. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `metadata` | map<string> | Yes | The complete metadata set (replaces all existing metadata). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->setShareMetadata({department: "finance", year: "2026"}); +``` + +
+ +
+ +
+getShareUsage + +
+ +Gets the approximate amount of data stored on the bound share, in bytes. This is a share-level operation, so it needs account-level credentials at runtime; a share- or file-scoped SAS fails. + +**Returns:** `int|Error` + +**Sample code:** + +```ballerina +int usageBytes = check fileShare->getShareUsage(); +``` + +**Sample response:** + +```ballerina +1073741824 +``` + +
+ +
+ +#### Directory operations + +Directory paths are slash-delimited, share-relative strings such as `"/2026/q1"`; the leading slash is optional. + +
+createDirectory + +
+ +Creates a directory in the bound share. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `directoryPath` | string | Yes | The share-relative path of the directory to create. | +| `options` | DirectoryCreateOptions | No | Optional creation options (metadata). See [DirectoryCreateOptions](#directorycreateoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->createDirectory("/2026/q1"); +``` + +
+ +
+ +
+deleteDirectory + +
+ +Deletes a directory from the bound share; the directory must be empty, otherwise the delete fails with a `ConflictError`. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `directoryPath` | string | Yes | The share-relative path of the directory to delete. | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->deleteDirectory("/2026/q1/drafts"); +``` + +
+ +
+ +
+hasDirectory + +
+ +Checks whether a directory exists in the bound share. It returns `false` only when Azure confirms the directory is absent (a confirmed 404); an `Error` means the check itself failed. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `directoryPath` | string | Yes | The share-relative path of the directory. | + +**Returns:** `boolean|Error` + +**Sample code:** + +```ballerina +boolean directoryExists = check fileShare->hasDirectory("/2026/q1"); +``` + +**Sample response:** + +```ballerina +true +``` + +
+ +
+ +
+getDirectoryProperties + +
+ +Gets the properties of a directory. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `directoryPath` | string | Yes | The share-relative path of the directory. | + +**Returns:** `DirectoryProperties|Error` + +**Sample code:** + +```ballerina +files:DirectoryProperties properties = check fileShare->getDirectoryProperties("/2026/q1"); +``` + +**Sample response:** + +```ballerina +{ + eTag: "\"0x8DDA1B2C3D4E5F6\"", + lastModified: [1770307200, 0.0], + isServerEncrypted: true +} +``` + +
+ +
+ +
+setDirectoryMetadata + +
+ +Replaces the metadata of a directory. The supplied map replaces the complete metadata set, so any entry omitted from it is cleared. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `directoryPath` | string | Yes | The share-relative path of the directory. | +| `metadata` | map<string> | Yes | The complete metadata set (replaces all existing metadata). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->setDirectoryMetadata("/2026/q1", {reviewed: "true"}); +``` + +
+ +
+ +
+list + +
+ +Lists the entries (files and subdirectories) under a directory as one lazy stream. By default the listing is non-recursive and `Entry.eTag`/`Entry.lastModified` are absent; set `ListOptions.recursive` to descend into subdirectories and `ListOptions.includeExtendedInfo` to populate the ETag and timestamp fields. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `directoryPath` | string | Yes | The share-relative path of the directory to list. | +| `options` | ListOptions | No | Optional listing options (prefix, recursion, extended info). See [ListOptions](#listoptions). | + +**Returns:** `stream|Error` + +**Sample code:** + +```ballerina +stream entries = check fileShare->list("/2026/q1", {recursive: true}); +check entries.forEach(function(files:Entry entry) { + // process entry.path +}); +``` + +**Sample response:** + +```ballerina +{ + path: "/2026/q1/report.pdf", + name: "report.pdf", + isDirectory: false, + sizeBytes: 524288, + id: "13835093239654252544" +} +``` + +
+ +
+ +
+renameDirectory + +
+ +Renames or moves a directory within the bound share, together with its entire contents; a rename never crosses shares. It is a move, not a copy: the source path no longer exists afterward. An existing file at the destination is overwritten only with `RenameOptions.replaceIfExists`; an existing directory at the destination always fails the operation. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `sourcePath` | string | Yes | The current share-relative path of the directory. | +| `destinationPath` | string | Yes | The new share-relative path. | +| `options` | RenameOptions | No | Optional rename options (overwrite, metadata). See [RenameOptions](#renameoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->renameDirectory("/2026/q1-draft", "/2026/q1"); +``` + +
+ +
+ +#### File operations + +File paths are slash-delimited, share-relative strings such as `"/2026/q1/report.pdf"`; the leading slash is optional. + +
+createFile + +
+ +Creates an empty file, pre-allocated at a fixed size. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file to create. | +| `sizeInBytes` | int | Yes | The size of the file, in bytes. | +| `options` | CreateOptions | No | Optional creation options (headers, metadata). See [CreateOptions](#createoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->createFile("/2026/q1/report.pdf", 524288); +``` + +
+ +
+ +
+deleteFile + +
+ +Deletes a file from the bound share. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file to delete. | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->deleteFile("/2026/q1/report-old.pdf"); +``` + +
+ +
+ +
+hasFile + +
+ +Checks whether a file exists in the bound share. It returns `false` only when Azure confirms the file is absent (a confirmed 404); an `Error` means the check itself failed. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file. | + +**Returns:** `boolean|Error` + +**Sample code:** + +```ballerina +boolean fileExists = check fileShare->hasFile("/2026/q1/report.pdf"); +``` + +**Sample response:** + +```ballerina +true +``` + +
+ +
+ +
+getFileProperties + +
+ +Gets the properties of a file, including its metadata (there is no separate metadata getter; read metadata from the `metadata` field of the result). + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file. | + +**Returns:** `FileProperties|Error` + +**Sample code:** + +```ballerina +files:FileProperties properties = check fileShare->getFileProperties("/2026/q1/report.pdf"); +``` + +**Sample response:** + +```ballerina +{ + eTag: "\"0x8DDA1B2C3D4E5F6\"", + lastModified: [1770307200, 0.0], + contentLength: 524288, + contentType: "application/pdf", + metadata: {reviewed: "true"}, + isServerEncrypted: true +} +``` + +
+ +
+ +
+setFileMetadata + +
+ +Replaces the metadata of a file. The supplied map replaces the complete metadata set, so any entry omitted from it is cleared; read the current metadata from `getFileProperties().metadata`. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file. | +| `metadata` | map<string> | Yes | The complete metadata set (replaces all existing metadata). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->setFileMetadata("/2026/q1/report.pdf", {reviewed: "true"}); +``` + +
+ +
+ +
+setContentHeaders + +
+ +Sets the content headers of a file, such as `Content-Type` and `Cache-Control`. The supplied record replaces the complete header set, so any header omitted from it is cleared; metadata is untouched. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file. | +| `headers` | ContentHeaders | Yes | The full set of content headers the file should carry. See [ContentHeaders](#contentheaders). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->setContentHeaders("/2026/q1/report.pdf", { + contentType: "application/pdf", + cacheControl: "max-age=3600" +}); +``` + +
+ +
+ +
+renameFile + +
+ +Renames or moves a file within the bound share; a rename never crosses shares. It is a move, not a copy: the source path no longer exists afterward. An existing destination file is overwritten only when `RenameOptions.replaceIfExists` is set, and an existing directory at the destination always fails the operation. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `sourcePath` | string | Yes | The current share-relative path of the file. | +| `destinationPath` | string | Yes | The new share-relative path. | +| `options` | RenameOptions | No | Optional rename options (overwrite, metadata). See [RenameOptions](#renameoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->renameFile("/2026/q1/report-draft.pdf", "/2026/q1/report.pdf", {replaceIfExists: true}); +``` + +
+ +
+ +#### Transfer operations + +`uploadFromFile` and `download` move data between a local file on disk and the share; the other operations work in memory or over streams. Transfer paths are full paths including the file name on both sides. + +
+uploadFromFile + +
+ +Uploads a local file to the bound share (disk to share). + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `sourcePath` | string | Yes | The path of the local file to upload, including the file name. | +| `destinationPath` | string | Yes | The share-relative path the file is written to, including the file name. | +| `options` | UploadOptions | No | Optional upload options (headers, metadata). See [UploadOptions](#uploadoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->uploadFromFile("./reports/q1.pdf", "/2026/q1/report.pdf"); +``` + +
+ +
+ +
+upload + +
+ +Uploads in-memory content to the bound share. A `byte[]` is written as-is, and an `xml` value as its textual form. A `string` is written verbatim as raw UTF-8 text, never JSON-quoted; call `toJsonString()` first to store a JSON encoding of a string. A record (which includes any map of `anydata` members), a record array, or any other `json` value is serialized per the format resolved from `UploadContentOptions.fileFormat` when set, else from the destination path's extension (`.json`, `.xml`, `.csv`): a record becomes a JSON or an XML document (never CSV), a record array becomes CSV rows headed by the union of the records' field names in first-seen order (nil or absent members as empty cells), and any other `json` value (an array, a scalar, or nil) becomes a JSON document. An unresolvable format, a record directed to CSV, a record array directed to a non-CSV format, or a non-mapping `json` value directed to a non-JSON format fails with a client-side `Error`. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `content` | UploadContent | Yes | The content to upload: byte[]|string|json|xml|record {}|record {}[]. | +| `destinationPath` | string | Yes | The share-relative path the content is written to, including the file name. | +| `options` | UploadContentOptions | No | Every [UploadOptions](#uploadoptions) field plus `fileFormat` (`JSON`, `XML`, or `CSV`), the record serialization format override. | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +Metrics metrics = {revenue: 1250000, growth: 0.12}; +check fileShare->upload(metrics, "/2026/q1/metrics.json"); +``` + +
+ +
+ +
+uploadFromStream + +
+ +Uploads a byte stream to the bound share. `contentLength` is required up front, and must not be negative, because Azure Files pre-allocates the file, so a stream of unknown length cannot be uploaded. A length mismatch or a failure of the source stream is a client-side `Error`, and every failure closes the source stream. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `content` | stream<byte[], error?> | Yes | The byte stream to upload. | +| `contentLength` | int | Yes | The total length of the content, in bytes. | +| `destinationPath` | string | Yes | The share-relative path the content is written to, including the file name. | +| `options` | UploadOptions | No | Optional upload options (headers, metadata). See [UploadOptions](#uploadoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +stream fileStream = check io:fileReadBlocksAsStream("./reports/q1.pdf"); +check fileShare->uploadFromStream(fileStream, 524288, "/2026/q1/report.pdf"); +``` + +
+ +
+ +
+download + +
+ +Downloads a file to a local path (share to disk). The download fails with a client-side `Error` when a local file already exists at `destinationPath`. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `sourcePath` | string | Yes | The share-relative path of the file to download, including the file name. | +| `destinationPath` | string | Yes | The local path to write the downloaded file to (must not exist). | +| `options` | DownloadOptions | No | Optional download options (range, snapshot). See [DownloadOptions](#downloadoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->download("/2026/q1/report.pdf", "./reports/q1.pdf"); +``` + +
+ +
+ +
+getFile + +
+ +Retrieves the file's content in the form the target type selects: `byte[]` (raw, materialized), `string` (UTF-8 text; invalid UTF-8 fails client-side), `json`, `xml`, `record {}`/`record {}[]`, which includes any map of `anydata` members and arrays of them (bound per the resolved format), `stream` (a lazy byte stream), or `stream` (lazy CSV rows, where a row that fails to bind surfaces as that pull's error entry). Record-shaped targets resolve their format from `options.fileFormat` when set, else the path's extension (`.json`, `.xml`, `.csv`): a single record binds from JSON or XML (never CSV), a record array from a JSON array or CSV rows (never XML), and an unresolvable format fails with a client-side `Error`. CSV content binds to record array and record stream targets only; for positional or headerless rows, read the content as `string` or `byte[]` and parse it with the `data.csv` module. Binding is strict. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The source share-relative path. | +| `options` | GetFileOptions | No | Optional retrieval options (range, snapshot, record binding format). See [GetFileOptions](#getfileoptions). | +| `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:** + +```ballerina +byte[] raw = check fileShare->getFile("/2026/q1/report.pdf"); +Person[] people = check fileShare->getFile("/2026/q1/people.csv"); +stream chunks = check fileShare->getFile("/2026/q1/large.bin"); +``` + +
+ +
+ +#### Copy operations + +Server-side copy is non-blocking: it returns a `copyId` you can poll with `checkCopyStatus` and cancel with `abortCopy`. + +
+copyFile + +
+ +Copies a file within the bound share. The copy is asynchronous; inspect the returned `CopyInfo.copyStatus` for its state. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `sourcePath` | string | Yes | The source share-relative path. | +| `destinationPath` | string | Yes | The destination share-relative path. | +| `options` | CopyOptions | No | Optional copy options (metadata). See [CopyOptions](#copyoptions). | + +**Returns:** `CopyInfo|Error` + +**Sample code:** + +```ballerina +files:CopyInfo copy = check fileShare->copyFile("/2026/q1/report.pdf", "/archive/2026-q1-report.pdf"); +``` + +**Sample response:** + +```ballerina +{ + copyId: "1c556d19-8b45-42d1-a4b5-6a1e73923d20", + copyStatus: "pending", + eTag: "\"0x8DDA1B2C3D4E5F6\"", + lastModified: [1770307200, 0.0] +} +``` + +
+ +
+ +
+copyFileFromUrl + +
+ +Copies a file from an external URL into the bound share. A cross-account file source or any blob-container source must carry its own authorization in the URL (typically a SAS token); a same-account file source needs none. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `sourceUrl` | string | Yes | The URL of the source file. | +| `destinationPath` | string | Yes | The destination share-relative path. | +| `options` | CopyOptions | No | Optional copy options (metadata). See [CopyOptions](#copyoptions). | + +**Returns:** `CopyInfo|Error` + +**Sample code:** + +```ballerina +files:CopyInfo copy = check fileShare->copyFileFromUrl( + "https://otheracct.file.core.windows.net/backups/2026/q1/report.pdf?sv=2025-05-05&sig=...", + "/2026/q1/report.pdf" +); +``` + +**Sample response:** + +```ballerina +{ + copyId: "8d1f3a52-6c07-4e4b-9f21-b3a8c5d4e6f7", + copyStatus: "pending", + eTag: "\"0x8DDA1B2C3D4E5F7\"", + lastModified: [1770307260, 0.0] +} +``` + +
+ +
+ +
+checkCopyStatus + +
+ +Checks the state of the most recent copy operation that targeted a file; it returns `()` when the file was never the destination of a copy. Call again to observe a pending copy's progress. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The destination share-relative path of the copy. | + +**Returns:** `CopyStatusInfo?|Error` + +**Sample code:** + +```ballerina +files:CopyStatusInfo? status = check fileShare->checkCopyStatus("/archive/2026-q1-report.pdf"); +``` + +**Sample response:** + +```ballerina +{ + copyId: "1c556d19-8b45-42d1-a4b5-6a1e73923d20", + copyStatus: "success", + copyProgress: {copiedBytes: 524288, totalBytes: 524288} +} +``` + +
+ +
+ +
+abortCopy + +
+ +Aborts a pending asynchronous copy operation. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The destination share-relative path of the copy. | +| `copyId` | string | Yes | The identifier of the copy to abort (from `CopyInfo.copyId`). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->abortCopy("/archive/2026-q1-report.pdf", "1c556d19-8b45-42d1-a4b5-6a1e73923d20"); +``` + +
+ +
+ +#### Range operations + +A file is pre-allocated; these operations fill, clear, and inspect specific byte ranges, which suits sparse or random-write workloads. + +
+uploadRange + +
+ +Writes a range of bytes into a file at a given offset. A single range write is capped at 4 MiB by the service with no internal chunking (the transfer operations chunk internally); larger content is rejected. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file. | +| `offset` | int | Yes | The zero-based byte offset at which to begin writing. | +| `content` | byte[] | Yes | The bytes to write (at most 4 MiB). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +byte[] content = check io:fileReadBytes("./chunks/part-000.bin"); +check fileShare->uploadRange("/2026/q1/data.bin", 0, content); +``` + +
+ +
+ +
+clearRange + +
+ +Clears a range of bytes in a file. The service deallocates space in 512-byte units, so a cleared span smaller than that is zeroed but may still appear in `listRanges`. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file. | +| `offset` | int | Yes | The zero-based byte offset at which to begin clearing. | +| `length` | int | Yes | The number of bytes to clear. | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->clearRange("/2026/q1/data.bin", 1048576, 524288); +``` + +
+ +
+ +
+listRanges + +
+ +Lists the valid (written) byte ranges of a file; both bounds of each returned `Range` are inclusive. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file. | +| `options` | RangeListOptions | No | Optional range-listing options. See [RangeListOptions](#rangelistoptions). | + +**Returns:** `Range[]|Error` + +**Sample code:** + +```ballerina +files:Range[] ranges = check fileShare->listRanges("/2026/q1/data.bin"); +``` + +**Sample response:** + +```ballerina +[{startByte: 0, endByte: 4194303}] +``` + +
+ +
+ +#### Share snapshot operations + +Point-in-time, read-only copies of the share. Snapshot contents are read through the regular read operations by passing the snapshot's id as the `snapshotId` of `DownloadOptions` or `ListOptions`. + +
+createShareSnapshot + +
+ +Creates a point-in-time, read-only snapshot of the bound share. Like the other snapshot operations, it needs account-level credentials; a share- or file-scoped SAS fails. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `metadata` | map<string> | No | Optional metadata to set on the snapshot; when absent, the share's metadata is copied to the snapshot. | + +**Returns:** `ShareSnapshotInfo|Error` + +**Sample code:** + +```ballerina +files:ShareSnapshotInfo snapshot = check fileShare->createShareSnapshot(); +``` + +**Sample response:** + +```ballerina +{ + snapshotId: "2026-08-06T09:15:22.0000000Z", + eTag: "\"0x8DDA1B2C3D4E5F6\"", + lastModified: [1770307200, 0.0] +} +``` + +
+ +
+ +
+listShareSnapshots + +
+ +Lists the snapshots of the bound share. This operation needs account-level credentials; a share- or file-scoped SAS fails. + +**Returns:** `ShareSnapshotInfo[]|Error` + +**Sample code:** + +```ballerina +files:ShareSnapshotInfo[] snapshots = check fileShare->listShareSnapshots(); +``` + +**Sample response:** + +```ballerina +[ + { + snapshotId: "2026-08-06T09:15:22.0000000Z", + eTag: "\"0x8DDA1B2C3D4E5F6\"", + lastModified: [1770307200, 0.0] + } +] +``` + +
+ +
+ +
+deleteShareSnapshot + +
+ +Deletes one snapshot of the bound share. This operation needs account-level credentials; a share- or file-scoped SAS fails. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `snapshotId` | string | Yes | The identifier of the snapshot to delete. | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check fileShare->deleteShareSnapshot("2026-08-06T09:15:22.0000000Z"); +``` + +
+ +
+ +
+listRangesDiff + +
+ +Lists how a file's byte ranges changed since a share snapshot: the ranges written and the ranges cleared. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file. | +| `previousSnapshotId` | string | Yes | The identifier of the baseline snapshot to diff against. | +| `options` | RangeListOptions | No | Optional range-listing options. See [RangeListOptions](#rangelistoptions). | + +**Returns:** `RangeDiff|Error` + +**Sample code:** + +```ballerina +files:RangeDiff diff = check fileShare->listRangesDiff("/2026/q1/data.bin", "2026-08-06T09:15:22.0000000Z"); +``` + +**Sample response:** + +```ballerina +{ + ranges: [{startByte: 0, endByte: 511}], + clearRanges: [] +} +``` + +
+ +
+ +#### SAS generation + +These are ordinary methods, not remote functions: they sign locally without a service call, so invoke them with `.` rather than `->`. `generateShareSas` and `generateSas` require the client to hold a `SharedKeyConfig` (or a connection string carrying an account key); the user-delegation variants sign with a `UserDelegationKey` obtained from `AdminClient.getUserDelegationKey`. + +
+generateShareSas + +
+ +Generates a SAS (Shared Access Signature) token scoped to the bound share; the client must hold shared key credentials. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `values` | ShareSasSignatureValues | Yes | What the SAS grants: validity window and permissions, or a stored policy reference. See [ShareSasSignatureValues](#sharesassignaturevalues). | + +**Returns:** `string|Error` + +**Sample code:** + +```ballerina +string sasToken = check fileShare.generateShareSas({ + expiryTime: time:utcAddSeconds(time:utcNow(), 3600), + permissions: {read: true, list: true} +}); +``` + +**Sample response:** + +```ballerina +"sv=2025-05-05&sr=s&sp=rl&se=2026-08-06T10%3A00%3A00Z&sig=nJd7..." +``` + +
+ +
+ +
+generateSas + +
+ +Generates a SAS (Shared Access Signature) token scoped to a single file; the client must hold shared key credentials. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `path` | string | Yes | The share-relative path of the file the SAS grants access to. | +| `values` | FileSasSignatureValues | Yes | What the SAS grants: validity window and permissions, or a stored policy reference. See [FileSasSignatureValues](#filesassignaturevalues). | + +**Returns:** `string|Error` + +**Sample code:** + +```ballerina +string sasToken = check fileShare.generateSas("/2026/q1/report.pdf", { + expiryTime: time:utcAddSeconds(time:utcNow(), 3600), + permissions: {read: true} +}); +``` + +**Sample response:** + +```ballerina +"sv=2025-05-05&sr=f&sp=r&se=2026-08-06T10%3A00%3A00Z&sig=Xk2p..." +``` + +
+ +
+ +
+generateShareUserDelegationSas + +
+ +Generates a user-delegation SAS token scoped to the bound share, signed with an Entra ID user-delegation key instead of the account key. A user-delegation SAS is valid at most 7 days, 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` | ShareSasSignatureValues | Yes | What the SAS grants: validity window and permissions, both required here. See [ShareSasSignatureValues](#sharesassignaturevalues). | +| `key` | UserDelegationKey | Yes | The user-delegation key to sign with, from `AdminClient.getUserDelegationKey`. | + +**Returns:** `string|Error` + +**Sample code:** + +```ballerina +// An Entra ID-authenticated AdminClient mints the delegation key. +files:AdminClient admin = check new (auth = {accountName, tenantId, clientId, clientSecret}); +files:UserDelegationKey key = check admin->getUserDelegationKey( + time:utcNow(), time:utcAddSeconds(time:utcNow(), 86400)); +string sasToken = check fileShare.generateShareUserDelegationSas({ + expiryTime: time:utcAddSeconds(time:utcNow(), 3600), + permissions: {read: true, list: true} +}, key); +``` + +**Sample response:** + +```ballerina +"sv=2025-05-05&sr=s&sp=rl&se=2026-08-06T10%3A00%3A00Z&skoid=3d1e2f3a-...&sig=Qm9r..." +``` + +
+ +
+ +
+generateUserDelegationSas + +
+ +Generates a user-delegation SAS token scoped to a single file, signed with an Entra ID user-delegation key instead of the account key. A user-delegation SAS is valid at most 7 days, 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 share-relative path of the file the SAS grants access to. | +| `values` | FileSasSignatureValues | Yes | What the SAS grants: validity window and permissions, both required here. See [FileSasSignatureValues](#filesassignaturevalues). | +| `key` | UserDelegationKey | Yes | The user-delegation key to sign with, from `AdminClient.getUserDelegationKey`. | + +**Returns:** `string|Error` + +**Sample code:** + +```ballerina +// An Entra ID-authenticated AdminClient mints the delegation key. +files:AdminClient admin = check new (auth = {accountName, tenantId, clientId, clientSecret}); +files:UserDelegationKey key = check admin->getUserDelegationKey( + time:utcNow(), time:utcAddSeconds(time:utcNow(), 86400)); +string sasToken = check fileShare.generateUserDelegationSas("/2026/q1/report.pdf", { + expiryTime: time:utcAddSeconds(time:utcNow(), 3600), + permissions: {read: true} +}, key); +``` + +**Sample response:** + +```ballerina +"sv=2025-05-05&sr=f&sp=r&se=2026-08-06T10%3A00%3A00Z&skoid=3d1e2f3a-...&sig=Ttw4..." +``` + +
+ +
+ +## AdminClient + +Account-level administration: share lifecycle and existence checks, file-service configuration, and account SAS. + +### Configuration + +The `AdminClient` takes the same `ClientConfiguration` as the `Client`; see the [Client configuration](#configuration) tables above. + +Under Microsoft Entra ID credentials, the `AdminClient` operations authorize against the storage account's management permissions (the `Microsoft.Storage/storageAccounts/fileServices/shares/` actions, carried by roles such as Contributor); the Storage File Data Privileged roles alone do not cover them. The one exception is `getUserDelegationKey`, which requires the `Storage File Delegator` role instead. See the [Setup Guide](setup-guide.md) for the role split. + +### Initializing the client + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string accountKey = ?; + +files:AdminClient admin = check new (auth = {accountName, accountKey}); +``` + +### Operations + +#### Share management + +
+hasShare + +
+ +Checks whether a share exists in the storage account. It returns `false` only when Azure confirms the share is absent (a confirmed 404); an `Error` means the check itself failed. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `shareName` | string | Yes | The name of the share to check. | + +**Returns:** `boolean|Error` + +**Sample code:** + +```ballerina +boolean shareExists = check admin->hasShare("reports"); +``` + +**Sample response:** + +```ballerina +true +``` + +
+ +
+ +
+listShares + +
+ +Lists the shares in the storage account, with optional filtering and optional inclusion of metadata, snapshots, and soft-deleted shares. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `options` | ShareListOptions | No | Optional filtering and listing options. See [ShareListOptions](#sharelistoptions). | + +**Returns:** `ShareInfo[]|Error` + +**Sample code:** + +```ballerina +files:ShareInfo[] shares = check admin->listShares({includeMetadata: true}); +``` + +**Sample response:** + +```ballerina +[ + { + name: "reports", + properties: { + quotaInGb: 100, + accessTier: "TransactionOptimized", + eTag: "\"0x8DDA1B2C3D4E5F6\"", + lastModified: [1770307200, 0.0] + }, + metadata: {department: "finance"} + } +] +``` + +
+ +
+ +
+createShare + +
+ +Creates a new share in the storage account. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `shareName` | string | Yes | The name of the share to create. | +| `options` | ShareCreateOptions | No | Optional creation options (quota, tier, protocols, metadata). See [ShareCreateOptions](#sharecreateoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check admin->createShare("reports", {quotaInGb: 100}); +``` + +
+ +
+ +
+deleteShare + +
+ +Deletes a share from the storage account. Under the account's soft-delete retention policy (the default for new accounts) the delete is soft, and the share is restorable with `undeleteShare`. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `shareName` | string | Yes | The name of the share to delete. | +| `options` | ShareDeleteOptions | No | Optional deletion options (snapshot handling, lease id). See [ShareDeleteOptions](#sharedeleteoptions). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check admin->deleteShare("reports-2024"); +``` + +
+ +
+ +
+undeleteShare + +
+ +Restores a soft-deleted share. Find restorable shares and their versions with `listShares({includeDeleted: true})`. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `shareName` | string | Yes | The name of the soft-deleted share to restore. | +| `version` | string | Yes | The version of the soft-deleted share (from `ShareInfo.version`). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check admin->undeleteShare("reports-2024", "01D9E9CE4B0316F0"); +``` + +
+ +
+ +#### Service configuration + +
+getServiceProperties + +
+ +Reads the account's file-service configuration (metrics and CORS rules). + +**Returns:** `ServiceProperties|Error` + +**Sample code:** + +```ballerina +files:ServiceProperties properties = check admin->getServiceProperties(); +``` + +**Sample response:** + +```ballerina +{ + hourMetrics: {enabled: true, version: "1.0", includeApis: true, retentionDays: 7}, + minuteMetrics: {enabled: false}, + cors: [] +} +``` + +
+ +
+ +
+setServiceProperties + +
+ +Updates the account's file-service configuration; the record replaces the whole configuration. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `properties` | ServiceProperties | Yes | The complete file-service configuration to apply. See [ServiceProperties](#serviceproperties). | + +**Returns:** `Error?` + +**Sample code:** + +```ballerina +check admin->setServiceProperties({ + hourMetrics: {enabled: true, includeApis: true, retentionDays: 7} +}); +``` + +
+ +
+ +#### User delegation and account SAS + +`generateAccountSas` is an ordinary method that signs locally without a service call; invoke it with `.` rather than `->`. + +
+getUserDelegationKey + +
+ +Gets a user-delegation key for signing user-delegation SAS tokens; the key is valid at most 7 days. This operation works only on an Entra ID client whose identity holds the `Storage File Delegator` role. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `startTime` | time:Utc | Yes | The start of the key's validity period. | +| `expiryTime` | time:Utc | Yes | The end of the key's validity period (at most 7 days out). | + +**Returns:** `UserDelegationKey|Error` + +**Sample code:** + +```ballerina +files:UserDelegationKey key = check admin->getUserDelegationKey( + time:utcNow(), time:utcAddSeconds(time:utcNow(), 86400)); +``` + +**Sample response:** + +```ballerina +{ + signedObjectId: "3d1e2f3a-4b5c-6d7e-8f9a-0b1c2d3e4f5a", + signedTenantId: "72f988bf-86f1-41af-91ab-2d7cd011db47", + signedStart: [1770307200, 0.0], + signedExpiry: [1770393600, 0.0], + signedService: "f", + signedVersion: "2025-05-05", + value: "aGVsbG8gd29ybGQ=" +} +``` + +
+ +
+ +
+generateAccountSas + +
+ +Generates an account-level SAS (Shared Access Signature) token; the client must hold shared key credentials. + +**Parameters:** + +| Name | Type | Required | Description | +|------|------|----------|-------------| +| `values` | AccountSasSignatureValues | Yes | What the SAS grants: validity window, permissions, and resource types. See [AccountSasSignatureValues](#accountsassignaturevalues). | + +**Returns:** `string|Error` + +**Sample code:** + +```ballerina +string sasToken = check admin.generateAccountSas({ + expiryTime: time:utcAddSeconds(time:utcNow(), 3600), + permissions: {read: true, list: true}, + resourceTypes: {'service: true, container: true, 'object: true} +}); +``` + +**Sample response:** + +```ballerina +"sv=2025-05-05&ss=f&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 + +The standard content headers that can be set on a file. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `contentType` | string | () | The MIME type of the content (e.g. `application/pdf`), served as `Content-Type` on downloads. | +| `contentEncoding` | string | () | Any encoding applied to the stored content (e.g. `gzip`). | +| `contentLanguage` | string | () | The natural language of the content (e.g. `en-US`). | +| `contentDisposition` | string | () | How receivers should present the content (e.g. `attachment` or `inline`). | +| `cacheControl` | string | () | Caching directives served with the file (e.g. `max-age=3600, private`). | +| `contentMd5` | string | () | Base64-encoded MD5 of the content, for integrity verification. | + +### ShareListOptions + +Options for `AdminClient.listShares`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `prefix` | string | () | Return only shares whose name begins with this prefix. | +| `includeMetadata` | boolean | false | Include each share's metadata in the results. | +| `includeSnapshots` | boolean | false | Include share snapshots in the results. | +| `includeDeleted` | boolean | false | Include soft-deleted shares in the results. | + +### ShareCreateOptions + +Options for `AdminClient.createShare`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `metadata` | map<string> | () | User-defined metadata to set on the new share. | +| `quotaInGb` | int | () | The provisioned capacity of the share, in GiB; when absent, the account kind's default quota applies. | +| `accessTier` | ShareAccessTier | () | The access tier for the share; when absent, the account kind's default tier applies (`TRANSACTION_OPTIMIZED` on pay-as-you-go accounts, `PREMIUM` on premium accounts). | +| `enabledProtocols` | ShareProtocol[] | [SMB] | The protocols to enable on the share (SMB and/or NFS). | +| `rootSquash` | NfsRootSquash | () | The NFS root-squash setting (NFS shares only); when absent, NFS shares default to `NO_ROOT_SQUASH`. | + +### ShareDeleteOptions + +Options for `AdminClient.deleteShare`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `deleteSnapshots` | ShareSnapshotsDeleteOption | () | How the share's snapshots are handled; when absent, only the share itself is deleted (the delete fails if snapshots exist). | +| `snapshotId` | string | () | Delete a specific snapshot rather than the share itself. | +| `leaseId` | string | () | The active lease id, required when the share is leased. | + +### DirectoryCreateOptions + +Options for `Client.createDirectory`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `metadata` | map<string> | () | User-defined metadata to set on the new directory. | + +### ListOptions + +Options for `Client.list`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `prefix` | string | () | Return only entries whose name begins with this prefix. | +| `recursive` | boolean | false | List entries in subdirectories as well. | +| `pageSize` | int | 5000 | The number of entries fetched per service round-trip, up to the service maximum of 5,000. Does not cap the total number of results. | +| `includeExtendedInfo` | boolean | false | Include the ETag and timestamps on each entry. | +| `snapshotId` | string | () | List from the share snapshot with this id instead of the live share. | + +### RenameOptions + +Options for `Client.renameFile` and `Client.renameDirectory`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `replaceIfExists` | boolean | false | If a file already occupies the destination path, delete it and give its path to the renamed entry. A directory occupying the destination always fails the operation regardless of this flag. | +| `metadata` | map<string> | () | User-defined metadata to set on the renamed entry (replaces all existing metadata); when absent, the existing metadata is preserved. | + +### CreateOptions + +Options for `Client.createFile` (creating an empty file of a given size). + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `contentHeaders` | ContentHeaders | () | Content headers to set on the file, such as `Content-Type` and `Cache-Control`. | +| `metadata` | map<string> | () | User-defined metadata to set on the file. | + +### UploadOptions + +Options for the upload operations (`uploadFromFile` and `uploadFromStream`; `upload` takes [UploadContentOptions](#uploadcontentoptions)). + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `contentHeaders` | ContentHeaders | () | Content headers to set on the file, such as `Content-Type` and `Cache-Control`. | +| `metadata` | map<string> | () | User-defined metadata to set on the file. | + +### UploadContentOptions + +Options for `upload`: every [UploadOptions](#uploadoptions) field, plus the record serialization format override. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `fileFormat` | FileFormat | () | The serialization format for `json`, record, and record array content: `JSON`, `XML`, or `CSV`. When absent, the format is inferred from the destination path's extension (`.json`, `.xml`, `.csv`). | + +### DownloadOptions + +Options for `download`, included by `getFile`'s `GetFileOptions`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `range` | Range | () | Download only this byte range instead of the whole file. | +| `snapshotId` | string | () | Read from the share snapshot with this id instead of the live share. | + +### GetFileOptions + +Options for `getFile`: every [DownloadOptions](#downloadoptions) field, plus the record binding format override. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `fileFormat` | FileFormat | () | The binding format for `record {}` and `record {}[]` targets: `JSON`, `XML`, or `CSV`. When absent, the format is inferred from the path's extension (`.json`, `.xml`, `.csv`). | + +### CopyOptions + +Options for `Client.copyFile` and `Client.copyFileFromUrl`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `metadata` | map<string> | () | User-defined metadata to set on the destination; when absent, the metadata is copied from the source file. | + +### RangeListOptions + +Options for `Client.listRanges` and `Client.listRangesDiff`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `range` | Range | () | Restrict the listing to this byte range. | + +### ShareSasSignatureValues + +The inputs for generating a share-scoped SAS via `Client.generateShareSas` or `Client.generateShareUserDelegationSas`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `expiryTime` | time:Utc | () | The end of the SAS validity period (UTC). May be omitted only when `identifier` references a stored access policy that carries an expiry. | +| `permissions` | ShareSasPermissions | () | The permissions the SAS grants. May be omitted only when `identifier` references a stored access policy that carries permissions. | +| `startTime` | time:Utc | () | The start of the SAS validity period (UTC); omit for immediately valid. | +| `protocol` | SasProtocol | () | The protocols a request presenting the SAS may use; omit to allow HTTPS and HTTP. | +| `ipRange` | string | () | An IP address or range the requests must come from (e.g. `168.1.5.60-168.1.5.70`). | +| `identifier` | string | () | The identifier of a stored access policy on the share, as an alternative to spelling out expiry and permissions here. Not valid for the user delegation variants, which reject it. | + +Generation fails with an `Error` when neither `identifier` nor both `expiryTime` and `permissions` are supplied. + +### ShareSasPermissions + +The permissions granted by a share-scoped SAS. Every permission is off unless enabled. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `read` | boolean | false | Read file content, properties, and metadata. | +| `create` | boolean | false | Create files and directories. | +| `write` | boolean | false | Write file content, properties, and metadata. | +| `delete` | boolean | false | Delete files and directories. | +| `list` | boolean | false | List files and directories. | + +### FileSasSignatureValues + +The inputs for generating a file-scoped SAS via `Client.generateSas` or `Client.generateUserDelegationSas`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `expiryTime` | time:Utc | () | The end of the SAS validity period (UTC). May be omitted only when `identifier` references a stored access policy that carries an expiry. | +| `permissions` | FileSasPermissions | () | The permissions the SAS grants. May be omitted only when `identifier` references a stored access policy that carries permissions. | +| `startTime` | time:Utc | () | The start of the SAS validity period (UTC); omit for immediately valid. | +| `protocol` | SasProtocol | () | The protocols a request presenting the SAS may use; omit to allow HTTPS and HTTP. | +| `ipRange` | string | () | An IP address or range the requests must come from (e.g. `168.1.5.60-168.1.5.70`). | +| `identifier` | string | () | The identifier of a stored access policy on the share, as an alternative to spelling out expiry and permissions here. Not valid for the user delegation variants, which reject it. | + +Generation fails with an `Error` when neither `identifier` nor both `expiryTime` and `permissions` are supplied. + +### FileSasPermissions + +The permissions granted by a file-scoped SAS. Every permission is off unless enabled. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `read` | boolean | false | Read the file's content, properties, and metadata. | +| `create` | boolean | false | Create the file. | +| `write` | boolean | false | Write the file's content, properties, and metadata. | +| `delete` | boolean | false | Delete the file. | + +### AccountSasSignatureValues + +The inputs for generating an account-level SAS via `AdminClient.generateAccountSas`. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `expiryTime` | time:Utc | Required | The end of the SAS validity period (UTC). | +| `permissions` | AccountSasPermissions | Required | The permissions the SAS grants. | +| `resourceTypes` | AccountSasResourceTypes | Required | The resource types the SAS applies to. | +| `startTime` | time:Utc | () | The start of the SAS validity period (UTC); omit for immediately valid. | +| `protocol` | SasProtocol | () | The protocols a request presenting the SAS may use; omit to allow HTTPS and HTTP. | +| `ipRange` | string | () | 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, and list entries. | +| `write` | boolean | false | Write content, properties, and metadata. | +| `delete` | boolean | false | Delete resources. | +| `list` | boolean | false | List shares and directory contents. | +| `add` | boolean | false | Add content (append-style operations of other storage services). | +| `create` | boolean | false | Create new resources. | +| `update` | boolean | false | Update stored entities (of other storage services). | +| `process` | boolean | false | Process stored messages (of other storage services). | + +### AccountSasResourceTypes + +The resource types an account-level SAS applies to. Every type is off unless enabled. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `'service` | boolean | false | Service-level operations (e.g. list shares, service properties). | +| `container` | boolean | false | Container-level operations (the share level: share properties, metadata). | +| `'object` | boolean | false | Object-level operations (files and directories). | + +### Entry + +One entry returned by `Client.list`. + +| Field | Type | Description | +|-------|------|-------------| +| `path` | string | The share-relative path of the entry, e.g. `/dir1/dir2/file.ext`. | +| `name` | string | The entry name (file or directory), without the directory component. | +| `isDirectory` | boolean | `true` if the entry is a directory, `false` if it is a file. | +| `sizeBytes` | int | The file size in bytes; not present for directories. | +| `id` | string | The entry identifier. | +| `eTag` | string | The entity tag; present only when the listing requests extended info (`ListOptions.includeExtendedInfo`). | +| `lastModified` | time:Utc | The last-modified time (UTC); present only when the listing requests extended info. | + +### ShareProperties + +Properties of a file share, as returned by `Client.getShareProperties` and inside `ShareInfo`. + +| Field | Type | Description | +|-------|------|-------------| +| `quotaInGb` | int | The provisioned capacity of the share, in GiB. | +| `accessTier` | ShareAccessTier | The share's access tier. Shares on premium (FileStorage) accounts always report `PREMIUM`. | +| `eTag` | string | The entity tag for optimistic concurrency. | +| `lastModified` | time:Utc | The last-modified time (UTC). | +| `metadata` | map<string> | User-defined metadata. | +| `enabledProtocols` | ShareProtocol[] | The enabled protocols (SMB and/or NFS). | +| `rootSquash` | NfsRootSquash | The NFS root-squash setting (NFS shares only). | +| `leaseState` | LeaseState | Where the lease stands in its lifecycle; present only while a lease exists. | +| `leaseStatus` | LeaseStatus | `LOCKED` while a lease is in force, `UNLOCKED` otherwise; present only while a lease exists. | +| `leaseDuration` | LeaseDuration | Whether the active lease is infinite or fixed-duration; present only while a lease exists. | +| `provisionedIops` | int | Provisioned IOPS (premium shares only). | +| `provisionedBandwidthMibps` | int | Provisioned bandwidth in MiB/s (premium shares only). | + +### ShareInfo + +One share as returned by `AdminClient.listShares`. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | The share name. | +| `properties` | ShareProperties | The share's properties. | +| `metadata` | map<string> | User-defined metadata, when requested via `ShareListOptions.includeMetadata`. | +| `snapshotId` | string | The snapshot identifier, present only for snapshot listings. | +| `isDeleted` | boolean | `true` when this entry is a soft-deleted share (requires `includeDeleted`). | +| `version` | string | The share version; pass to `AdminClient.undeleteShare` to restore a deleted share. | + +### DirectoryProperties + +Properties of a directory, as returned by `Client.getDirectoryProperties`. + +| Field | Type | Description | +|-------|------|-------------| +| `eTag` | string | The entity tag for optimistic concurrency. | +| `lastModified` | time:Utc | The last-modified time (UTC). | +| `metadata` | map<string> | User-defined metadata. | +| `isServerEncrypted` | boolean | Whether the service has encrypted the directory at rest. | + +### FileProperties + +Properties of a file, as returned by `Client.getFileProperties`. + +| Field | Type | Description | +|-------|------|-------------| +| `eTag` | string | The entity tag for optimistic concurrency. | +| `lastModified` | time:Utc | The last-modified time (UTC). | +| `contentLength` | int | The size of the file in bytes. | +| `contentType` | string | The MIME type of the content, served as `Content-Type` on downloads. `application/octet-stream` when no content type was ever set. | +| `contentEncoding` | string | The encoding applied to the stored content (e.g. `gzip`). | +| `contentDisposition` | string | How receivers should present the content (e.g. `attachment` or `inline`). | +| `cacheControl` | string | Caching directives served with the file (e.g. `max-age=3600, private`). | +| `contentMd5` | string | Base64-encoded MD5 of the content, for integrity verification. | +| `metadata` | map<string> | User-defined metadata. | +| `isServerEncrypted` | boolean | Whether the service has encrypted the file at rest (server-side encryption, covering the file data and its metadata). | +| `leaseState` | LeaseState | Where the lease stands in its lifecycle; present only while a lease exists. | +| `leaseStatus` | LeaseStatus | `LOCKED` while a lease is in force, `UNLOCKED` otherwise; present only while a lease exists. | +| `leaseDuration` | LeaseDuration | Whether the active lease is infinite or fixed-duration; present only while a lease exists. | +| `copyStatus` | CopyStatus | The status of the most recent copy operation, if any. | +| `copyId` | string | The identifier of the most recent copy operation, if any. | +| `copyProgress` | CopyProgress | Progress of the most recent copy operation, if any. | + +### CopyInfo + +The result of starting a copy operation. Copies are asynchronous. + +| Field | Type | Description | +|-------|------|-------------| +| `copyId` | string | The copy operation identifier; pass to `Client.abortCopy` to cancel a pending copy. | +| `copyStatus` | CopyStatus | The copy status at the moment the copy started, `PENDING` while the copy is still in progress. | +| `eTag` | string | The entity tag of the destination after the copy started. | +| `lastModified` | time:Utc | The last-modified time of the destination (UTC). | + +### CopyStatusInfo + +The state of the most recent copy operation that targeted a file, as returned by `Client.checkCopyStatus`. + +| Field | Type | Description | +|-------|------|-------------| +| `copyId` | string | The identifier of the copy operation; pass to `Client.abortCopy` to cancel a pending copy. | +| `copyStatus` | CopyStatus | The status of the copy. | +| `copyProgress` | CopyProgress | Progress of the copy (bytes copied so far out of the total). | + +### CopyProgress + +Progress of an asynchronous copy operation. + +| Field | Type | Description | +|-------|------|-------------| +| `copiedBytes` | int | The number of bytes copied so far. | +| `totalBytes` | int | The total number of bytes to be copied. | + +### Range + +A single byte range within a file. Both bounds are inclusive (a range starting at offset `o` with length `l` is `startByte = o`, `endByte = o + l - 1`). + +| Field | Type | Description | +|-------|------|-------------| +| `startByte` | int | The zero-based inclusive start offset. | +| `endByte` | int | The zero-based inclusive end offset. | + +### RangeDiff + +The result of `Client.listRangesDiff`: how a file's ranges changed since a share snapshot. + +| Field | Type | Description | +|-------|------|-------------| +| `ranges` | Range[] | The ranges written since the baseline snapshot. | +| `clearRanges` | Range[] | The ranges cleared since the baseline snapshot. | + +### ShareSnapshotInfo + +One share snapshot, as returned by `Client.createShareSnapshot` and `Client.listShareSnapshots`. + +| Field | Type | Description | +|-------|------|-------------| +| `snapshotId` | string | The snapshot identifier, an opaque UTC-timestamp-formatted string. Pass it as the `snapshotId` of the download and list options to read from the snapshot. | +| `eTag` | string | The entity tag of the share at the moment of the snapshot. | +| `lastModified` | time:Utc | The last-modified time of the share at the moment of the snapshot (UTC). | + +### ServiceProperties + +The account's file-service configuration: request-metrics collection and cross-origin resource sharing rules. + +| Field | Type | Description | +|-------|------|-------------| +| `hourMetrics` | Metrics | Metrics aggregated per hour. | +| `minuteMetrics` | Metrics | Metrics aggregated per minute. | +| `cors` | CorsRule[] | The CORS (Cross-Origin Resource Sharing) rules, evaluated in order; at most five. | +| `protocol` | ProtocolSettings | Protocol-level settings. | + +### Metrics + +A metrics-collection setting of the file service. + +| Field | Type | Description | +|-------|------|-------------| +| `enabled` | boolean | Whether metrics are collected. | +| `version` | string | The storage-analytics version the setting applies to. | +| `includeApis` | boolean | Whether metrics cover called API operations as well as storage capacity. | +| `retentionDays` | int | How many days collected metrics are retained. | + +### CorsRule + +One CORS (Cross-Origin Resource Sharing) rule of the file service. The string fields are comma-separated lists; `*` allows all. + +| Field | Type | Description | +|-------|------|-------------| +| `allowedOrigins` | string | The origin domains allowed to make requests. | +| `allowedMethods` | string | The HTTP methods an allowed origin may use. | +| `allowedHeaders` | string | The request headers an allowed origin may send. | +| `exposedHeaders` | string | The response headers exposed to the browser. | +| `maxAgeInSeconds` | int | How long, in seconds, a browser may cache the preflight response. | + +### ProtocolSettings + +Protocol-level settings of the file service. + +| Field | Type | Description | +|-------|------|-------------| +| `smbMultichannelEnabled` | boolean | Whether SMB multichannel (multiple parallel network channels per SMB session) is enabled for the account. | + +### UserDelegationKey + +A key for signing user-delegation SAS tokens, obtained via `AdminClient.getUserDelegationKey`. + +| Field | Type | Description | +|-------|------|-------------| +| `signedObjectId` | string | The object id of the Entra ID principal the key was issued to. | +| `signedTenantId` | string | The Entra ID tenant the key was issued in. | +| `signedStart` | time:Utc | The start of the key's validity period (UTC). | +| `signedExpiry` | time:Utc | The end of the key's validity period (UTC). | +| `signedService` | string | The service the key is valid for. | +| `signedVersion` | string | The storage service version the key was issued for. | +| `value` | string | The key itself, base64-encoded. | + +### Enums + +- `ShareAccessTier`: `HOT`, `COOL`, `TRANSACTION_OPTIMIZED`, `PREMIUM`. +- `ShareProtocol`: `SMB`, `NFS`. +- `FileFormat`: `JSON`, `XML`, `CSV`. +- `ShareSnapshotsDeleteOption`: `INCLUDE`, `INCLUDE_LEASED`. +- `NfsRootSquash`: `NO_ROOT_SQUASH`, `ROOT_SQUASH`, `ALL_SQUASH`. +- `CopyStatus`: `PENDING`, `SUCCESS`, `ABORTED`, `FAILED`. +- `LeaseState`: `AVAILABLE`, `LEASED`, `EXPIRED`, `BREAKING`, `BROKEN`. +- `LeaseStatus`: `LOCKED`, `UNLOCKED`. +- `LeaseDuration`: `INFINITE`, `FIXED`. +- `SasProtocol`: `HTTPS`, `HTTPS_HTTP`. +- `RetryPolicyType`: `EXPONENTIAL`, `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). It carries no detail fields, with one exception: + - **`ContentBindingError`**: a listener-only error raised when a dispatched file's content does not bind to its handler's declared type. It is delivered to the service's `onError` handler and carries the file's share-relative path in `filePath` and, when the content had been downloaded before binding failed, its raw bytes in `content`. See the [Trigger Reference](trigger-reference.md#contentbindingerror). +- **`ServiceError`**: any error the Azure service raised, always carrying `httpStatus` and `errorCode`. Its subtypes are `NotFoundError` (404), `ConflictError` (409), `AuthorizationError` (403), `PreconditionFailedError` (412), `RangeNotSatisfiableError` (416), and `QuotaExceededError` (403, the share is full). 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 `ShareSizeLimitReached` (403) becomes a `QuotaExceededError` while an auth failure (also 403) becomes an `AuthorizationError`. Check the more specific error types before the general ones. diff --git a/en/docs/connectors/catalog/storage-file/azure.storage.files/example.md b/en/docs/connectors/catalog/storage-file/azure.storage.files/example.md new file mode 100644 index 00000000000..2f62eb09c0d --- /dev/null +++ b/en/docs/connectors/catalog/storage-file/azure.storage.files/example.md @@ -0,0 +1,266 @@ +# Example + +## Azure Files example + +### What you'll build + +Build a WSO2 Integrator automation that connects to an Azure file share, uploads a local report with the `uploadFromFile` operation, and confirms the upload with the `hasFile` operation. The workflow uses configurable variables to manage the Azure credentials securely. + +**Operations used:** +- **uploadFromFile** : Uploads a local file to a path on the share. +- **hasFile** : Checks whether a file exists at a share path. + +### Architecture + +```mermaid +flowchart LR + A((User)) --> B[main Automation] + B --> C[uploadFromFile Operation] + C <--> D[(Azure Files share)] + B --> E[hasFile Operation] + E <--> D + E --> F[log:printInfo] +``` + +### Prerequisites + +- An Azure storage account with a file share (see the [Setup Guide](setup-guide.md)) +- The storage account name and an access key + +### Setting up the integration + +> **New to WSO2 Integrator?** Follow the [Create a New Integration](../../../../develop/create-integrations/create-a-new-integration.md) guide to set up your integration first, then return here to add the connector. + +#### Step 1: Add an Automation entry point + +A new integration starts with no artifacts, so the sidebar stays empty and connections cannot be added yet. Create the entry point first: + +1. Select **+ Add Artifact** on the canvas toolbar. +2. Under **Automation**, select the **Automation** tile. +3. Select **Create Integration**. No additional configuration is needed. + +An **Automation** entry point appears in the sidebar under **Entry Points**, and the design view shows the automation node. Selecting the node opens the automation flow editor with a **Start** node. + +### Creating the configurable variables + +The connection form references configurable variables for the share name and credentials, so create the variables first. + +#### Step 2: Create configurable variables + +1. In the sidebar, select **Configurations** to open the **Configurable Variables** view. +2. Select **+ Add Config**, enter the **Variable Name**, keep the **Variable Type** as `string`, leave **Default Value** empty, and select **Save**. Repeat for each variable listed below. + +- **accountName** (string) : The Azure storage account name +- **accountKey** (string) : An access key of the storage account +- **shareName** (string) : The name of the file share to bind the client to + +![Add Configurable Variable panel with the accountName variable](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_01_configurables_panel.png) + +### Adding the Azure Files connector + +Select **Add Connection** in the WSO2 Integrator sidebar to open the connector palette. + +#### Step 3: Open the connector palette and select the Files connector + +1. In the WSO2 Integrator sidebar, expand **Connections** and select the **+** button next to it. +2. In the connector palette search box, enter `azure.storage.files`. +3. The palette lists three cards under `ballerinax / azure.storage.files`: **Files** (the share client this example uses), **Files Admin** (the account-level `AdminClient`), and **Files Caller** (passed to trigger handlers, not used as a connection). Select the **Files** card. + +![Connector palette with the azure.storage.files search results](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_02_palette.png) + +### Configuring the Azure Files connection + +#### Step 4: Bind connection parameters to the configurable variables + +Selecting the **Files** card opens the **Configure Files** form. Switch **Share Name** to **Expression** and enter `shareName`, switch **Auth** to **Expression** and enter `{accountName, accountKey}`, and set **Connection Name** to `azFilesClient`. + +![Azure Files connection form with all parameters set](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_03_connection_form.png) + +#### Step 5: Save the connection + +Select **Save Connection** to persist the connection. The form closes and `azFilesClient` appears in the sidebar under **Connections**. + +#### Step 6: Set actual values for your configurables + +1. In the left panel, select **Configurations**. +2. Set a value for each configurable listed below. + +- **accountName** (string) : Your storage account name, from the [Setup Guide](setup-guide.md) +- **accountKey** (string) : An access key of the storage account +- **shareName** (string) : The file share to work with (for example, `reports`) + +### Configuring the uploadFromFile operation + +#### Step 7: Select the uploadFromFile operation and configure its parameters + +1. In the sidebar under **Entry Points**, select **Automation** to open its flow editor (selecting the automation node in the design view works too). +2. Select the **+** button on the canvas between **Start** and **Error Handler**. +3. In the right-side node panel, expand **Connections → azFilesClient**. + +![Azure Files operations panel](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_04_operations_panel.png) + +4. Select **Upload From File** and fill in the operation form: + +- **Source Path** : The local file to upload (for example, `./data/q1-report.pdf`) +- **Destination Path** : The full share path to upload to, including the file name (for example, `/reports/q1-report.pdf`) + +5. Select **Save**. + +![uploadFromFile operation configuration](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_05_uploadfile_form.png) + +#### Step 8: Confirm the upload and log the result + +1. Select the **+** below the **Upload From File** node and add the **Has File** operation from **Connections → azFilesClient**. Set **Path** to the destination path from Step 7 (`/reports/q1-report.pdf`) and name the result variable `uploaded` (its type is fixed to `boolean`). +2. Add a **Log Info** statement below it with the expression ``string `${uploaded}` `` (the message must be a string, so the boolean is interpolated). + +`hasFile` returns `true` once the file is present on the share, so the log output confirms the upload. + +![Completed Azure Files automation flow](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_06_completed_flow.png) + +### Try it yourself + +Try this sample in WSO2 Integration Platform. + +[![Deploy to Devant](https://openindevant.choreoapps.dev/images/DeployDevant-White.svg)](https://console.devant.dev/new?gh=wso2/integration-samples/tree/main/integrator-default-profile/connectors/azure.storage.files_connector_sample) + +[View source on GitHub](https://github.com/wso2/integration-samples/tree/main/integrator-default-profile/connectors/azure.storage.files_connector_sample) + +--- + +## Azure Files trigger example + +### What you'll build + +This integration watches a drop folder on an Azure file share and processes each JSON file dropped into it. When a `.json` file arrives on the watched path, the `onFileJson` handler fires with the parsed content and logs it, and the listener deletes the file after successful processing; a file that fails to parse moves to a `/failed` directory instead. + +### Architecture + +```mermaid +flowchart LR + A((Producer app)) --> B[(Azure Files share)] + B --> C[[Azure Files Trigger Listener]] + C --> D[Handler: onFileJson] + D --> E[log:printInfo] +``` + +### Prerequisites + +- An Azure storage account with a file share containing an `/incoming` directory (see the [Setup Guide](setup-guide.md)) +- The storage account name and an access key + +### Setting up the integration + +> **New to WSO2 Integrator?** Follow the [Create a New Integration](../../../../develop/create-integrations/create-a-new-integration.md) guide to set up your integration first, then return here to add the trigger. + +### Configuring the Azure Files listener + +#### Step 1: Create configurable variables + +In the left panel, select **Configurations**. In the Configurable Variables panel, select **+ Add Config** and create each configuration listed below. If you completed the client example in the same project, these variables already exist; reuse them and skip this step. + +- **accountName** (string) : The Azure storage account name +- **accountKey** (string) : An access key of the storage account +- **shareName** (string) : The file share to watch + +![Add Configurable Variable panel with the accountName variable](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_01_configurables_panel.png) + +### Adding the Azure Files trigger + +#### Step 2: Select the Azure Files integration type + +1. Select the **+** button in the WSO2 Integrator side panel header to open the **New Integration** wizard (on an empty project, the **+ Add Integration or Library** button in the project view opens the same wizard), and continue to the **Type** step. +2. Scroll to the **File Integration** category, select the **Azure Files** card, and select **Next**. + +![New Integration wizard with the Azure Files card selected](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_01_new_integration_wizard.png) + +#### Step 3: Configure the listener + +The **Azure Files Integration** page opens with the **Listener Configurations** form (the trigger polls through a listener). Fill it referencing the configurables: + +- **Listener Name** : `azFilesListener` +- **Share Name** : Switch to **Expression** and enter `shareName` +- **Select the authentication method** : **Shared Key** +- **Account Name** : Switch to **Expression** and enter `accountName` +- **Account Key** : Switch to **Expression** and enter `accountKey` +- **Monitoring Path** : `/incoming`. This is the watched path the service attaches to; `/` watches the share root. + +![Azure Files listener configuration form](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_02_listener_config_form.png) + +#### Step 4: Create the trigger + +Select **Create** to generate the listener and the service. A `files:Service` entry appears in the sidebar under **Entry Points**. + +The listener polls every 60 seconds by default. To make the example respond faster, select `azFilesListener` under **Listeners** and set **Polling Interval** to a smaller value, for example `5`. + +### Setting configuration values + +#### Step 5: Set actual values for your configurations + +In the left panel, select **Configurations** again, and set a value for each configuration created above: + +- **accountName** (string) : Your storage account name +- **accountKey** (string) : An access key of the storage account +- **shareName** (string) : The file share to watch + +### Handling file events + +#### Step 6: Add a file handler + +Return to the integration service view (select **files:Service** under **Entry Points**) and select **+ Add Handler**. The handler picker offers **On Create**, which fires for files appearing on the monitoring path; select it. The handler's **Format** setting then selects how the content is delivered: **JSON**, **XML**, **CSV**, **Text**, or **Raw Bytes**, generating the `onFileJson`, `onFileXml`, `onFileCsv`, `onFileText`, or `onFile` callback respectively. An `onError` handler for poll, read, and content-binding failures can be added in code; see the [Trigger Reference](trigger-reference.md). Note that declaring one moves the disposal of content-binding failures onto `onError`'s own `@files:FunctionConfig`, so the **On Error** action configured here would no longer apply to them. + +![Handler picker with the On Create handler](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_03_add_handler_panel.png) + +#### Step 7: Configure the JSON handler + +In the **New On Create Configuration** panel, set: + +- **Format** : **JSON**, so the handler receives the parsed content +- **After File Processing → On Success** : **Delete**, so a processed file is removed from the drop folder +- **After File Processing → On Error** : **Move** with **Move To** `/failed`, so a file that cannot be parsed leaves the watched path instead of firing again on every poll. (This service declares no `onError` handler, so the binding failure is disposed of by this action.) + +These options generate the `onFileJson` handler carrying the `@files:FunctionConfig` annotation's `afterProcess` and `afterError` actions. See the [Trigger Reference](trigger-reference.md) for the full annotation surface. + +![On Create handler configuration with the JSON format and post-processing actions](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_04_handler_config.png) + +Select **Save** to register the `onFileJson` handler on the service. + +#### Step 8: Add a log statement to the handler + +After the handler is saved, WSO2 Integrator opens the handler's flow canvas. The handler receives the parsed file content as an input named `content` of type `json`. + +1. Select the **+** inside the handler flow and choose **Log Info** from the **Logging** section in the side panel. +2. In the expression editor, select `content` from the **Inputs** list, then append `.toJsonString()`. + +![onFileJson handler flow with the log statement](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_05_handler_flow.png) + +#### Step 9: Verify the final service view + +Navigate back to the integration service view. The handler section now displays the registered `onFileJson` handler. + +![Final service view with the registered onFileJson handler](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_06_service_view_final.png) + +### Running the integration + +Select **Run Integration** in the WSO2 Integrator toolbar to start the integration. To fire a test event, drop a `.json` file into the watched directory: + +1. In the [Azure portal](https://portal.azure.com/), open your storage account and navigate to **Data storage** > **File shares**. +2. Open the share, browse into the `incoming` directory, and select **Upload** to add a small `.json` file. + +On the next poll (every 60 seconds by default, or the interval you set on the listener), the `onFileJson` handler fires and logs the parsed content to the console, and the listener deletes the file from the drop folder. A malformed `.json` file moves to `/failed` instead, because this service declares no `onError` handler. + +### Try it yourself + +Try this sample in WSO2 Integration Platform. + +[![Deploy to Devant](https://openindevant.choreoapps.dev/images/DeployDevant-White.svg)](https://console.devant.dev/new?gh=wso2/integration-samples/tree/main/integrator-default-profile/connectors/azure.storage.files_trigger_sample) + +[View source on GitHub](https://github.com/wso2/integration-samples/tree/main/integrator-default-profile/connectors/azure.storage.files_trigger_sample) + +## More code examples + +The Azure Files connector provides practical examples illustrating usage in various scenarios. Explore these [examples](https://github.com/ballerina-platform/module-ballerinax-azure.storage.files/tree/main/examples), covering file backup, SAS handouts, and share-driven file processing. + +1. [File backup](https://github.com/ballerina-platform/module-ballerinax-azure.storage.files/tree/main/examples/file-backup) - Continuously back up a local folder: a directory listener watches it and uploads every new file to a file share. +2. [Share handout](https://github.com/ballerina-platform/module-ballerinax-azure.storage.files/tree/main/examples/share-handout) - Upload a report and generate a time-limited, read-only SAS URL to share with a third party. +3. [Drop folder processor](https://github.com/ballerina-platform/module-ballerinax-azure.storage.files/tree/main/examples/drop-folder-processor) - Watch a folder on a share with the listener and process each dropped file. +4. [Change tracker](https://github.com/ballerina-platform/module-ballerinax-azure.storage.files/tree/main/examples/change-tracker) - A schedulable program that diffs a share against the snapshot saved by its previous run and logs created, modified, and deleted events. diff --git a/en/docs/connectors/catalog/storage-file/azure.storage.files/overview.md b/en/docs/connectors/catalog/storage-file/azure.storage.files/overview.md new file mode 100644 index 00000000000..83aabf5ecf3 --- /dev/null +++ b/en/docs/connectors/catalog/storage-file/azure.storage.files/overview.md @@ -0,0 +1,63 @@ +--- +connector: true +connector_name: "azure.storage.files" +title: "Azure Files" +description: "Overview of the ballerinax/azure.storage.files connector for WSO2 Integrator." +--- + +[Azure Files](https://learn.microsoft.com/en-us/azure/storage/files/storage-files-introduction) offers fully managed file shares in the cloud, accessible via the industry-standard SMB and NFS protocols and a REST API. The `ballerinax/azure.storage.files` connector (v1.0.0) connects WSO2 Integrator to Microsoft Azure Files, managing shares and the directories and files within them: uploads, downloads, copies, renames, byte ranges, snapshots, and SAS token generation. A polling `Listener` turns files arriving on a share into service events. + +## Key features + +- Share-scoped `Client` for directory and file operations, transfers, copies, and byte ranges +- Account-level `AdminClient` for creating, listing, deleting, and restoring shares +- Polling `Listener` that routes files arriving on a watched path to raw, typed, or streaming content handlers, with an optional `onError` error handler +- Share snapshots +- Authentication with shared key, SAS tokens, connection strings, and Microsoft Entra ID +- GraalVM compatible for native image builds + +## Actions + +Actions are operations you invoke on Azure Files from your integration: uploading and downloading files, managing directories and shares, copying, generating SAS tokens, and more. The connector exposes actions through two clients. + +| Client | Actions | +|--------|---------| +| `Client` | Directory, file, transfer, copy, range, snapshot, and SAS operations within one share | +| `AdminClient` | Account-level share management and file-service configuration | + +See the **[Action Reference](action-reference.md)** for the full list of operations, parameters, and sample code for each client. + +## Triggers + +Triggers let your integration react to files arriving on a file share. The connector uses a polling `Listener` that periodically scans a watched path on a share and routes each file present there to the matching content handler of your service. + +| Event | Callback | Description | +|-------|----------|-------------| +| Any file without a dedicated typed handler | `onFile` | Receives the raw file content | +| Text file (`.txt`) | `onFileText` | Receives the content as a string | +| JSON file (`.json`) | `onFileJson` | Receives the parsed JSON content | +| XML file (`.xml`) | `onFileXml` | Receives the parsed XML content | +| CSV file (`.csv`) | `onFileCsv` | Receives the parsed rows | +| Listener error | `onError` | Receives poll failures, content-read failures, and content-binding failures | + +See the **[Trigger Reference](trigger-reference.md)** for listener configuration, the service model, and callback signatures. + +## Documentation + +* **[Setup Guide](setup-guide.md)**: How to create a storage account and file share, and obtain credentials. + +* **[Action Reference](action-reference.md)**: Full reference for both clients: operations, parameters, return types, and sample code. + +* **[Trigger Reference](trigger-reference.md)**: Reference for event-driven integration using the listener and service model. + +* **[Example](example.md)**: Learn how to build and configure an integration using the **Azure Files** connector, including connection setup, operation configuration, execution flow, and event-driven trigger setup. + +## How to contribute + +As an open source project, WSO2 welcomes contributions from the community. + +To contribute to the code for this module, please create a pull request in the following repository. + +* [Azure Files Module GitHub repository](https://github.com/ballerina-platform/module-ballerinax-azure.storage.files) + +Check the issue tracker for open issues that interest you. We look forward to receiving your contributions. diff --git a/en/docs/connectors/catalog/storage-file/azure.storage.files/setup-guide.md b/en/docs/connectors/catalog/storage-file/azure.storage.files/setup-guide.md new file mode 100644 index 00000000000..c4860e86e33 --- /dev/null +++ b/en/docs/connectors/catalog/storage-file/azure.storage.files/setup-guide.md @@ -0,0 +1,70 @@ +--- +connector: true +connector_name: "azure.storage.files" +title: "Setup Guide" +description: "How to set up and configure the ballerinax/azure.storage.files connector." +--- + +# Setup Guide + +This guide walks you through preparing an Azure storage account and obtaining the credentials the `ballerinax/azure.storage.files` connector needs to authenticate with Azure Files. + +## Prerequisites + +- An Azure subscription. If you do not have one, [sign up for a free Azure account](https://azure.microsoft.com/free/). + +## Create a storage account + +1. Sign in to the [Azure portal](https://portal.azure.com/), search for **Storage accounts**, and open it. +2. Select **+ Create**. +3. On the **Basics** tab, select a subscription and resource group, provide a globally unique storage account name, and pick a region. The **Standard** performance tier is sufficient for SMB file shares; choose **Premium** with the **File shares** account type only if you need provisioned performance or NFS. +4. Select **Review + create**, then **Create**, and wait for the deployment to complete. For the full set of options, see the [Azure documentation](https://learn.microsoft.com/en-us/azure/storage/common/storage-account-create). + +## Create a file share + +1. Open the deployed storage account and navigate to **Data storage** > **File shares**. +2. Select **+ File share**, provide a name, and select **Create**. The share name is what you pass to the connector at initialization. For details, see the [Azure Files documentation](https://learn.microsoft.com/en-us/azure/storage/files/storage-how-to-create-file-share). + +## Obtain credentials + +The connector accepts any one of the following credential types. An access key is the most capable credential: share-level administrative operations and key-based SAS token generation require it. (User delegation SAS is the exception; it requires a Microsoft Entra ID identity instead, as described below.) + +### Access keys + +1. In the storage account, navigate to **Security + networking** > **Access keys**. +2. Select **Show** next to **key1**, then copy the storage account name and the key value. These two values are the account name and account key the connector's shared key authentication uses. + +### SAS token or SAS URL + +1. In the storage account, navigate to **Security + networking** > **Shared access signature**. +2. Select the allowed services, resource types, permissions, and an expiry window, then select **Generate SAS and connection string**. +3. Copy the **SAS token**, or the **File service SAS URL** if you prefer a single value that carries both the endpoint and the token. + +A SAS credential is limited to the services, resource types, permissions, and expiry it was minted with. The portal's **Shared access signature** page mints an account SAS; minted with the File service and the container resource type, it can also perform share-level administrative operations. A share- or file-scoped SAS cannot. No SAS credential can mint further SAS tokens. + +### Connection string + +The portal shows a connection string alongside each access key under **Security + networking** > **Access keys**. Select **Show** next to the **Connection string** field and copy the value. It carries the account name, the credential, and the service endpoints in one string. + +### Microsoft Entra ID + +The connector can authenticate as a Microsoft Entra ID identity: a service principal (via a client secret or certificate), a managed identity, a federated workload identity, or the default credential chain of the environment it runs in. + +To use a service principal: + +1. In the Azure portal, open **Microsoft Entra ID** > **App registrations** and select **+ New registration**. After registering, note the **Directory (tenant) ID** and **Application (client) ID** from the app's overview page. +2. Under the app's **Certificates & secrets**, create a client secret (or upload a certificate) and copy its value. + +The role requirements apply regardless of which Entra ID credential kind you use, and they split by operation family: + +- For file and directory data operations, the identity must hold the **Storage File Data Privileged Reader** or **Storage File Data Privileged Contributor** role on the storage account. The connector sends the backup intent on every request; this requires the privileged roles and bypasses file and directory ACLs. +- Share-level and account-level management operations (the admin operations, and the operations on the share itself) authorize against the storage account's management permissions instead: the identity needs a role carrying the `Microsoft.Storage/storageAccounts/fileServices/shares/` read, write, and delete actions, such as **Contributor** on the storage account. The privileged data roles alone do not cover these operations. +- Generating user delegation SAS tokens additionally requires the **Storage File Delegator** role. + +An identity covering the full connector surface holds a privileged data role and a management role together. Assign the roles in the storage account under **Access control (IAM)** > **Add** > **Add role assignment**. + +## Next steps + +- [Actions](action-reference.md): the operations available on the connector's clients. +- [Triggers](trigger-reference.md): event-driven integration with the polling listener. +- [Example](example.md): step-by-step walkthroughs using the credentials from this guide. diff --git a/en/docs/connectors/catalog/storage-file/azure.storage.files/trigger-reference.md b/en/docs/connectors/catalog/storage-file/azure.storage.files/trigger-reference.md new file mode 100644 index 00000000000..99b59051e97 --- /dev/null +++ b/en/docs/connectors/catalog/storage-file/azure.storage.files/trigger-reference.md @@ -0,0 +1,235 @@ +--- +connector: true +connector_name: "azure.storage.files" +--- + +# Triggers + +The `ballerinax/azure.storage.files` connector supports event-driven file processing through a polling listener. The `files:Listener` periodically scans one watched path on an Azure file share and routes each file present there to the matching content handler of your service, delivering the content in the format you choose (bytes, text, JSON, XML, or CSV). + +The connector exposes several components: + +| Component | Role | +|-----------|------| +| `files:Listener` | Polls one watched path on a share at a fixed interval. | +| `files:Service` | Hosts the content handlers invoked for each dispatched file; the service's attach point is the watched path. | +| `files:Caller` | A client passed to handlers, enabling additional file operations (download, upload, move, delete) within the handler. | +| `files:FileInfo` | Metadata record describing the dispatched file, such as share name, path, name, size, and last-modified time. | + +For action-based operations, see the [Action Reference](action-reference.md). + +--- + +## Listener + +The `files:Listener` holds the connection credentials and the polling schedule. It is bound to one share at initialization; the path to watch belongs to the service, not the listener. + +### Configuration + +| Config Type | Description | +|-------------|-------------| +| `ListenerConfiguration` | Configuration for the Azure Files listener, including authentication, polling cadence, data-binding behavior, and transport settings. | + +**`ListenerConfiguration` fields:** + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `auth` | AuthConfig | Required | The authentication configuration. Accepts any credential from the auth union; see the [Action Reference](action-reference.md#configuration) for the credential records. | +| `pollingInterval` | decimal | 60 | Interval in seconds between polls of the watched path. Must be greater than zero; the listener fails to initialize otherwise. | +| `retryConfig` | RetryConfig | () | Retry behavior for service requests; omit for the service defaults. | +| `transportConfig` | TransportConfig | () | HTTP transport settings (proxy, connection pool, TLS); omit for the defaults. | +| `laxDataBinding` | boolean | false | Relaxed data binding for the typed content handlers: JSON, XML, and CSV record binding treat a null value as an optional field and an absent field as a nilable field. | + +### Initializing the listener + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string accountKey = ?; +configurable string shareName = ?; + +listener files:Listener dropListener = new (shareName, + auth = {accountName, accountKey}, + pollingInterval = 5 +); +``` + +--- + +## Service + +A `files:Service` is a Ballerina service attached to a `files:Listener`. The service's attach point is the watched path. A service declared as `service /invoices on dropListener` watches the `/invoices` directory of the share; the string form `service "/dir one/reports" on dropListener` covers names a resource path cannot express; a service with no attach point watches the share root. One listener accepts exactly one service; to watch several paths, run several listeners. + +The optional `@files:ServiceConfig` annotation configures recursion, file-name filtering, and a minimum file age (see [Supporting types](#supporting-types)). It does not carry a path. + +Files are routed to handlers by file extension: `.txt` to `onFileText`, `.json` to `onFileJson`, `.xml` to `onFileXml`, and `.csv` to `onFileCsv`. A per-handler `@files:FunctionConfig` with a `fileNamePattern` overrides extension routing. A file whose extension maps to a handler the service does not declare falls back to `onFile`; if `onFile` is also absent, the file is skipped and logged. At most one handler runs per file. + +Delivery is at-least-once: the listener keeps no per-file state, so a file that stays on the watched path fires again on every poll. Handlers consume files by deleting or moving them out of the watched path, either through the `Caller` or with the `@files:FunctionConfig` auto-consume actions. One file is never dispatched twice at once; at most one invocation runs per path at a time, even across an overwrite. A file overwritten while its handler is still running is picked up on a later poll, once the in-flight invocation finishes. For exactly-once effects, make handlers idempotent or claim each file by renaming it out of the watched path before processing. A file that is listed but cannot be read is also left in place and retried on the next poll, notifying `onError` each time. + +:::note +The `byte[]` form of `onFile` loads the whole file into memory; prefer the stream form or a narrower watch for large files. Each poll with `recursive: true` issues a full recursive listing and downloads every dispatched file, so at scale, widen `pollingInterval`, narrow the watched path, or add a `fileNamePattern`. A file still being written over SMB or NFS can be picked up mid-write; set `minFileAgeSeconds` to guard against partial writes. +::: + +### Callback signatures + +| Function | Signature | Description | +|----------|-----------|-------------| +| `onFile` | remote function onFile(byte[] content, files:FileInfo file, files:Caller caller) returns error? | Invoked for a dispatched file, delivering the raw content. Also accepts the content as stream<byte[], error?> for streaming large files. | +| `onFileText` | remote function onFileText(string content, files:FileInfo file, files:Caller caller) returns error? | Invoked for a dispatched `.txt` file, delivering the content as a string. | +| `onFileJson` | remote function onFileJson(json content, files:FileInfo file, files:Caller caller) returns error? | Invoked for a dispatched `.json` file, delivering the parsed content. Also binds to a user-defined record. | +| `onFileXml` | remote function onFileXml(xml content, files:FileInfo file, files:Caller caller) returns error? | Invoked for a dispatched `.xml` file, delivering the document. Also binds to a user-defined record. | +| `onFileCsv` | remote function onFileCsv(MyRow[] content, files:FileInfo file, files:Caller caller) returns error? | Invoked for a dispatched `.csv` file, delivering the rows bound to a record array. Also binds to a stream of records. | +| `onError` | remote function onError(files:Error err, files:Caller caller) returns error? | Invoked when a poll fails, when a listed file's content cannot be read, or when a file's content cannot be bound to the typed parameter of a content handler. Declaring it also makes it responsible for consuming files that fail to bind; see [Error handling](#error-handling). | + +:::note +The trailing parameters are optional. A content handler declares its content parameter first, then either, both, or neither of `FileInfo` and `Caller`, so the accepted shapes are `(content)`, `(content, FileInfo)`, `(content, Caller)`, and `(content, FileInfo, Caller)`; when both are present, `FileInfo` must precede `Caller`. `onError` accepts `(error)` or `(error, Caller)`. Its first parameter must be declared as `error` or `files:Error`; a narrower subtype such as `files:ContentBindingError` is rejected at compile time, because `onError` has to be able to receive poll, read, and binding failures alike. +::: + +:::note +Each content parameter is declared with exactly one of its accepted types. `onFile` takes `byte[]` or `stream`. `onFileJson` takes a `json` value or a record. `onFileXml` takes `xml` or a record. `onFileCsv` takes a record array or a stream of records; both map each row's fields through the file's first row, the header. +::: + +### Full usage example + +```ballerina +import ballerina/log; + +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string accountKey = ?; +configurable string shareName = ?; + +// The shape a dropped .json file binds to. +type Person record {| + string name; + int age; +|}; + +listener files:Listener dropListener = new (shareName, + auth = {accountName, accountKey}, + pollingInterval = 5 +); + +// The attach point is the watched path: this service watches "/incoming". +service /incoming on dropListener { + + // A .json file binds to Person and is deleted once processed. + @files:FunctionConfig {afterProcess: files:DELETE} + remote function onFileJson(Person person, files:FileInfo file, files:Caller caller) returns error? { + log:printInfo("processed JSON drop", fileName = file.name, personName = person.name); + } + + // Every other file arrives as raw bytes and moves to /processed afterwards. + @files:FunctionConfig {afterProcess: {moveTo: "/processed"}} + remote function onFile(byte[] content, files:FileInfo file, files:Caller caller) returns error? { + log:printInfo("processed file drop", fileName = file.name, sizeBytes = content.length()); + } + + // Notified on poll failures, read failures, and content-binding failures. Because onError + // is declared, it owns the fate of a .json drop that fails to bind: this annotation moves + // it to /failed so it stops re-firing. + @files:FunctionConfig {afterProcess: {moveTo: "/failed"}} + remote function onError(files:Error err) returns error? { + log:printError("drop-folder listener reported an error", 'error = err); + } +} +``` + +:::note +`@files:FunctionConfig`'s `afterProcess` and `afterError` auto-consume a file after its handler runs: `files:DELETE` deletes it, and a `Move` record (`{moveTo: "/processed"}`) moves it. `afterProcess` runs when the handler returns normally, and `afterError` when the handler returns an error. `afterError` also covers a typed handler's content-binding failures, but only when the service declares no `onError`; with `onError` declared, binding failures are consumed by `onError`'s own annotation instead. Without a matching action, the file stays on the watched path and fires again on the next poll. +::: + +A step-by-step walkthrough of building this integration in the WSO2 Integrator IDE is in the [Example](example.md) page. + +### Error handling + +A service may declare an `onError` handler. It is notified on every listener-side failure: + +- A failed poll, with the mapped typed error, for example an `AuthorizationError` when the credential lacks access to the watched path. +- A failed content read, also with the mapped typed error: the file was listed, but its content could not be downloaded for dispatch. The file stays on the watched path, so the notification repeats while the read keeps failing. +- A typed handler's content-binding failure, with a [`ContentBindingError`](#contentbindingerror) whose detail names the file. + +A malformed file routed to a typed handler is a content-binding error; it never falls through to `onFile`. Errors a content handler itself returns do not notify `onError`, and neither does a CSV row that fails to bind lazily while a handler drains a record stream: that error belongs to the handler doing the draining. `onError` is not a content handler, so it does not satisfy the service's at-least-one-handler requirement. + +Declaring `onError` hands it ownership of binding failures. The content handler's `afterError` no longer applies to a binding failure; the file's fate follows `onError`'s own `@files:FunctionConfig` instead, with `afterProcess` when `onError` returns normally and `afterError` when it returns an error or panics. An error returned by `onError` is never propagated, but it is not inert either: it is printed, and it selects `afterError`. + +:::warning +An `onError` with no `@files:FunctionConfig` leaves the file on the watched path, so the same malformed file is redelivered on every poll. Give `onError` an `afterProcess` action whenever the service relies on automatic consumption of files that fail to bind. +::: + +The consume actions on `onError` cover binding failures only. A file whose content could not be read is always left for the next poll, whatever `onError` returns, so a transient read failure never discards content. A `fileNamePattern` in `onError`'s annotation is ignored, because `onError` is never routed a file. + +A credential that cannot list the watched path does not fail at attach time; the first poll surfaces the `AuthorizationError`. Polling keeps its configured interval after a failure, so the next scheduled poll scans again. + +--- + +## Supporting types + +### `FileInfo` + +| Field | Type | Description | +|-------|------|-------------| +| `shareName` | string | The name of the share the file lives on. | +| `path` | string | The share-relative path of the file, for example `/dir1/dir2/file.ext`. | +| `name` | string | The file name only, without the directory component. | +| `sizeBytes` | int | The file size in bytes. | +| `eTag` | string | The entity tag of the file. | +| `lastModified` | time:Utc | The last-modified time (UTC). | + +### `ServiceConfiguration` + +The type of the optional `@files:ServiceConfig` annotation on the service. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `recursive` | boolean | true | Whether the service watches subdirectories under the watched path. | +| `fileNamePattern` | string | () | A regular expression matched against the file name (not the path); non-matching files are never dispatched to this service. An invalid pattern fails when the service is attached. | +| `minFileAgeSeconds` | decimal | () | Skip files younger than this many seconds, guarding against files still being written. | + +### `FunctionConfiguration` + +The type of the optional `@files:FunctionConfig` annotation on individual handlers. It also applies to `onError`, where the consume actions dispose of the binding failures it handles. + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `fileNamePattern` | string | () | Per-handler routing override: a regular expression matched against the file name. Ignored on `onError`, which is never routed a file. | +| `afterProcess` | DELETE|Move | () | Auto-consume action after the handler returns normally. On `onError`, it applies when `onError` returns normally, meaning it handled the binding failure. | +| `afterError` | DELETE|Move | () | Auto-consume action after the handler returns an error. On a content handler it also covers content-binding failures, but only when the service declares no `onError`. On `onError` it applies when `onError` itself returns an error or panics. | + +`files:DELETE` deletes the file. A `Move` record moves it: + +| Field | Type | Default | Description | +|-------|------|---------|-------------| +| `moveTo` | string | Required | The target directory; the file keeps its name and the directory is created if absent. | +| `preserveSubDirs` | boolean | true | Recreate the file's sub-path under the target directory on recursive watches. | + +A move onto an existing same-named file replaces it. + +### `ContentBindingError` + +The error delivered to `onError` when a dispatched file's content does not bind to its handler's declared type. It is the one client-side error that carries a detail record. + +| Field | Type | Description | +|-------|------|-------------| +| `filePath` | string | The share-relative path of the file whose content failed to bind, for example `/incoming/broken.json`. | +| `content` | byte[] | The file's raw content. Absent when the failure happened before the content was read, which is the case for the stream content forms. | + +Narrow to it inside `onError` to act on the file that failed: + +```ballerina +remote function onError(files:Error err) returns error? { + if err is files:ContentBindingError { + log:printError("file did not bind", path = err.detail().filePath, 'error = err); + return; + } + log:printError("listener error", 'error = err); +} +``` + +### `Caller` + +A `files:Caller` is passed to each handler so it can act on the event's file without constructing a separate client. It forwards a share-scoped subset of the `Client` operations, with the same signatures: `getFile`, `download`, `uploadFromFile`, `upload`, `deleteFile`, `renameFile`, `copyFile`, `checkCopyStatus`, `abortCopy`, `createDirectory`, `deleteDirectory`, and `list`. See the [Action Reference](action-reference.md) for each operation. + +Handlers pass the event's path explicitly, for example `caller->deleteFile(file.path)`, and read the share's name from `FileInfo.shareName`. Property reads and writes and share-level administrative operations are not forwarded; construct a `Client` for those. diff --git a/en/docs/develop/integration-artifacts/file/azure-files.md b/en/docs/develop/integration-artifacts/file/azure-files.md new file mode 100644 index 00000000000..f7e10fe6193 --- /dev/null +++ b/en/docs/develop/integration-artifacts/file/azure-files.md @@ -0,0 +1,617 @@ +--- +title: Azure Files +description: Process files from Azure file shares using polling, pattern matching, typed content retrieval, and automatic post-processing. +keywords: [wso2 integrator, azure files, file integration, file share, polling, drop folder] +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Azure Files + +Azure Files [file integrations](../../../get-started/concepts/core.md#file-integration) poll a directory on an Azure file share and process files as they arrive. Use them for drop-folder processing, ETL pipelines, and batch integrations where applications exchange data as CSV, XML, JSON, or binary files through a share mounted over SMB or NFS. + +The listener authenticates to the storage account with a shared key, a SAS token, a SAS URL, a connection string, or a Microsoft Entra ID identity. For creating the storage account, the file share, and the credentials, see the [Azure Files setup guide](../../../connectors/catalog/storage-file/azure.storage.files/setup-guide.md). + +## Creating an Azure Files service + +One flow creates the listener and the service together; the authentication method is a selector on the creation form. + + + + +1. Click **+** in the WSO2 Integrator side panel header to open the **New Integration** wizard (on an empty project, the **+ Add Integration or Library** button in the project view opens the same wizard), and continue to the **Type** step. + +2. Scroll to the **File Integration** category, select the **Azure Files** card, and click **Next**. + + ![New Integration wizard with the Azure Files card selected](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_01_new_integration_wizard.png) + +3. The **Azure Files Integration** page opens with the **Listener Configurations** form. Fill in: + + | Field | Description | + |---|---| + | **Listener Name** | Identifier for this listener (e.g., `shareListener`). | + | **Share Name** | The name of the file share to watch. | + | **Monitoring Path** | The directory on the share to poll for files (e.g., `/incoming`). `/` watches the share root. | + +4. Choose an **authentication method**. For **Shared Key**, fill in: + + | Field | Description | + |---|---| + | **Account Name** | The storage account name. | + | **Account Key** | A base64-encoded access key of the storage account. | + + ![Azure Files listener configuration form](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_02_listener_config_form.png) + + The selector's other options — SAS token, SAS URL, connection string, and Microsoft Entra ID — reveal the fields of the matching credential record shown on the Ballerina Code tab. + +5. Click **Create**. WSO2 Integrator generates the listener and the service, and a **files:Service** entry appears in the sidebar under **Entry Points**. + +6. Click [**+ Add Handler**](#adding-a-file-handler) in the service view to define how incoming files are processed. + + + + +The service's attach point is the watched path — `service /incoming on shareListener` watches the `/incoming` directory of the share, the string form `service "/dir one/reports" on shareListener` covers names a resource path cannot express, and a service with no attach point watches the share root. + +**Shared Key:** + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string accountKey = ?; +configurable string shareName = ?; + +listener files:Listener shareListener = new (shareName, + auth = {accountName, accountKey}, + pollingInterval = 30 +); + +service /incoming on shareListener { + remote function onFileText(string content, files:FileInfo file) returns error? { + // Process text file content + } +} +``` + +**SAS token:** + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string sasToken = ?; +configurable string shareName = ?; + +listener files:Listener shareListener = new (shareName, + auth = {accountName, sasToken} +); + +service /incoming on shareListener { + remote function onFileText(string content, files:FileInfo file) returns error? { + // Process text file content + } +} +``` + +**SAS URL** — the full URL from the Azure portal, carrying the endpoint and the token in one string: + +```ballerina +import ballerinax/azure.storage.files; + +configurable string sasUrl = ?; +configurable string shareName = ?; + +listener files:Listener shareListener = new (shareName, + auth = {sasUrl} +); + +service /incoming on shareListener { + remote function onFileText(string content, files:FileInfo file) returns error? { + // Process text file content + } +} +``` + +**Connection string:** + +```ballerina +import ballerinax/azure.storage.files; + +configurable string connectionString = ?; +configurable string shareName = ?; + +listener files:Listener shareListener = new (shareName, + auth = {connectionString} +); + +service /incoming on shareListener { + remote function onFileText(string content, files:FileInfo file) returns error? { + // Process text file content + } +} +``` + +**Microsoft Entra ID with the default credential chain** — tries the environment, a managed identity, and developer sign-ins in turn, so one configuration works both locally and when deployed: + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string shareName = ?; + +listener files:Listener shareListener = new (shareName, + auth = {kind: "default", accountName} +); + +service /incoming on shareListener { + remote function onFileText(string content, files:FileInfo file) returns error? { + // Process text file content + } +} +``` + +**Microsoft Entra ID as a service principal with a client secret:** + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string tenantId = ?; +configurable string clientId = ?; +configurable string clientSecret = ?; +configurable string shareName = ?; + +listener files:Listener shareListener = new (shareName, + auth = {accountName, tenantId, clientId, clientSecret} +); + +service /incoming on shareListener { + remote function onFileText(string content, files:FileInfo file) returns error? { + // Process text file content + } +} +``` + +Entra ID also supports managed identities, service principals with client certificates, and workload identities — one record per credential kind, each carrying the fields that credential needs. See the [connector configuration reference](../../../connectors/catalog/storage-file/azure.storage.files/action-reference.md#configuration) for every record. The Entra ID identity must hold the `Storage File Data Privileged Reader` or `Storage File Data Privileged Contributor` role on the storage account. + + + + +## File handlers + +A file handler is a `remote function` that WSO2 Integrator calls for each file the listener's polling cycle finds on the watched path. A service declares one handler per content format it processes, plus an optional error handler: + +| Handler | Trigger | +|---|---| +| **onCreate** (`onFileText` / `onFileJson` / `onFileXml` / `onFileCsv` / `onFile`) | A file on the watched path matches the service's filters. The function name depends on the content type — one typed variant per file format, with `onFile` as the raw-bytes catch-all. | +| **onError** | A poll failed, a listed file's content could not be read, or a file's content could not be bound to a typed handler's content parameter — for example, a JSON handler received malformed JSON. A binding failure arrives as a `files:ContentBindingError` naming the file. | + +At least one content handler is required — a service with only an `onError` handler is not valid. + +There is no delete handler: the listener dispatches the files present on the share and keeps no per-file state. + +### Adding a file handler + + + + +1. Open the service view (select **files:Service** under **Entry Points**) and click **+ Add Handler**. The handler picker offers **On Create**, which fires for files appearing on the monitoring path; select it. + + ![Handler picker with the On Create handler](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_03_add_handler_panel.png) + +2. The handler configuration panel opens: + + | Field | Description | + |---|---| + | **Format** | The format of incoming files. Determines the handler function name and the type of the `content` parameter. Options: **JSON**, **XML**, **CSV**, **Text**, **Raw Bytes**. See [Content types](#content-types). | + | **After File Processing — On Success** | Action to take when the handler completes without error: **Move** to a destination path or **Delete** the file. See [Post-processing](#post-processing-moving-or-deleting-files). | + | **After File Processing — On Error** | Action to take when the handler returns an error: **Move** to an error directory or **Delete** the file. It also covers a content-binding failure, unless the service declares an `onError` handler in code, in which case the binding failure's disposition follows `onError`'s own actions instead. See [Post-processing](#post-processing-moving-or-deleting-files). | + + ![On Create handler configuration with the format and post-processing actions](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_04_handler_config.png) + +3. Click **Save** to register the handler. The service view lists it: + + ![Service view with the registered handler](/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_06_service_view_final.png) + +An `onError` handler for poll, read, and content-binding failures is added in the code view — see the Ballerina Code tab. Declaring one changes how content-binding failures are post-processed; see [Post-processing](#post-processing-moving-or-deleting-files). + + + + +File handlers are typed `remote function` declarations inside the service. WSO2 Integrator routes files to handlers by file extension; the content parameter type determines deserialization. + +**Text file handler:** + +```ballerina +remote function onFileText(string content, files:FileInfo file) returns error? { + // content contains the full file text +} +``` + +**JSON file handler (typed record):** + +```ballerina +type Order record {| + string orderId; + string product; + int quantity; +|}; + +remote function onFileJson(Order 'order, files:FileInfo file) returns error? { + // 'order is deserialized from JSON +} +``` + +**CSV streaming handler (large files):** + +```ballerina +type Row record {| + string orderId; + int quantity; +|}; + +remote function onFileCsv(stream content, files:FileInfo file) returns error? { + check content.forEach(function(Row row) { + // Process each row without loading the whole file into memory + }); +} +``` + +**Binary file handler:** + +```ballerina +remote function onFile(byte[] content, files:FileInfo file) returns error? { + // content is the raw file bytes +} +``` + +**Error handler** — fires on every listener-side failure: a failed poll, a listed file whose content could not be read, and a typed handler's content-binding failure (for example, a JSON handler receiving malformed JSON). Poll and read failures arrive as the mapped typed error, such as a `files:AuthorizationError`. A binding failure arrives as a `files:ContentBindingError`, whose detail carries the file's `filePath` and, when the content had been downloaded before binding failed, its raw `content`: + +```ballerina +remote function onError(files:Error err) returns error? { + if err is files:ContentBindingError { + log:printError("file did not bind", path = err.detail().filePath, 'error = err); + return; + } + log:printError("file processing error", 'error = err); +} +``` + +A read failure always leaves the file for the next poll, so the notification repeats while the read keeps failing. Errors a content handler itself returns do not reach `onError`. + +The trailing parameters are optional. A content handler declares its content parameter first, then either, both, or neither of `files:FileInfo` and `files:Caller` — the accepted shapes are `(content)`, `(content, FileInfo)`, `(content, Caller)`, and `(content, FileInfo, Caller)`; when both are present, `FileInfo` must precede `Caller`. `onError` accepts `(error)` or `(error, Caller)`, and may carry its own `@files:FunctionConfig` to dispose of the binding failures it handles. + + + + +### Content types + +The **Format** chosen on an On Create handler determines the function name and the type of the `content` parameter. Files are routed to handlers by file extension: + +| Format | Handler function | Routed extension | Content type | Use when | +|---|---|---|---|---| +| **Text** | `onFileText` | `.txt` | `string` | Files are plain text (logs, EDI, custom formats). | +| **JSON** | `onFileJson` | `.json` | `json` or a typed record | Files are JSON documents. | +| **XML** | `onFileXml` | `.xml` | `xml` or a typed record | Files are XML documents. | +| **CSV** | `onFileCsv` | `.csv` | `record {}[]` or `stream` | Files are comma-separated values. Rows map through the header row into your record type; use a stream for large files. | +| **Raw Bytes** | `onFile` | any other extension | `byte[]` or `stream` | Binary files or when you need raw byte access. | + +Routing rules: + +- A per-handler `@files:FunctionConfig` with a `fileNamePattern` overrides extension routing for that handler. When several patterns match one file name, the handlers are checked in the fixed order `onFileText`, `onFileJson`, `onFileXml`, `onFileCsv`, then `onFile`. At most one handler runs per file. +- A file whose extension maps to a handler the service does not declare falls back to `onFile`; if `onFile` is also absent, the file is skipped and logged. +- A file routed to a typed handler whose content is malformed raises a `files:ContentBindingError` — it never falls through to `onFile`. Its detail carries the file's path in `filePath`, and its raw bytes in `content` when the download had already completed. When the service declares an `onError` handler, the error is delivered there and the file's fate follows **`onError`'s own** `@files:FunctionConfig`; the content handler's `afterError` is not applied. When the service declares no `onError`, the error is logged and the content handler's `afterError` applies. + +### Post-processing: moving or deleting files + +Delivery is at-least-once: the listener keeps no per-file state, so a file that stays on the watched path fires again on every poll. Handlers consume files by deleting or moving them out of the watched path — either through the [`Caller`](#caller-operations) or with the automatic actions configured here. + + + + +The handler configuration panel's **After File Processing** section has two independent actions: + +| Event | Action picker | Extra input | +|---|---|---| +| **On Success** | **Move** or **Delete** | **Move To** destination path (required when Move is chosen) | +| **On Error** | **Move** or **Delete** | **Move To** destination path (required when Move is chosen) | + +Common combinations: + +- **Delete on success, move on error** — discard processed files, quarantine failures for review. Set an error destination like `/failed`. +- **Move on success, move on error** — archive processed files and quarantine failures. Set separate destinations like `/processed` and `/failed`. +- **Leave the file alone for an outcome** — skip the action for that side; the file stays on the watched path and fires again on the next poll. + +These actions cover errors the handler returns. If the service also declares an `onError` handler in the code view, content-binding failures are disposed of by `onError`'s own actions instead, so annotate `onError` to quarantine files that fail to bind. + +The choices update the handler's `@files:FunctionConfig` annotation; switch to the code view to review the generated annotation. + + + + +The form writes an `@files:FunctionConfig` annotation on the handler. Each of `afterProcess` and `afterError` takes one of two values — the bare constant `files:DELETE` for delete, or a `files:Move` record for move: + +```ballerina +@files:FunctionConfig { + afterProcess: files:DELETE, + afterError: {moveTo: "/failed"} +} +remote function onFileJson(Order 'order, files:FileInfo file) returns error? { + check processOrder('order, file.name); +} +``` + +`@files:FunctionConfig` fields: + +| Field | Type | Description | +|---|---|---| +| `fileNamePattern` | `string?` | Regular expression matched against the file name, routing matching files to this handler. Overrides extension routing. Ignored on `onError`, which is never routed a file. | +| `afterProcess` | `files:DELETE\|files:Move?` | Action to take when the handler returns without error. Omit the field to leave the file in place. | +| `afterError` | `files:DELETE\|files:Move?` | Action to take when the handler returns an error or panics. Also covers the handler's content-binding failures, but only when the service declares no `onError` handler. Same shape as `afterProcess`. | + +The annotation may also sit on `onError`, where `afterProcess` and `afterError` dispose of the binding failures it handles. + +`files:Move` fields: + +| Field | Type | Default | Description | +|---|---|---|---| +| `moveTo` | `string` | — | The target directory the file is moved into. The file keeps its name, and the directory is created if it does not exist. A move onto an existing same-named file replaces it. | +| `preserveSubDirs` | `boolean` | `true` | On recursive watches, recreate the file's sub-path (relative to the watched path) under `moveTo`. | + +`afterError` also covers the handler's content-binding failures, but only when the service declares no `onError` handler. With an `onError` declared, a binding failure becomes its to dispose of: annotate `onError` itself to quarantine the file. + +```ballerina +// Quarantines every file that fails to bind, and logs the failure. +@files:FunctionConfig {afterProcess: {moveTo: "/failed"}} +remote function onError(files:Error err) returns error? { + log:printError("listener error", 'error = err); +} +``` + +On `onError`, `afterProcess` applies when it returns normally and `afterError` when it returns an error; `fileNamePattern` is ignored. The actions cover binding failures only — a file whose content could not be read always stays for the next poll, whatever `onError` returns. Setting neither leaves the file on the watched path to fire again on every poll. + + + + +### Typed content and streaming + +JSON and XML handlers can receive their payload as a free-form value (`json`, `xml`) or as a typed record you define; CSV handlers bind typed records only. CSV and Raw Bytes handlers can additionally receive the content as a `stream`, so the handler never holds the whole file in memory. The **Format** picker on the handler form selects the base delivery type; to bind typed records or streams, edit the handler's content parameter type in the code view. + +**Typed CSV rows** — the file's first row is always consumed as the header and maps each row's fields: + +```ballerina +type Order record {| + string orderId; + string product; + int quantity; +|}; + +remote function onFileCsv(Order[] orders, files:FileInfo file) returns error? { + foreach Order 'order in orders { + // typed field access: 'order.orderId, 'order.quantity, ... + } +} +``` + +**Typed JSON document:** + +```ballerina +type OrderBatch record {| + string batchId; + Order[] orders; +|}; + +remote function onFileJson(OrderBatch batch, files:FileInfo file) returns error? { + // batch.batchId and batch.orders are typed +} +``` + +**Streaming CSV rows:** + +```ballerina +remote function onFileCsv(stream orders, files:FileInfo file) returns error? { + check orders.forEach(function(Order 'order) { + // process each row as it arrives + }); +} +``` + +**Streaming raw bytes:** + +```ballerina +remote function onFile(stream content, files:FileInfo file) returns error? { + check content.forEach(function(byte[] chunk) { + // process each chunk + }); +} +``` + +A content value that does not match the declared parameter type is a `files:ContentBindingError`, delivered to `onError`. To relax the record binding — treating a null value as an optional field and an absent field as a nilable field — set `laxDataBinding: true` on the [listener configuration](#listener-configuration). + +### FileInfo + +Each handler can receive a `files:FileInfo` parameter with metadata about the dispatched file. + +| Field | Type | Description | +|---|---|---| +| `shareName` | `string` | The name of the share the file lives on | +| `path` | `string` | The share-relative path of the file, for example `/dir1/dir2/file.ext` — use this for all `caller->` operations | +| `name` | `string` | The file name only, without the directory component | +| `sizeBytes` | `int` | The file size in bytes | +| `eTag` | `string` | The entity tag of the file | +| `lastModified` | `time:Utc` | The last-modified time (UTC) | + +`FileInfo` carries what a directory listing provides. For full properties (content type, metadata, headers), use the connector's `getFileProperties` operation — see the [action reference](../../../connectors/catalog/storage-file/azure.storage.files/action-reference.md). + +### Caller operations + +For most use cases, the typed handler parameters and the `@files:FunctionConfig` post-processing actions are sufficient. When you need additional control — reading a related file, writing output to a different path, or managing files manually — add the `files:Caller` parameter to your handler. It exposes a share-scoped subset of the connector's client operations on the same connection the listener polls with. + +**Reading and writing content:** + +| Operation | Return type | Description | +|---|---|---| +| `caller->getFile(path, options)` | `T\|Error` | Retrieve a file's content in the form the assignment target selects — `byte[]`, `string`, `json`, `xml`, a typed record or record array, or a lazy stream | +| `caller->download(sourcePath, destinationPath, options)` | `Error?` | Download a file to a local path | +| `caller->uploadFromFile(sourcePath, destinationPath, options)` | `Error?` | Upload a local file to the share | +| `caller->upload(content, destinationPath, options)` | `Error?` | Upload in-memory content — `byte[]`, `string`, `json`, `xml`, a record, or a record array | + +**File management:** + +| Operation | Return type | Description | +|---|---|---| +| `caller->deleteFile(path)` | `Error?` | Delete a file | +| `caller->renameFile(sourcePath, destinationPath, options)` | `Error?` | Rename or move a file within the share | +| `caller->copyFile(sourcePath, destinationPath, options)` | `files:CopyInfo\|Error` | Start an asynchronous copy within the share | +| `caller->checkCopyStatus(path)` | `files:CopyStatusInfo?\|Error` | Check the state of the most recent copy targeting a file | +| `caller->abortCopy(path, copyId)` | `Error?` | Abort a pending copy | + +**Directories:** + +| Operation | Return type | Description | +|---|---|---| +| `caller->createDirectory(directoryPath, options)` | `Error?` | Create a directory | +| `caller->deleteDirectory(directoryPath)` | `Error?` | Delete an empty directory | +| `caller->list(directoryPath, options)` | `stream\|Error` | List the entries under a directory | + +Handlers pass the event's path explicitly — for example, a handler that consumes its file manually: + +```ballerina +remote function onFile(byte[] content, files:FileInfo file, files:Caller caller) returns error? { + check archive(content); + check caller->deleteFile(file.path); +} +``` + +Property reads and writes and share-level administrative operations are not on the `Caller`; construct a client through a [connection](../supporting/connections.md) for those. See the [action reference](../../../connectors/catalog/storage-file/azure.storage.files/action-reference.md) for every operation's parameters. + +## Service and listener + +Every Azure Files integration in the project tree is built from two pieces: + +| Construct | Role | +|---|---| +| **Listener** | The connection to one file share. Holds the credentials, the share name, and how often to poll. | +| **Service** | The processing logic for one directory on that share. Its attach point is the watched path, and it holds the file filters and the file handlers that run when a file arrives. | + +The pairing is one-to-one: each listener accepts exactly one service. To watch several paths — on the same share or on different shares — declare one listener and service pair per path: + +```ballerina +import ballerinax/azure.storage.files; + +configurable string accountName = ?; +configurable string accountKey = ?; +configurable string shareName = ?; + +listener files:Listener ordersListener = new (shareName, + auth = {accountName, accountKey} +); + +listener files:Listener invoicesListener = new (shareName, + auth = {accountName, accountKey} +); + +type OrderRow record {| + string orderId; + int quantity; +|}; + +service /orders on ordersListener { + remote function onFileCsv(OrderRow[] content, files:FileInfo file) returns error? { + // Process order CSVs from /orders + } +} + +service /invoices on invoicesListener { + remote function onFileXml(xml content, files:FileInfo file) returns error? { + // Process invoice XMLs from /invoices + } +} +``` + +Delivery is at-least-once. The listener keeps no per-file state, so a file that stays on the watched path fires again on every poll — consume processed files with the [post-processing actions](#post-processing-moving-or-deleting-files) or through the [`Caller`](#caller-operations). One file is never dispatched twice at once: at most one invocation runs per path at a time, and a file overwritten while its handler is running is picked up on a later poll. For exactly-once effects, make handlers idempotent or claim each file by renaming it out of the watched path before processing. A file still being written when a poll runs can be picked up mid-write — set `minFileAgeSeconds` on the [service configuration](#service-configuration) to guard against partial writes. + +For the general concept, see [Services and listeners](../../../get-started/concepts/core.md#integration-as-api). + +## Service configuration + +The optional `@files:ServiceConfig` annotation controls what the service watches — recursion into subdirectories, file-name filtering, and a minimum file age. It does not carry a path: the watched path is the service's attach point, so where the [FTP/SFTP service](ftp-sftp.md#service-configuration) sets a `path` field, the Azure Files service is declared as `service /incoming on shareListener`. + +```ballerina +type OrderRow record {| + string orderId; + int quantity; +|}; + +@files:ServiceConfig { + recursive: false, + fileNamePattern: ".*\\.csv", + minFileAgeSeconds: 30 +} +service /incoming/orders on shareListener { + remote function onFileCsv(OrderRow[] content, files:FileInfo file) returns error? { + // Process order CSVs + } +} +``` + +`@files:ServiceConfig` fields: + +| Field | Type | Default | Description | +|---|---|---|---| +| `recursive` | `boolean` | `true` | Watch subdirectories under the watched path. | +| `fileNamePattern` | `string?` | — | Regular expression matched against the file name (not the path); non-matching files are never dispatched. | +| `minFileAgeSeconds` | `decimal?` | — | Skip files younger than this many seconds, guarding against files still being written. | + +## Listener configuration + +The listener controls **how** to connect — the share, the credentials, and the polling cadence. Open the listener's configuration by clicking its name (for example, `shareListener`) under **Listeners** in the sidebar. + + + + +| Field | Description | Default | +|---|---|---| +| **Name** | Identifier for the listener. Required. | — | +| **Share Name** | The name of the file share to watch. Required. | — | +| **Auth** | The authentication record — one of the five credential kinds. See [Creating an Azure Files service](#creating-an-azure-files-service). Required. | — | +| **Polling Interval** | Seconds between polls of the watched path. Must be greater than zero. | `60` | +| **Retry Config** | Retry behaviour for service requests. | Service defaults | +| **Transport Config** | HTTP transport settings — proxy, connection pool, and TLS. | Defaults | +| **Lax Data Binding** | Relaxed data binding for the typed content handlers: JSON, XML, and CSV record binding treat a null value as an optional field and an absent field as a nilable field. | `false` | + + + + +Listener configuration maps to the `files:ListenerConfiguration` record passed when constructing the listener, alongside the share name: + +```ballerina +listener files:Listener shareListener = new (shareName, + auth = {accountName, accountKey}, + pollingInterval = 30 +); +``` + +`files:ListenerConfiguration` fields: + +| Field | Type | Default | Description | +|---|---|---|---| +| `auth` | `files:AuthConfig` | — | The authentication configuration — one credential-artifact record. See [Creating an Azure Files service](#creating-an-azure-files-service). | +| `pollingInterval` | `decimal` | `60` | How often the watched path is polled, in seconds. Must be greater than zero. | +| `retryConfig` | `files:RetryConfig?` | — | Retry behaviour for service requests; omit for the service defaults. | +| `transportConfig` | `files:TransportConfig?` | — | HTTP transport settings (proxy, connection pool, TLS); omit for the defaults. | +| `laxDataBinding` | `boolean` | `false` | Relaxed data binding for the typed content handlers. | + +For the `RetryConfig` and `TransportConfig` field sets and the credential records, see the [connector configuration reference](../../../connectors/catalog/storage-file/azure.storage.files/action-reference.md#configuration). + + + + +Each poll with `recursive: true` issues a full recursive listing and downloads every dispatched file. At scale, widen the polling interval, narrow the watched path, or add a `fileNamePattern`. + +## What's next + +- [Local files](local-files.md) — monitor a local directory instead of a file share +- [Azure Files connector reference](../../../connectors/catalog/storage-file/azure.storage.files/overview.md) — setup, operations, and the full trigger reference diff --git a/en/docs/develop/integration-artifacts/integration-artifacts.md b/en/docs/develop/integration-artifacts/integration-artifacts.md index 07acc26bd6c..aa9d2d5247d 100644 --- a/en/docs/develop/integration-artifacts/integration-artifacts.md +++ b/en/docs/develop/integration-artifacts/integration-artifacts.md @@ -66,6 +66,7 @@ Trigger an integration when files appear on a remote server or local directory. | Artifact | Description | |---|---| | [FTP/SFTP](file/ftp-sftp.md) | Watches an FTP, FTPS, or SFTP server for new or modified files. | +| [Azure Files](file/azure-files.md) | Watches a directory on an Azure file share for incoming files. | | [Local files](file/local-files.md) | Watches a local directory for file arrivals and changes. | ### Other artifacts diff --git a/en/sidebars.ts b/en/sidebars.ts index d00d9898d77..08a73c593dd 100644 --- a/en/sidebars.ts +++ b/en/sidebars.ts @@ -182,6 +182,7 @@ const sidebars: SidebarsConfig = { 'develop/integration-artifacts/file/csv-fault-tolerance', ], }, + 'develop/integration-artifacts/file/azure-files', 'develop/integration-artifacts/file/local-files', ], }, @@ -527,6 +528,17 @@ const sidebars: SidebarsConfig = { 'connectors/catalog/ai-ml/azure.ai.search.index/example', ], }, + { + type: 'category', + label: 'Azure Files', + link: { type: 'doc', id: 'connectors/catalog/storage-file/azure.storage.files/overview' }, + items: [ + 'connectors/catalog/storage-file/azure.storage.files/setup-guide', + 'connectors/catalog/storage-file/azure.storage.files/action-reference', + 'connectors/catalog/storage-file/azure.storage.files/trigger-reference', + 'connectors/catalog/storage-file/azure.storage.files/example', + ], + }, { type: 'category', diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_01_configurables_panel.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_01_configurables_panel.png new file mode 100644 index 00000000000..026a1da09c2 Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_01_configurables_panel.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_02_palette.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_02_palette.png new file mode 100644 index 00000000000..fdbe75ecb5b Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_02_palette.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_03_connection_form.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_03_connection_form.png new file mode 100644 index 00000000000..2f0f9cf991a Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_03_connection_form.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_04_operations_panel.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_04_operations_panel.png new file mode 100644 index 00000000000..8ee8ba50d45 Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_04_operations_panel.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_05_uploadfile_form.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_05_uploadfile_form.png new file mode 100644 index 00000000000..559c86276f2 Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_05_uploadfile_form.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_06_completed_flow.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_06_completed_flow.png new file mode 100644 index 00000000000..37e313f160b Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_screenshot_06_completed_flow.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_01_new_integration_wizard.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_01_new_integration_wizard.png new file mode 100644 index 00000000000..65023939969 Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_01_new_integration_wizard.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_02_listener_config_form.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_02_listener_config_form.png new file mode 100644 index 00000000000..f4ee5d2e661 Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_02_listener_config_form.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_03_add_handler_panel.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_03_add_handler_panel.png new file mode 100644 index 00000000000..056977e5283 Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_03_add_handler_panel.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_04_handler_config.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_04_handler_config.png new file mode 100644 index 00000000000..936f6e18e1c Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_04_handler_config.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_05_handler_flow.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_05_handler_flow.png new file mode 100644 index 00000000000..f08cca3e9e6 Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_05_handler_flow.png differ diff --git a/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_06_service_view_final.png b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_06_service_view_final.png new file mode 100644 index 00000000000..ed797d4252b Binary files /dev/null and b/en/static/img/connectors/catalog/storage-file/azure.storage.files/azure_files_trigger_screenshots_06_service_view_final.png differ