Azure Files REST API
Azure Files provides hosted cloud file shares that you can access ("mount") using industry standard file system protocols such as SMB and NFS. When you mount a file share on your computer using SMB or NFS, your operating system redirects local file system API requests, such as those that you might make using .NET's System.IO interfaces or Python's open/read/write methods. This means that applications, and importantly users of these applications, don't need to do anything special (or even know) their data is on a remote file share instead of local storage.
Because the FileREST API was designed specifically for Azure Files, it enables you to access features of Azure Files that are not accessible over SMB or NFS, and perform certain operations, such as copy, more efficiently than via SMB/NFS. The stateless nature of HTTPS makes the FileREST API is useful for use in cloud services or applications that need to access many Azure file shares, such as value-added services or applications that can be attached to the Azure file share to add some capability. These might include antivirus, backup, data management, or replication products. As an example, Azure File Sync and Azure Backup are notable first party value-added services that extensively use the FileREST API to add value on-top of a customer-owned Azure file share.
As a general rule, you should consider using the FileREST API if you are building value-added services or applications, especially if you are providing such value-added services to your customers. If you are constructing a line-of-business application, particularly one that end users will use against a mounted Azure file share, you can use either SMB/NFS or FileREST, however, you may find that using SMB/NFS provide an easier path since they enable you to use native file system APIs. If you have an existing application that was written native file system APIs, you absolutely do not need to rewrite it to take advantage of Azure Files; the key value proposition of Azure Files is exposing native file system APIs through use of SMB or NFS.
To learn more about Azure Files, including deployment, networking, and identity configuration, see:
In Azure, the control plane is provided through the Azure Resource Manager, sometimes abbreviated as ARM, which provides a common way of exposing Azure resources to be managed by the customer. The top-level unit of management, or tracked resource in Azure Files, and other storage services such as Blob storage, is the storage account. The storage account is managed by the storage resource provider, which has the namespace Microsoft.Storage. The storage resource provider also exposes management of child resources, or proxy resources, that enable the management of the storage services bundled in the storage account. For Azure Files, there are two relevant proxy resources:
FileServiceresource, which provides Azure Files specific settings that apply to all of the file shares in the storage account. The
FileServiceresource is a child of the storage account tracked resource, and a storage account only ever has one
FileShareresource, which represents a file share (or a snapshot of a file share). The
FileShareresource is a child of the
FileServiceresource, and may contain an infinite number of file shares. Although a
FileServicecan contain an infinite number of
FileShareresources, using a very large number is not a good idea as everything within a storage account shares a defined pool of IO, bandwidth, and other limits. For more information, see Azure Files scalability and performance targets.
To learn how to call the control plane APIs, see:
For legacy reasons, operations on the
FileShare objects may also be done through the data plane. This is an artifact of Azure Files predating Azure Resource Manager, and while these APIs are fully supported, you should prefer using the storage resource provider APIs to manage Azure Files for several reasons:
Operations exposed through Azure Resource Manager use Azure AD for authentication and authorization, enabling you to manage Azure Files with role-based access control (RBAC). You can authorize your application or service to programmatically call these APIs with an Azure AD service principal.
Azure Resource Manager APIs can be called imperatively, using the REST API directly or through an SDK, or declaratively, by declaring what resources need to be deployed using Azure templates. For resources that need to be repeatedly created together, service deployments, etc., using templates can considerably simplify the work required.
Although using the storage resource provider to manage storage resources is preferred, in cases requiring high scale, such as a workload that creates or modifies thousands of file shares within the same storage account, using the FileREST data plane management APIs will be most performant.
Azure Files provides a hierarchical file system for unstructured data ("files"). The FileREST API models the two important objects in the file system space: Files and Directories. To learn how to call the FileREST APIs, see:
- Operations on the File Service (prefer control plane APIs)
- Operations on File Shares (prefer control plane APIs)
- Operations on Directories
- Operations on Files