Microsoft Docs

Azure Storage File REST API Reference

This document provides a comprehensive reference for the Azure Storage File REST API, which allows you to programmatically interact with Azure Files shares, directories, and files. You can use this API to perform operations such as creating, listing, and managing shares, as well as uploading, downloading, and managing files and directories within those shares.

File REST Operations

This section details the operations available for managing files and directories within an Azure Files share.

PUT Create File / Update File

PUT /{accountName}/{shareName}/{directory}/{file}

This operation creates a new file or uploads content to an existing file. If the file already exists, the operation overwrites the existing file.

Parameters

Name Type Description Required
x-ms-content-length Integer The size of the file in bytes. Yes
x-ms-lease-id (optional) String Specifies the lease ID if the file is currently leased. No
x-ms-blob-condition-append-offset (optional) Integer Specifies the condition that the append offset must be equal to the specified value. No

Common Response Codes

  • 201 Created: The file was successfully created.
  • 200 OK: The file was successfully updated.
  • 400 Bad Request: The request is invalid.
  • 403 Forbidden: The caller does not have permission.
  • 412 Precondition Failed: A specified condition for the request failed.

GET Get File

GET /{accountName}/{shareName}/{directory}/{file}

This operation retrieves the contents of a file.

Parameters

Name Type Description Required
range (optional) String Specifies the byte range of the file to retrieve. No
x-ms-lease-id (optional) String Specifies the lease ID if the file is currently leased. No

Common Response Codes

  • 200 OK: The file content was successfully retrieved.
  • 404 Not Found: The file does not exist.
  • 403 Forbidden: The caller does not have permission.

DELETE Delete File

DELETE /{accountName}/{shareName}/{directory}/{file}

This operation deletes a file from the specified share.

Parameters

Name Type Description Required
x-ms-lease-id (optional) String Specifies the lease ID if the file is currently leased. No
x-ms-delete-snapshots (optional) String Specifies whether to delete previous versions of the file. No

Common Response Codes

  • 202 Accepted: The file was successfully deleted.
  • 404 Not Found: The file does not exist.
  • 403 Forbidden: The caller does not have permission.

Directory REST Operations

This section details the operations available for managing directories within an Azure Files share.

PUT Create Directory

PUT /{accountName}/{shareName}/{directory}

This operation creates a new directory in the specified share. If the directory already exists, the operation fails.

Parameters

Name Type Description Required
x-ms-lease-id (optional) String Specifies the lease ID if the directory is currently leased. No

Common Response Codes

  • 201 Created: The directory was successfully created.
  • 409 Conflict: The directory already exists.
  • 403 Forbidden: The caller does not have permission.

GET List Directories and Files

GET /{accountName}/{shareName}/{directory}

This operation lists the directories and files within a specified directory. If the specified directory is the root directory, this operation lists the contents of the root directory.

Parameters

Name Type Description Required
recursive (optional) Boolean Specifies whether to recursively list the contents of subdirectories. No
x-ms-properties (optional) String Specifies which properties to return for each item. No

Common Response Codes

  • 200 OK: The listing was successful.
  • 404 Not Found: The directory does not exist.
  • 403 Forbidden: The caller does not have permission.

DELETE Delete Directory

DELETE /{accountName}/{shareName}/{directory}

This operation deletes the specified directory. The directory must be empty before it can be deleted.

Parameters

Name Type Description Required
x-ms-lease-id (optional) String Specifies the lease ID if the directory is currently leased. No
recursive (optional) Boolean If true, deletes the directory and all its contents recursively. No

Common Response Codes

  • 202 Accepted: The directory was successfully deleted.
  • 404 Not Found: The directory does not exist.
  • 409 Conflict: The directory is not empty.
  • 403 Forbidden: The caller does not have permission.

Share REST Operations

This section details the operations available for managing Azure Files shares.

PUT Create Share

PUT /{accountName}/{shareName}

This operation creates a new share within the specified storage account.

Parameters

Name Type Description Required
x-ms-share-quota (optional) Integer Specifies the maximum size of the share in GiB. No

Common Response Codes

  • 201 Created: The share was successfully created.
  • 409 Conflict: The share already exists.
  • 403 Forbidden: The caller does not have permission.

GET List Shares

GET /{accountName}

This operation lists all shares within the specified storage account.

Parameters

Name Type Description Required
include (optional) String Specifies to include snapshots when listing shares. No

Common Response Codes

  • 200 OK: The listing was successful.
  • 403 Forbidden: The caller does not have permission.

DELETE Delete Share

DELETE /{accountName}/{shareName}

This operation deletes the specified share and all data within it.

Parameters

Name Type Description Required
x-ms-delete-snapshots (optional) String Specifies whether to delete previous versions of the share. No

Common Response Codes

  • 202 Accepted: The share was successfully deleted.
  • 404 Not Found: The share does not exist.
  • 403 Forbidden: The caller does not have permission.

Authentication

All Azure Storage REST API requests must be authenticated. Authentication can be achieved using one of the following methods:

  • Shared Key Authentication: Use your storage account name and account key.
  • Shared Access Signature (SAS) Token: A token that grants delegated access to Azure Storage resources.
  • Azure Active Directory (Azure AD): For more secure and integrated authentication.

For detailed information on authentication, please refer to the Azure Storage Authentication documentation.

Common Headers

The following headers are commonly used in Azure Storage File REST API requests:

Header Description
x-ms-version Specifies the version of the REST API to use.
Authorization Contains credentials for authentication.
x-ms-date The UTC date and time of the request.
Content-Length The length of the request body in bytes.
Content-Type The MIME type of the request body.