File service REST API
The Server Message Block (SMB) protocol is the preferred file share protocol used on-premises today. The Microsoft Azure File service enables customers to leverage the availability and scalability of Azure’s Cloud Infrastructure as a Service (IaaS) SMB without having to rewrite SMB client applications.
The Azure File service also offers a compelling alternative to traditional Direct Attached Storage (DAS) and Storage Area Network (SAN) solutions, which are often complex and expensive to install, configure, and operate. Pricing for the new Azure File service is consistent with existing Azure Storage services and is charged in units of storage capacity and transactions. See the Azure Storage Pricing page for details.
Files stored in Azure File service shares are accessible via the SMB protocol, and also via REST APIs, at the endpoint
http|https://<account>.file.core.windows.net. HTTPS is recommended.
While the Azure File service REST APIs are similar to the Azure Blob service REST APIs, there are minor differences related to how the service models the underlying file system. These differences are noted in the operations table below.
File service REST operations
The Azure File service offers the following four resources: the storage account, shares, directories, and files. Shares provide a way to organize sets of files and also can be mounted as an SMB file share that is hosted in the cloud.
The File service REST API provides a way to work with share, directory, and file resources via HTTP/HTTPS operations. File service operations are available only in version 2014-02-14 of the storage services or later.
The File service REST API includes the operations listed in the table below.
|Operation||Resource Type||REST Verb||Description||Differences with corresponding Blob service operation|
|List Shares||Storage account||GET||Lists all the file shares in a storage account||None|
|Get File Service Properties||Storage account||GET||Gets the File service properties for the storage account||None|
|Set File Service Properties||Storage account||PUT||Sets the File service properties for the storage account||None|
|Preflight File Request||Storage account||OPTIONS||Queries the Cross-Origin Resource Sharing (CORS) rules for the File service prior to sending the actual request.||None|
|Create Share||Share||PUT||Creates a new share in a storage account.||Request header|
|Snapshot Share||Share||PUT||Creates a new share snapshot for an existing share in a storage account.||Request header|
|Get Share ACL||Share||GET/HEAD||Returns information about stored access policies specified on the share.||Response body|
|Set Share ACL||Share||PUT||Sets a stored access policy for use with shared access signatures.||Request body|
|Get Share Properties||Share||GET/HEAD||Returns all user-defined metadata and system properties of a share.||None|
|Set Share Properties||Share||PUT||Sets system properties for a share.||N/A|
|Get Share Metadata||Share||GET/HEAD||Returns only user-defined metadata of a share.||None|
|Set Share Metadata||Share||PUT||Sets user-defined metadata of a share.||None|
|Get Share Stats||Share||GET||Retrieves statistics related to the share.||N/A|
|Delete Share||Share||DELETE||Deletes the share and any files and directories that it contains.||None|
|List Directories and Files||Directory||GET||Lists files and directories within the share or specified directory.||Query String Params, Response Body|
|Create Directory||Directory||PUT||Creates a directory in the share or parent directory.||New|
|Get Directory Properties||Directory||GET/HEAD||Returns system defined properties of a directory. This operation allows users to check for directory existence.||New|
|Get Directory Metadata||Directory||GET/HEAD||Retrieves all user-defined metadata on the directory.||New|
|Set Directory Metadata||Directory||PUT||Sets user-defined metadata of an existing directory.||New|
|Delete Directory||Directory||DELETE||Deletes the directory. Only supported for empty directories.||New|
|Create File||File||PUT||Creates a new file or replaces an existing file within a directory or share.||Name
|Get File||File||GET||Reads or downloads a file from the File service, including its user-defined metadata and system properties.||Name, Response Headers|
|Set File Properties||File||PUT||Sets system properties defined for an existing file.||Name,
Request & Response Headers
|Get File Properties||File||HEAD||Returns all system properties and user-defined metadata on the file.||Name, Response Headers|
|Get File Metadata||File||GET/HEAD||Retrieves all user-defined metadata on the file.||Name only|
|Set File Metadata||File||PUT||Sets user-defined metadata of an existing file.||Name only|
|Delete File||File||DELETE||Deletes the file permanently.||Name only|
|Copy File||File||PUT||Copies a source blob or file to a destination file in this storage account.||Name, Param, Response Headers|
|Abort Copy File||File||PUT||Aborts a pending Copy File operation, and leaves a destination file with zero length and full metadata.||Name, Param, Response Headers|
|Put Range||File||PUT||Puts a range of data into a file, or clears a range in the file.||Name,
Query String Param, Response Header & Body
|List Ranges||File||GET||Returns a list of active ranges for the file. Active ranges are those ranges that have been populated with data using Put Range API.||Name,
Query String Param, Response Body
In this section
This section contains the following topics.