Azure Storage

Azure Storage File Service REST API Reference

This document provides a reference for the Azure Storage File service REST API. This API allows you to interact with your Azure File shares programmatically.

Introduction

The Azure Storage File service provides a fully managed file share in the cloud that is accessible via the industry-standard Server Message Block (SMB) protocol. It can be mounted concurrently by cloud or on-premises Windows, macOS, and Linux workloads.

Authentication

All requests to the Azure Storage REST APIs must be authenticated. The most common authentication methods are:

Refer to the Azure Storage authentication documentation for detailed information.

File Service Operations

List Shares

GET /{accountName}/shares

Lists all shares in the specified storage account.

Query Parameters

Name Description Required
include Optional. Specifies one or more root-level shares to include in the response. Valid values are metadata. No
prefix Optional. A string value that identifies the shares that return the name beginning with the specified prefix. No
marker Optional. Specifies a string value that identifies the position in the list of shares at which to begin the listing. No
maxresults Optional. Specifies the maximum number of shares to return. No
200 OK 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

GET https://myaccount.file.core.windows.net/myshare?restype=account&comp=list&include=metadata HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02

Create Share

PUT /{accountName}/shares/{shareName}

Creates a new file share under the specified account.

Query Parameters

Name Description Required
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No

Request Headers

Name Description Required
x-ms-meta- <name> Optional. User-defined metadata. No
x-ms-share-quota Optional. Specifies the quota in GiB for the share. No
201 Created 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

PUT https://myaccount.file.core.windows.net/myshare?restype=share HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02
x-ms-meta-project: data
x-ms-share-quota: 1024

Get Share Properties

GET /{accountName}/shares/{shareName}

Retrieves the properties of the specified file share.

Query Parameters

Name Description Required
comp Required. Set to properties to retrieve share properties. Yes
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No
200 OK 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

GET https://myaccount.file.core.windows.net/myshare?restype=share&comp=properties HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02

Delete Share

DELETE /{accountName}/shares/{shareName}

Deletes the specified file share.

Query Parameters

Name Description Required
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No
204 No Content 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

DELETE https://myaccount.file.core.windows.net/myshare?restype=share HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02

Directories and Files

The File service supports operations on directories and files within a share.

List Directories and Files

GET /{accountName}/shares/{shareName}/{directoryOrFilePath}

Lists the contents of a share, directory, or subdirectory.

Query Parameters

Name Description Required
comp Required. Set to list to list the contents. Yes
prefix Optional. A string value that identifies the entries that return the name beginning with the specified prefix. No
delimiter Optional. Specifies the delimiter for directory traversal. No
marker Optional. Specifies a string value that identifies the position in the list at which to begin the listing. No
maxresults Optional. Specifies the maximum number of entries to return. No
include Optional. Specifies one or more root-level shares to include in the response. Valid values are metadata. No
200 OK 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

GET https://myaccount.file.core.windows.net/myshare/mydir?restype=directory&comp=list&include=metadata HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02

Create Directory

PUT /{accountName}/shares/{shareName}/{directoryPath}

Creates a new directory under the specified share or parent directory.

Query Parameters

Name Description Required
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No

Request Headers

Name Description Required
x-ms-meta- <name> Optional. User-defined metadata. No
201 Created 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

PUT https://myaccount.file.core.windows.net/myshare/mydir/subdir?restype=directory HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02
x-ms-meta-department: engineering

Get Directory Properties

GET /{accountName}/shares/{shareName}/{directoryPath}

Retrieves the properties of the specified directory.

Query Parameters

Name Description Required
comp Required. Set to properties to retrieve directory properties. Yes
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No
200 OK 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

GET https://myaccount.file.core.windows.net/myshare/mydir?restype=directory&comp=properties HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02

Delete Directory

DELETE /{accountName}/shares/{shareName}/{directoryPath}

Deletes the specified directory. The directory must be empty before it can be deleted.

Query Parameters

Name Description Required
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No
204 No Content 400 Bad Request 403 Forbidden 409 Conflict 500 Internal Server Error

Example Request (Conceptual)

DELETE https://myaccount.file.core.windows.net/myshare/mydir?restype=directory HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02

Upload File

PUT /{accountName}/shares/{shareName}/{filePath}

Uploads a file to a specified share or directory.

Query Parameters

Name Description Required
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No
comp Optional. Can be append or flush for large file uploads. No
contentlength Required for PUT range operations. The length of the file. No
fileRange Optional. For uploading a range of bytes. No
maxPageSize Optional. For large file uploads, specifies the size of pages. No

Request Headers

Name Description Required
x-ms-content-length Required. The length of the file. Yes
x-ms-meta- <name> Optional. User-defined metadata. No
x-ms-type Optional. Set to file. No
x-ms-content-type Optional. The MIME type of the file. No
201 Created 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual - Uploading a small file)

PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile.txt HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02
x-ms-content-length: 1234
x-ms-content-type: text/plain
x-ms-meta-version: 1.0

<file content>

Get File Properties

GET /{accountName}/shares/{shareName}/{filePath}

Retrieves the properties of the specified file.

Query Parameters

Name Description Required
comp Required. Set to properties to retrieve file properties. Yes
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No
200 OK 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

GET https://myaccount.file.core.windows.net/myshare/mydir/myfile.txt?comp=properties HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02

Download File

GET /{accountName}/shares/{shareName}/{filePath}

Downloads the content of a file.

Query Parameters

Name Description Required
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No
ranges Optional. Specifies one or more byte ranges to retrieve. No
200 OK 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

GET https://myaccount.file.core.windows.net/myshare/mydir/myfile.txt HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02
x-ms-range: bytes=0-1023

Delete File

DELETE /{accountName}/shares/{shareName}/{filePath}

Deletes the specified file.

Query Parameters

Name Description Required
timeout Optional. Specifies the timeout, in seconds, relative to the time the request was submitted. No
204 No Content 400 Bad Request 403 Forbidden 500 Internal Server Error

Example Request (Conceptual)

DELETE https://myaccount.file.core.windows.net/myshare/mydir/myfile.txt HTTP/1.1
Authorization: SharedKey myaccount:Xq+5GjU3g+hS4f/HwM8s7P+d+Yg1dKzN3Q8o9rX3dZw=
Date: Mon, 27 Jul 2009 22:35:59 GMT
x-ms-version: 2019-02-02