File Service REST API

The Server Message Block (SMB) protocol is the preferred file share protocol used on premise 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.window.net. Note that 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.

Azure 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
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 allows users to check for directory existence. Only LMT i.e. created date will be returned. 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

Request Headers
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 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.

See Also

Storage Services REST