مشاركة عبر

Azure Files REST API

  • مقالة

Azure Files provides hosted cloud file shares that you can access (mount) by using industry-standard file system protocols such as SMB and NFS. When you mount a file share on your computer by using SMB or NFS, your operating system redirects API requests for the local file system. The redirection includes local API requests that you make by using .NET System.IO interfaces or Python open, read, or write methods. This means that users of these applications don't need to do anything special or even know that their data is on a remote file share instead of local storage.

Azure Files also provides a REST API, which is often called the FileREST API. To use the FileREST API, you create HTTPS requests against the FileREST HTTPS endpoints. You could write code to create HTTPS requests yourself, but we provide Azure SDKs that use the FileREST API for you, providing an idiomatic language wrapper over the FileREST API in popular languages such as C#, Java, Python, JavaScript, and Go.

Because the FileREST API was designed specifically for Azure Files, it enables you to access features of Azure Files that you can't access over SMB or NFS. It also enables you to perform certain operations, such as copy, more efficiently than you can via SMB or NFS.

The stateless nature of HTTPS makes the FileREST API useful for cloud services or applications that need to access many Azure file shares. For example, you can attach value-added services or applications to an Azure file share to add a capability. These services or applications might include antivirus, backup, data management, or replication products. Azure File Sync and Azure Backup are notable Microsoft services that extensively use the FileREST API to add value on top of a customer-owned Azure file share.

Consider using the FileREST API if you're building value-added services or applications, especially if you're providing those services to customers. If you're constructing a line-of-business application, particularly one that users will use against a mounted Azure file share, you can use either SMB/NFS or FileREST. However, you might find that using SMB or NFS provides an easier path because those protocols enable you to use native file system APIs.

If you have an existing application that was written with native file system APIs, you don't need to rewrite it to take advantage of Azure Files. The key value proposition of Azure Files is exposing native file system APIs through the use of SMB or NFS.

To learn more about Azure Files, including deployment, networking, and identity configuration, see:

Control plane

In Azure, the control plane is provided through Azure Resource Manager, which provides a common way to expose Azure resources that the customer will manage. The top-level unit of management is the storage account. The storage account is a tracked resource in Azure Files and other storage services, such as Azure Blob Storage.

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:

  • The FileService resource. It provides settings specific to Azure Files that apply to all of the file shares in the storage account. The FileService resource is a child of the storage account. A storage account always has only one FileService resource: default.

  • The FileShare resource. It represents a file share or a snapshot of a file share. The FileShare resource is a child of the FileService resource and can contain an infinite number of file shares.

Although a FileService resource can contain an infinite number of FileShare resources, using a very large number is not a good idea because everything within a storage account shares a defined pool of I/O, bandwidth, and other limits. For more information, see Azure Files scalability and performance targets.

To learn how to call the control plane APIs, see:

Operations on the FileService and FileShare objects can also be done through the data plane. This is an artifact of Azure Files predating Azure Resource Manager. Although these APIs are fully supported, in most cases you should use the storage resource provider APIs to manage Azure Files for these reasons:

  • Operations exposed through Azure Resource Manager use Microsoft Entra ID for authentication and authorization, so you can manage Azure Files by using role-based access control (RBAC). You can authorize your application or service to programmatically call these APIs with a Microsoft Entra service principal.

  • You can call Azure Resource Manager APIs imperatively, either through the REST API directly or through an SDK. Or you can call them declaratively, by declaring what resources need to be deployed through Azure templates. For resources that need to be repeatedly created together (for example, in service deployments), using templates can considerably simplify the work that's required.

  • Although we recommend using the storage resource provider to manage storage resources, using the FileREST data plane management APIs will give you better performance in cases that require high scale. An example of such a case is a workload that creates or modifies thousands of file shares within the same storage account.

    • Microsoft.Storage storageAccounts/fileServices/shares triggers a control plane operation via the storage resource provider.
    • Microsoft.Storage storageAccounts/fileServices/fileshares is a data plane operation. Setting share-level roles such as Storage File Data SMB Share Reader should be a data plane operation and must use this resource.

Data plane

Azure Files provides a hierarchical file system for unstructured data. 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:

See also