az storage file

Manage file shares that use the SMB 3.0 protocol.

Commands

az storage file copy Manage file copy operations.
az storage file copy cancel Aborts a pending copy_file operation, and leaves a destination file with zero length and full metadata.
az storage file copy start Copies a file asynchronously.
az storage file copy start-batch Copy multiple files or blobs to a file share.
az storage file delete Marks the specified file for deletion.
az storage file delete-batch Delete files from an Azure Storage File Share.
az storage file download Downloads a file to a file path, with automatic chunking and progress notifications.
az storage file download-batch Download files from an Azure Storage File Share to a local directory in a batch operation.
az storage file exists Check for the existence of a file.
az storage file generate-sas Generates a shared access signature for the file.
az storage file list List files and directories in a share.
az storage file metadata Manage file metadata.
az storage file metadata show Returns all user-defined metadata for the specified file.
az storage file metadata update Sets user-defined metadata for the specified file as one or more name-value pairs.
az storage file resize Resizes a file to the specified size.
az storage file show Returns all user-defined metadata, standard HTTP properties, and system properties for the file.
az storage file update Sets system properties on the file.
az storage file upload Upload a file to a share that uses the SMB 3.0 protocol.
az storage file upload-batch Upload files from a local directory to an Azure Storage File Share in a batch operation.
az storage file url Creates the url to access a file.

az storage file delete

Marks the specified file for deletion.

The file is later deleted during garbage collection.

az storage file delete --path
--share-name
[--account-key]
[--account-name]
[--connection-string]
[--sas-token]
[--timeout]

Required Parameters

--path -p

The path to the file within the file share.

--share-name -s

The file share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--timeout

Request timeout in seconds. Applies to each call to the service.

az storage file delete-batch

Delete files from an Azure Storage File Share.

az storage file delete-batch --source
[--account-key]
[--account-name]
[--connection-string]
[--dryrun]
[--pattern]
[--sas-token]
[--timeout]

Required Parameters

--source -s

The source of the file delete operation. The source can be the file share URL or the share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--dryrun

List the files and blobs to be deleted. No actual data deletion will occur.

--pattern

The pattern used for file globbing. The supported patterns are '*', '?', '[seq]', and '[!seq]'.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--timeout

Request timeout in seconds. Applies to each call to the service.

az storage file download

Downloads a file to a file path, with automatic chunking and progress notifications.

Returns an instance of File with properties and metadata.

az storage file download --path
--share-name
[--account-key]
[--account-name]
[--connection-string]
[--dest]
[--end-range]
[--max-connections]
[--open-mode]
[--sas-token]
[--snapshot]
[--start-range]
[--timeout]
[--validate-content]

Required Parameters

--path -p

The path to the file within the file share.

--share-name -s

The file share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--dest

Path of the file to write to. The source filename will be used if not specified.

--end-range

End of byte range to use for downloading a section of the file. If end_range is given, start_range must be provided. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file.

--max-connections

If set to 2 or greater, an initial get will be done for the first self.MAX_SINGLE_GET_SIZE bytes of the file. If this is the entire file, the method returns at this point. If it is not, it will download the remaining data parallel using the number of threads equal to max_connections. Each chunk will be of size self.MAX_CHUNK_GET_SIZE. If set to 1, a single large get request will be done. This is not generally recommended but available if very few threads should be used, network requests are very expensive, or a non-seekable stream prevents parallel download. This may also be valuable if the file is being concurrently modified to enforce atomicity or if many files are expected to be empty as an extra request is required for empty files if max_connections is greater than 1.

default value: 2
--open-mode

Mode to use when opening the file. Note that specifying append only open_mode prevents parallel download. So, max_connections must be set to 1 if this open_mode is used.

default value: wb
--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--snapshot

A string that represents the snapshot version, if applicable.

--start-range

Start of byte range to use for downloading a section of the file. If no end_range is given, all bytes after the start_range will be downloaded. The start_range and end_range params are inclusive. Ex: start_range=0, end_range=511 will download first 512 bytes of file.

--timeout

Request timeout in seconds. Applies to each call to the service.

--validate-content

If set to true, validates an MD5 hash for each retrieved portion of the file. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that the service will only return transactional MD5s for chunks 4MB or less so the first get request will be of size self.MAX_CHUNK_GET_SIZE instead of self.MAX_SINGLE_GET_SIZE. If self.MAX_CHUNK_GET_SIZE was set to greater than 4MB an error will be thrown. As computing the MD5 takes processing time and more requests will need to be done due to the reduced chunk size there may be some increase in latency.

az storage file download-batch

Download files from an Azure Storage File Share to a local directory in a batch operation.

az storage file download-batch --destination
--source
[--account-key]
[--account-name]
[--connection-string]
[--dryrun]
[--max-connections]
[--pattern]
[--sas-token]
[--validate-content]

Required Parameters

--destination -d

The local directory where the files are downloaded to. This directory must already exist.

--source -s

The source of the file download operation. The source can be the file share URL or the share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--dryrun

List the files and blobs to be downloaded. No actual data transfer will occur.

--max-connections

The maximum number of parallel connections to use. Default value is 1.

default value: 1
--pattern

The pattern used for file globbing. The supported patterns are '*', '?', '[seq]', and '[!seq]'.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--validate-content

If set, calculates an MD5 hash for each range of the file for validation.

az storage file exists

Check for the existence of a file.

az storage file exists --path
--share-name
[--account-key]
[--account-name]
[--connection-string]
[--sas-token]
[--snapshot]
[--timeout]

Required Parameters

--path -p

The path to the file within the file share.

--share-name -s

The file share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--snapshot

A string that represents the snapshot version, if applicable.

--timeout

Request timeout in seconds. Applies to each call to the service.

az storage file generate-sas

Generates a shared access signature for the file.

Use the returned signature with the sas_token parameter of FileService.

az storage file generate-sas --path
--share-name
[--account-key]
[--account-name]
[--cache-control]
[--connection-string]
[--content-disposition]
[--content-encoding]
[--content-language]
[--content-type]
[--expiry]
[--https-only]
[--ip]
[--permissions]
[--policy-name]
[--sas-token]
[--start]

Required Parameters

--path -p

The path to the file within the file share.

--share-name -s

The file share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--cache-control

Response header value for Cache-Control when resource is accessed using this shared access signature.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--content-disposition

Response header value for Content-Disposition when resource is accessed using this shared access signature.

--content-encoding

Response header value for Content-Encoding when resource is accessed using this shared access signature.

--content-language

Response header value for Content-Language when resource is accessed using this shared access signature.

--content-type

Response header value for Content-Type when resource is accessed using this shared access signature.

--expiry

Specifies the UTC datetime (Y-m-d'T'H:M'Z') at which the SAS becomes invalid. Do not use if a stored access policy is referenced with --id that specifies this value.

--https-only

Only permit requests made with the HTTPS protocol. If omitted, requests from both the HTTP and HTTPS protocol are permitted.

--ip

Specifies the IP address or range of IP addresses from which to accept requests. Supports only IPv4 style addresses.

--permissions

The permissions the SAS grants. Allowed values: (c)reate (d)elete (r)ead (w)rite. Do not use if a stored access policy is referenced with --id that specifies this value. Can be combined.

--policy-name

The name of a stored access policy within the share's ACL.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--start

Specifies the UTC datetime (Y-m-d'T'H:M'Z') at which the SAS becomes valid. Do not use if a stored access policy is referenced with --id that specifies this value. Defaults to the time of the request.

az storage file list

List files and directories in a share.

az storage file list --share-name
[--account-key]
[--account-name]
[--connection-string]
[--exclude-dir]
[--path]
[--sas-token]
[--snapshot]
[--timeout]

Required Parameters

--share-name -s

The file share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--exclude-dir

List only files in the given share.

--path -p

The directory path within the file share.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--snapshot

A string that represents the snapshot version, if applicable.

--timeout

Request timeout in seconds. Applies to each call to the service.

az storage file resize

Resizes a file to the specified size.

If the specified byte value is less than the current size of the file, then all ranges above the specified byte value are cleared.

az storage file resize --path
--share-name
--size
[--account-key]
[--account-name]
[--connection-string]
[--sas-token]
[--timeout]

Required Parameters

--path -p

The path to the file within the file share.

--share-name -s

The file share name.

--size

The length to resize the file to.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--timeout

Request timeout in seconds. Applies to each call to the service.

az storage file show

Returns all user-defined metadata, standard HTTP properties, and system properties for the file.

Returns an instance of File with FileProperties and a metadata dict.

az storage file show --path
--share-name
[--account-key]
[--account-name]
[--connection-string]
[--sas-token]
[--snapshot]
[--timeout]

Required Parameters

--path -p

The path to the file within the file share.

--share-name -s

The file share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--snapshot

A string that represents the snapshot version, if applicable.

--timeout

Request timeout in seconds. Applies to each call to the service.

az storage file update

Sets system properties on the file.

If one property is set for the content_settings, all properties will be overriden.

az storage file update --path
--share-name
[--account-key]
[--account-name]
[--connection-string]
[--content-cache-control]
[--content-disposition]
[--content-encoding]
[--content-language]
[--content-md5]
[--content-type]
[--sas-token]
[--timeout]

Required Parameters

--path -p

The path to the file within the file share.

--share-name -s

The file share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--content-cache-control

The cache control string.

--content-disposition

Conveys additional information about how to process the response payload, and can also be used to attach additional metadata.

--content-encoding

The content encoding type.

--content-language

The content language.

--content-md5

The content's MD5 hash.

--content-type

The content MIME type.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--timeout

Request timeout in seconds. Applies to each call to the service.

az storage file upload

Upload a file to a share that uses the SMB 3.0 protocol.

Creates or updates an Azure file from a source path with automatic chunking and progress notifications.

az storage file upload --share-name
--source
[--account-key]
[--account-name]
[--connection-string]
[--content-cache-control]
[--content-disposition]
[--content-encoding]
[--content-language]
[--content-md5]
[--content-type]
[--max-connections]
[--metadata]
[--path]
[--sas-token]
[--timeout]
[--validate-content]

Examples

Upload to a local file to a share.

az storage file upload -s MyShare -source /path/to/file

Required Parameters

--share-name -s

The file share name.

--source

Path of the local file to upload as the file content.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--content-cache-control

The cache control string.

--content-disposition

Conveys additional information about how to process the response payload, and can also be used to attach additional metadata.

--content-encoding

The content encoding type.

--content-language

The content language.

--content-md5

The content's MD5 hash.

--content-type

The content MIME type.

--max-connections

Maximum number of parallel connections to use.

default value: 2
--metadata

Metadata in space-separated key=value pairs. This overwrites any existing metadata.

--path -p

The path to the file within the file share. If the file name is omitted, the source file name will be used.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--timeout

Request timeout in seconds. Applies to each call to the service.

--validate-content

If true, calculates an MD5 hash for each range of the file. The storage service checks the hash of the content that has arrived with the hash that was sent. This is primarily valuable for detecting bitflips on the wire if using http instead of https as https (the default) will already validate. Note that this MD5 hash is not stored with the file.

az storage file upload-batch

Upload files from a local directory to an Azure Storage File Share in a batch operation.

az storage file upload-batch --destination
--source
[--account-key]
[--account-name]
[--connection-string]
[--content-cache-control]
[--content-disposition]
[--content-encoding]
[--content-language]
[--content-md5]
[--content-type]
[--dryrun]
[--max-connections]
[--metadata]
[--pattern]
[--sas-token]
[--validate-content]

Required Parameters

--destination -d

The destination of the upload operation.

--source -s

The directory to upload files from.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--content-cache-control

The cache control string.

--content-disposition

Conveys additional information about how to process the response payload, and can also be used to attach additional metadata.

--content-encoding

The content encoding type.

--content-language

The content language.

--content-md5

The content's MD5 hash.

--content-type

The content MIME type.

--dryrun

List the files and blobs to be uploaded. No actual data transfer will occur.

--max-connections

The maximum number of parallel connections to use. Default value is 1.

default value: 1
--metadata

Metadata in space-separated key=value pairs. This overwrites any existing metadata.

--pattern

The pattern used for file globbing. The supported patterns are '*', '?', '[seq', and '[!seq]'.

--sas-token

A Shared Access Signature (SAS). Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_SAS_TOKEN.

--validate-content

If set, calculates an MD5 hash for each range of the file for validation.

az storage file url

Creates the url to access a file.

az storage file url --path
--share-name
[--account-key]
[--account-name]
[--connection-string]
[--protocol {http, https}]
[--sas-token]

Required Parameters

--path -p

The path to the file within the file share.

--share-name -s

The file share name.

Optional Parameters

--account-key

Storage account key. Must be used in conjunction with storage account name. Environment variable: AZURE_STORAGE_KEY.

--account-name

Storage account name. Related environment variable: AZURE_STORAGE_ACCOUNT. Must be used in conjunction with either storage account key or a SAS token. If neither are present, the command will try to query the storage account key using the authenticated Azure account. If a large number of storage commands are executed the API quota may be hit.

--connection-string

Storage account connection string. Environment variable: AZURE_STORAGE_CONNECTION_STRING.

--protocol

Protocol to use.

accepted values: http, https
default value: https
--sas-token

Shared access signature token created with generate_shared_access_signature.