ShareClient class
Definition
A client to interact with a specific share, although that share may not yet exist.
For operations relating to a specific directory or file in this share, the clients for those entities can also be retrieved using the get_directory_client(directory_path=None) and get_file_client(file_path) functions.
ShareClient(account_url, share_name, snapshot=None, credential=None, **kwargs)
- Inheritance
-
builtins.objectazure.storage.fileshare._shared.base_client_async.AsyncStorageAccountHostsMixinShareClientazure.storage.fileshare._shared.base_client.StorageAccountHostsMixinazure.storage.fileshare._share_client.ShareClientShareClient
Parameters
- account_url
- str
The URI to the storage account. In order to create a client given the full URI to the share, use the <xref:azure.storage.fileshare.aio.from_share_url> classmethod.
- share_name
- str
The name of the share with which to interact.
- snapshot
- str
An optional share snapshot on which to operate. This can be the snapshot ID string or the response returned from create_snapshot(**kwargs).
- credential
The credential with which to authenticate. This is optional if the account URL already has a SAS token. The value can be a SAS token string or an account shared access key.
Methods
| create_directory |
Creates a directory in the share and returns a client to interact with the directory. |
| create_permission_for_share |
Create a permission (a security descriptor) at the share level. This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key. |
| create_share |
Creates a new Share under the account. If a share with the same name already exists, the operation fails. |
| create_snapshot |
Creates a snapshot of the share. A snapshot is a read-only version of a share that's taken at a point in time. It can be read, copied, or deleted, but not modified. Snapshots provide a way to back up a share as it appears at a moment in time. A snapshot of a share has the same name as the base share from which the snapshot is taken, with a DateTime value appended to indicate the time at which the snapshot was taken. |
| delete_directory |
Marks the directory for deletion. The directory is later deleted during garbage collection. |
| delete_share |
Marks the specified share for deletion. The share is later deleted during garbage collection. |
| get_directory_client |
Get a client to interact with the specified directory. The directory need not already exist. |
| get_file_client |
Get a client to interact with the specified file. The file need not already exist. |
| get_permission_for_share |
Get a permission (a security descriptor) for a given key. This 'permission' can be used for the files/directories in the share. |
| get_share_access_policy |
Gets the permissions for the share. The permissions indicate whether files in a share may be accessed publicly. |
| get_share_properties |
Returns all user-defined metadata and system properties for the specified share. The data returned does not include the shares's list of files or directories. |
| get_share_stats |
Gets the approximate size of the data stored on the share in bytes. Note that this value may not include all recently created or recently re-sized files. |
| list_directories_and_files |
Lists the directories and files under the share. |
| set_share_access_policy |
Sets the permissions for the share, or stored access policies that may be used with Shared Access Signatures. The permissions indicate whether files in a share may be accessed publicly. |
| set_share_metadata |
Sets the metadata for the share. Each call to this operation replaces all existing metadata attached to the share. To remove all metadata from the share, call this operation with no metadata dict. |
| set_share_quota |
Sets the quota for the share. |
create_directory
Creates a directory in the share and returns a client to interact with the directory.
create_directory(directory_name, **kwargs)
Parameters
- directory_name
- str
The name of the directory.
Returns
ShareDirectoryClient
Return type
create_permission_for_share
Create a permission (a security descriptor) at the share level.
This 'permission' can be used for the files/directories in the share. If a 'permission' already exists, it shall return the key of it, else creates a new permission at the share level and return its key.
create_permission_for_share(file_permission, **kwargs)
Parameters
- file_permission
- str
File permission, a Portable SDDL
Returns
A file permission key
Return type
create_share
Creates a new Share under the account. If a share with the same name already exists, the operation fails.
create_share(**kwargs)
Returns
Share-updated property dict (Etag and last modified).
Return type
Examples
Creates a file share.
await share.create_share()
create_snapshot
Creates a snapshot of the share.
A snapshot is a read-only version of a share that's taken at a point in time. It can be read, copied, or deleted, but not modified. Snapshots provide a way to back up a share as it appears at a moment in time.
A snapshot of a share has the same name as the base share from which the snapshot is taken, with a DateTime value appended to indicate the time at which the snapshot was taken.
create_snapshot(**kwargs)
Returns
Share-updated property dict (Snapshot ID, Etag, and last modified).
Return type
Examples
Creates a snapshot of the file share.
await share.create_snapshot()
delete_directory
Marks the directory for deletion. The directory is later deleted during garbage collection.
delete_directory(directory_name, **kwargs)
Parameters
- directory_name
- str
The name of the directory.
Return type
delete_share
Marks the specified share for deletion. The share is later deleted during garbage collection.
delete_share(delete_snapshots=False, **kwargs)
Parameters
- delete_snapshots
- bool
Indicates if snapshots are to be deleted.
Return type
Examples
Deletes the share and any snapshots.
await share.delete_share(delete_snapshots=True)
get_directory_client
Get a client to interact with the specified directory. The directory need not already exist.
get_directory_client(directory_path=None)
Parameters
- directory_path
- str
Path to the specified directory.
Returns
A Directory Client.
Return type
get_file_client
Get a client to interact with the specified file. The file need not already exist.
get_file_client(file_path)
Parameters
- file_path
- str
Path to the specified file.
Returns
A File Client.
Return type
get_permission_for_share
Get a permission (a security descriptor) for a given key.
This 'permission' can be used for the files/directories in the share.
get_permission_for_share(permission_key, **kwargs)
Parameters
- permission_key
- str
Key of the file permission to retrieve
Returns
A file permission (a portable SDDL)
Return type
get_share_access_policy
Gets the permissions for the share. The permissions indicate whether files in a share may be accessed publicly.
get_share_access_policy(**kwargs)
Returns
Access policy information in a dict.
Return type
get_share_properties
Returns all user-defined metadata and system properties for the specified share. The data returned does not include the shares's list of files or directories.
get_share_properties(**kwargs)
Returns
The share properties.
Return type
Examples
Gets the share properties.
properties = await share.get_share_properties()
get_share_stats
Gets the approximate size of the data stored on the share in bytes.
Note that this value may not include all recently created or recently re-sized files.
get_share_stats(**kwargs)
Returns
The approximate size of the data (in bytes) stored on the share.
Return type
list_directories_and_files
Lists the directories and files under the share.
list_directories_and_files(directory_name=None, name_starts_with=None, marker=None, **kwargs)
Parameters
- directory_name
- str
Name of a directory.
- name_starts_with
- str
Filters the results to return only directories whose names begin with the specified prefix.
- marker
- str
An opaque continuation token. This value can be retrieved from the next_marker field of a previous generator object. If specified, this generator will begin returning results from this point.
Returns
An auto-paging iterable of dict-like DirectoryProperties and FileProperties
Examples
List directories and files in the share.
# Create a directory in the share
dir_client = await share.create_directory("mydir")
# Upload a file to the directory
with open(SOURCE_FILE, "rb") as source_file:
await dir_client.upload_file(file_name="sample", data=source_file)
# List files in the directory
my_files = []
async for item in share.list_directories_and_files(directory_name="mydir"):
my_files.append(item)
print(my_files)
set_share_access_policy
Sets the permissions for the share, or stored access policies that may be used with Shared Access Signatures. The permissions indicate whether files in a share may be accessed publicly.
set_share_access_policy(signed_identifiers, **kwargs)
Parameters
- signed_identifiers
- dict(str, AccessPolicy)
A dictionary of access policies to associate with the share. The dictionary may contain up to 5 elements. An empty dictionary will clear the access policies set on the service.
Returns
Share-updated property dict (Etag and last modified).
Return type
set_share_metadata
Sets the metadata for the share.
Each call to this operation replaces all existing metadata attached to the share. To remove all metadata from the share, call this operation with no metadata dict.
set_share_metadata(metadata, **kwargs)
Parameters
- metadata
- dict(str, str)
Name-value pairs associated with the share as metadata.
Returns
Share-updated property dict (Etag and last modified).
Return type
Examples
Sets the share metadata.
data = {'category': 'test'}
await share.set_share_metadata(metadata=data)
set_share_quota
Sets the quota for the share.
set_share_quota(quota, **kwargs)
Parameters
- quota
- int
Specifies the maximum size of the share, in gigabytes. Must be greater than 0, and less than or equal to 5TB.
Returns
Share-updated property dict (Etag and last modified).
Return type
Examples
Sets the share quota.
# Set the quota for the share to 1GB
await share.set_share_quota(quota=1)