@azure/storage-file-share
Version:
Microsoft Azure Storage SDK for JavaScript - File
1,086 lines • 140 kB
TypeScript
import type { TokenCredential } from "@azure/core-auth";
import type { RequestBodyType as HttpRequestBody, TransferProgressEvent } from "@azure/core-rest-pipeline";
import type { AbortSignalLike } from "@azure/abort-controller";
import type { CopyFileSmbInfo, DeleteSnapshotsOptionType, DirectoryCreateResponse, DirectoryDeleteResponse, DirectoryGetPropertiesResponse, DirectoryItem, DirectoryListFilesAndDirectoriesSegmentResponse, DirectoryListHandlesResponse, DirectorySetMetadataResponse, DirectorySetPropertiesResponse, DirectoryForceCloseHandlesHeaders, FileAbortCopyResponse, FileCreateResponse, FileDeleteResponse, FileDownloadResponseModel, FileForceCloseHandlesHeaders, FileGetPropertiesResponse, FileGetRangeListHeaders, FileGetRangeListDiffResponse, FileItem, FileListHandlesResponse, FilePermissionFormat, FileSetHTTPHeadersResponse, FileSetMetadataResponse, FileStartCopyResponse, FileUploadRangeFromURLResponse, FileUploadRangeResponse, HandleItem, LeaseAccessConditions, ModeCopyMode, OwnerCopyMode, RangeModel, ShareCreatePermissionResponse, ShareCreateResponse, ShareCreateSnapshotResponse, ShareDeleteResponse, ShareGetAccessPolicyHeaders, ShareGetPermissionResponse, ShareGetPropertiesResponseModel, ShareGetStatisticsResponseModel, ShareSetAccessPolicyResponse, ShareSetMetadataResponse, ShareSetQuotaResponse, SignedIdentifierModel, SourceModifiedAccessConditions, ShareAccessTier, ShareSetPropertiesResponse, ShareRootSquash, FileRenameResponse, DirectoryRenameResponse, FileLastWrittenMode, SharePermission, FileCreateHardLinkResponse, FileCreateSymbolicLinkResponse, FileGetSymbolicLinkResponse } from "./generatedModels.js";
import type { Pipeline } from "./Pipeline.js";
import type { WithResponse } from "./utils/utils.common.js";
import { Credential } from "@azure/storage-common";
import type { CommonOptions } from "./StorageClient.js";
import { StorageClient } from "./StorageClient.js";
import type { PagedAsyncIterableIterator } from "@azure/core-paging";
import type { Range } from "./Range.js";
import type { CloseHandlesInfo, FileAndDirectoryCreateCommonOptions, FileAndDirectorySetPropertiesCommonOptions, FileHttpHeaders, Metadata, ShareProtocols, HttpAuthorization, ShareClientOptions, ShareClientConfig, FilePosixProperties, TimeNowType } from "./models.js";
import type { ShareSASPermissions } from "./ShareSASPermissions.js";
import type { SASProtocol } from "./SASQueryParameters.js";
import type { SasIPRange } from "./SasIPRange.js";
import type { FileSASPermissions } from "./FileSASPermissions.js";
import { Readable } from "node:stream";
export { ShareClientOptions, ShareClientConfig } from "./models.js";
/**
* Options to configure the {@link ShareClient.create} operation.
*/
export interface ShareCreateOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* A name-value pair to associate with a file storage object.
*/
metadata?: {
[propertyName: string]: string;
};
/**
* Specifies the maximum size of the share, in
* gigabytes.
*/
quota?: number;
/**
* Specifies the access tier of the share. Possible values include: 'TransactionOptimized',
* 'Hot', 'Cool'
*/
accessTier?: ShareAccessTier;
/**
* Supported in version 2020-02-10 and above. Specifies the enabled protocols on the share. If not specified, the default is SMB.
*/
protocols?: ShareProtocols;
/**
* Root squash to set on the share. Only valid for NFS shares. Possible values include:
* 'NoRootSquash', 'RootSquash', 'AllSquash'.
*/
rootSquash?: ShareRootSquash;
/**
* Specifies whether the snapshot virtual directory should be accessible at the root of share mount point when NFS is enabled.
* If not specified, the default is true.
*/
enableSnapshotVirtualDirectoryAccess?: boolean;
/**
* Optional. Boolean. Default if not specified is false. This property enables paid bursting.
*/
paidBurstingEnabled?: boolean;
/**
* Optional. Integer. Default if not specified is the maximum throughput the file share can support. Current maximum for a file share is 10,340 MiB/sec.
*/
paidBurstingMaxBandwidthMibps?: number;
/**
* Optional. Integer. Default if not specified is the maximum IOPS the file share can support. Current maximum for a file share is 102,400 IOPS.
*/
paidBurstingMaxIops?: number;
/**
* Optional. Supported in version 2025-01-05 and later. Only allowed for provisioned v2 file shares.
* Specifies the provisioned number of input/output operations per second (IOPS) of the share. If this is not specified, the provisioned IOPS is set to value calculated based on recommendation formula.
*/
shareProvisionedIops?: number;
/** Optional. Supported in version 2025-01-05 and later. Only allowed for provisioned v2 file shares. Specifies the provisioned bandwidth of the share, in mebibytes per second (MiBps). If this is not specified, the provisioned bandwidth is set to value calculated based on recommendation formula. */
shareProvisionedBandwidthMibps?: number;
}
/**
* Options to configure the {@link ShareClient.delete} operation.
*/
export interface ShareDeleteMethodOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* Specifies the option
* include to delete the base share and all of its snapshots. Possible values
* include: 'include'
*/
deleteSnapshots?: DeleteSnapshotsOptionType;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
}
/**
* Options to configure the {@link ShareClient.setMetadata} operation.
*/
export interface ShareSetMetadataOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
}
/**
* Options to configure the {@link ShareClient.setAccessPolicy} operation.
*/
export interface ShareSetAccessPolicyOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
}
/**
* Options to configure the {@link ShareClient.getAccessPolicy} operation.
*/
export interface ShareGetAccessPolicyOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
}
/**
* Options to configure the {@link ShareClient.exists} operation.
*/
export interface ShareExistsOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
}
/**
* Options to configure the {@link ShareClient.getProperties} operation.
*/
export interface ShareGetPropertiesOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
}
/**
* Options to configure the {@link ShareClient.setQuota} operation.
*/
export interface ShareSetQuotaOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
}
/**
* Options to configure the {@link ShareClient.setProperties} operation.
*/
export interface ShareSetPropertiesOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* Specifies the access tier of the share. Possible values include: 'TransactionOptimized',
* 'Hot', 'Cool'.
*/
accessTier?: ShareAccessTier;
/**
* Specifies the maximum size of the share, in gigabytes.
*/
quotaInGB?: number;
/**
* Root squash to set on the share. Only valid for NFS shares. Possible values include:
* 'NoRootSquash', 'RootSquash', 'AllSquash'.
*/
rootSquash?: ShareRootSquash;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
/**
* Specifies whether the snapshot virtual directory should be accessible at the root of share mount point when NFS is enabled.
* If not specified, the default is true.
*/
enableSnapshotVirtualDirectoryAccess?: boolean;
/**
* Optional. Boolean. Default if not specified is false. This property enables paid bursting.
*/
paidBurstingEnabled?: boolean;
/**
* Optional. Integer. Default if not specified is the maximum throughput the file share can support. Current maximum for a file share is 10,340 MiB/sec.
*/
paidBurstingMaxBandwidthMibps?: number;
/**
* Optional. Integer. Default if not specified is the maximum IOPS the file share can support. Current maximum for a file share is 102,400 IOPS.
*/
paidBurstingMaxIops?: number;
/**
* Optional. Supported in version 2025-01-05 and later. Only allowed for provisioned v2 file shares.
* Specifies the provisioned number of input/output operations per second (IOPS) of the share. If this is not specified, the provisioned IOPS is set to value calculated based on recommendation formula.
*/
shareProvisionedIops?: number;
/** Optional. Supported in version 2025-01-05 and later. Only allowed for provisioned v2 file shares. Specifies the provisioned bandwidth of the share, in mebibytes per second (MiBps). If this is not specified, the provisioned bandwidth is set to value calculated based on recommendation formula. */
shareProvisionedBandwidthMibps?: number;
}
/**
* Options to configure the {@link ShareClient.getStatistics} operation.
*/
export interface ShareGetStatisticsOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* If specified, the operation only succeeds if the resource's lease is active and matches this ID.
*/
leaseAccessConditions?: LeaseAccessConditions;
}
/**
* Signed Identifier
*/
export interface SignedIdentifier {
/**
* a unique id
*/
id: string;
/**
* Access Policy
*/
accessPolicy: {
/**
* the date-time the policy is active.
*/
startsOn: Date;
/**
* the date-time the policy expires.
*/
expiresOn: Date;
/**
* the permissions for the acl policy
* @see https://learn.microsoft.com/rest/api/storageservices/set-share-acl
*/
permissions: string;
};
}
export declare type ShareGetAccessPolicyResponse = WithResponse<{
signedIdentifiers: SignedIdentifier[];
} & ShareGetAccessPolicyHeaders, ShareGetAccessPolicyHeaders, SignedIdentifierModel[]>;
/**
* Options to configure the {@link ShareClient.createSnapshot} operation.
*/
export interface ShareCreateSnapshotOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* A name-value pair to associate with a file storage object.
*/
metadata?: {
[propertyName: string]: string;
};
}
/**
* Options to configure the {@link ShareClient.createPermission} operation.
*/
export interface ShareCreatePermissionOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
}
/**
* Options to configure the {@link ShareClient.getPermission} operation.
*/
export interface ShareGetPermissionOptions extends CommonOptions {
/**
* Optional. Available for version 2023-06-01 and later. Specifies the format in which the permission is returned.
* Acceptable values are SDDL or binary. If x-ms-file-permission-format is unspecified or explicitly set to SDDL, the permission is returned in SDDL format.
* If x-ms-file-permission-format is explicitly set to binary, the permission is returned as a base64 string representing the binary encoding of the permission
*/
filePermissionFormat?: FilePermissionFormat;
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
}
/**
* Response data for the {@link ShareClient.getStatistics} Operation.
*/
export type ShareGetStatisticsResponse = ShareGetStatisticsResponseModel & {
/**
* @deprecated shareUsage is going to be deprecated. Please use ShareUsageBytes instead.
*
* The approximate size of the data stored on the share, rounded up to the nearest gigabyte. Note
* that this value may not include all recently created or recently resized files.
*/
shareUsage: number;
};
/**
* Contains response data for the {@link ShareClient.createIfNotExists} operation.
*/
export interface ShareCreateIfNotExistsResponse extends ShareCreateResponse {
/**
* Indicate whether the share is successfully created. Is false when the share is not changed as it already exists.
*/
succeeded: boolean;
}
/**
* Contains response data for the {@link ShareClient.deleteIfExists} operation.
*/
export interface ShareDeleteIfExistsResponse extends ShareDeleteResponse {
/**
* Indicate whether the share is successfully deleted. Is false if the share does not exist in the first place.
*/
succeeded: boolean;
}
/**
* Contains response data for the {@link ShareClient.getProperties} operation.
*/
export type ShareGetPropertiesResponse = ShareGetPropertiesResponseModel & {
/**
* The protocols that have been enabled on the share.
*/
protocols?: ShareProtocols;
};
/**
* Common options of the {@link ShareGenerateSasUrlOptions} and {@link FileGenerateSasUrlOptions}.
*/
export interface CommonGenerateSasUrlOptions {
/**
* The version of the service this SAS will target. If not specified, it will default to the version targeted by the
* library.
*/
version?: string;
/**
* Optional. SAS protocols, HTTPS only or HTTPSandHTTP
*/
protocol?: SASProtocol;
/**
* Optional. When the SAS will take effect.
*/
startsOn?: Date;
/**
* Optional only when identifier is provided. The time after which the SAS will no longer work.
*/
expiresOn?: Date;
/**
* Optional. IP ranges allowed in this SAS.
*/
ipRange?: SasIPRange;
/**
* Optional. The name of the access policy on the share this SAS references if any.
*
* @see https://learn.microsoft.com/rest/api/storageservices/establishing-a-stored-access-policy
*/
identifier?: string;
/**
* Optional. The cache-control header for the SAS.
*/
cacheControl?: string;
/**
* Optional. The content-disposition header for the SAS.
*/
contentDisposition?: string;
/**
* Optional. The content-encoding header for the SAS.
*/
contentEncoding?: string;
/**
* Optional. The content-language header for the SAS.
*/
contentLanguage?: string;
/**
* Optional. The content-type header for the SAS.
*/
contentType?: string;
}
/**
* Options to configure {@link ShareClient.generateSasUrl} operation.
*/
export interface ShareGenerateSasUrlOptions extends CommonGenerateSasUrlOptions {
/**
* Optional only when identifier is provided. Specifies the list of permissions to be associated with the SAS.
*/
permissions?: ShareSASPermissions;
}
/**
* A ShareClient represents a URL to the Azure Storage share allowing you to manipulate its directories and files.
*/
export declare class ShareClient extends StorageClient {
/**
* Share operation context provided by protocol layer.
*/
private context;
private _name;
private shareClientConfig?;
/**
* The name of the share
*/
get name(): string;
/**
* @param connectionString - Account connection string or a SAS connection string of an Azure storage account.
* [ Note - Account connection string can only be used in NODE.JS runtime. ]
* Account connection string example -
* `DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=accountKey;EndpointSuffix=core.windows.net`
* SAS connection string example -
* `BlobEndpoint=https://myaccount.blob.core.windows.net/;QueueEndpoint=https://myaccount.queue.core.windows.net/;FileEndpoint=https://myaccount.file.core.windows.net/;TableEndpoint=https://myaccount.table.core.windows.net/;SharedAccessSignature=sasString`
* @param name - Share name.
* @param options - Optional. Options to configure the HTTP pipeline.
*/
constructor(connectionString: string, name: string, options?: ShareClientOptions);
/**
* Creates an instance of ShareClient.
*
* @param url - A URL string pointing to Azure Storage file share, such as
* "https://myaccount.file.core.windows.net/share". You can
* append a SAS if using AnonymousCredential, such as
* "https://myaccount.file.core.windows.net/share?sasString".
* @param credential - Such as AnonymousCredential or StorageSharedKeyCredential.
* If not specified, AnonymousCredential is used.
* @param options - Optional. Options to configure the HTTP pipeline.
*/
constructor(url: string, credential?: Credential | TokenCredential, options?: ShareClientOptions);
/**
* Creates an instance of ShareClient.
*
* @param url - A URL string pointing to Azure Storage file share, such as
* "https://myaccount.file.core.windows.net/share". You can
* append a SAS if using AnonymousCredential, such as
* "https://myaccount.file.core.windows.net/share?sasString".
* @param pipeline - Call newPipeline() to create a default
* pipeline, or provide a customized pipeline.
*/
constructor(url: string, pipeline: Pipeline, options?: ShareClientConfig);
/**
* Creates a new ShareClient object identical to the source but with the specified snapshot timestamp.
* Provide "" will remove the snapshot and return a URL to the base share.
*
* @param snapshot - The snapshot timestamp.
* @returns A new ShareClient object identical to the source but with the specified snapshot timestamp
*/
withSnapshot(snapshot: string): ShareClient;
/**
* Creates a new share under the specified account. If the share with
* the same name already exists, the operation fails.
* @see https://learn.microsoft.com/rest/api/storageservices/create-share
*
* @param options - Options to Share Create operation.
* @returns Response data for the Share Create operation.
*/
create(options?: ShareCreateOptions): Promise<ShareCreateResponse>;
/**
* Creates a new share under the specified account. If the share with
* the same name already exists, it is not changed.
* @see https://learn.microsoft.com/rest/api/storageservices/create-share
*
* @param options -
*/
createIfNotExists(options?: ShareCreateOptions): Promise<ShareCreateIfNotExistsResponse>;
/**
* Creates a {@link ShareDirectoryClient} object.
*
* @param directoryName - A directory name
* @returns The ShareDirectoryClient object for the given directory name.
*/
getDirectoryClient(directoryName: string): ShareDirectoryClient;
/**
* Gets the directory client for the root directory of this share.
* Note that the root directory always exists and cannot be deleted.
*
* @readonly A new ShareDirectoryClient object for the root directory.
*/
get rootDirectoryClient(): ShareDirectoryClient;
/**
* Creates a new subdirectory under this share.
* @see https://learn.microsoft.com/rest/api/storageservices/create-directory
*
* @param directoryName -
* @param options - Options to Directory Create operation.
* @returns Directory creation response data and the corresponding directory client.
*/
createDirectory(directoryName: string, options?: DirectoryCreateOptions): Promise<{
directoryClient: ShareDirectoryClient;
directoryCreateResponse: DirectoryCreateResponse;
}>;
/**
* Removes the specified empty sub directory under this share.
* Note that the directory must be empty before it can be deleted.
* @see https://learn.microsoft.com/rest/api/storageservices/delete-directory
*
* @param directoryName -
* @param options - Options to Directory Delete operation.
* @returns Directory deletion response data.
*/
deleteDirectory(directoryName: string, options?: DirectoryDeleteOptions): Promise<DirectoryDeleteResponse>;
/**
* Creates a new file or replaces a file under the root directory of this share.
* Note it only initializes the file with no content.
* @see https://learn.microsoft.com/rest/api/storageservices/create-file
*
* @param fileName -
* @param size - Specifies the maximum size in bytes for the file, up to 4 TB.
* @param options - Options to File Create operation.
* @returns File creation response data and the corresponding file client.
*/
createFile(fileName: string, size: number, options?: FileCreateOptions): Promise<{
fileClient: ShareFileClient;
fileCreateResponse: FileCreateResponse;
}>;
/**
* Removes a file under the root directory of this share from the storage account.
* When a file is successfully deleted, it is immediately removed from the storage
* account's index and is no longer accessible to clients. The file's data is later
* removed from the service during garbage collection.
*
* Delete File will fail with status code 409 (Conflict) and error code `SharingViolation`
* if the file is open on an SMB client.
*
* Delete File is not supported on a share snapshot, which is a read-only copy of
* a share. An attempt to perform this operation on a share snapshot will fail with 400
* (`InvalidQueryParameterValue`)
*
* @see https://learn.microsoft.com/rest/api/storageservices/delete-file2
*
* @param directoryName -
* @param fileName -
* @param options - Options to File Delete operation.
* @returns Promise<FileDeleteResponse> File Delete response data.
*/
deleteFile(fileName: string, options?: FileDeleteOptions): Promise<FileDeleteResponse>;
/**
* Returns true if the Azrue share resource represented by this client exists; false otherwise.
*
* NOTE: use this function with care since an existing share might be deleted by other clients or
* applications. Vice versa new shares might be added by other clients or applications after this
* function completes.
*
* @param options - options to Exists operation.
*/
exists(options?: ShareExistsOptions): Promise<boolean>;
/**
* Returns all user-defined metadata and system properties for the specified
* share.
* @see https://learn.microsoft.com/rest/api/storageservices/get-share-properties
*
* WARNING: The `metadata` object returned in the response will have its keys in lowercase, even if
* they originally contained uppercase characters. This differs from the metadata keys returned by
* the `listShares` method of {@link ShareServiceClient} using the `includeMetadata` option, which
* will retain their original casing.
*
* @returns Response data for the Share Get Properties operation.
*/
getProperties(options?: ShareGetPropertiesOptions): Promise<ShareGetPropertiesResponse>;
/**
* Marks the specified share for deletion. The share and any directories or files
* contained within it are later deleted during garbage collection.
* @see https://learn.microsoft.com/rest/api/storageservices/delete-share
*
* @param options - Options to Share Delete operation.
* @returns Response data for the Share Delete operation.
*/
delete(options?: ShareDeleteMethodOptions): Promise<ShareDeleteResponse>;
/**
* Marks the specified share for deletion if it exists. The share and any directories or files
* contained within it are later deleted during garbage collection.
* @see https://learn.microsoft.com/rest/api/storageservices/delete-share
*
* @param options -
*/
deleteIfExists(options?: ShareDeleteMethodOptions): Promise<ShareDeleteIfExistsResponse>;
/**
* Sets one or more user-defined name-value pairs for the specified share.
*
* If no option provided, or no metadata defined in the option parameter, the share
* metadata will be removed.
* @see https://learn.microsoft.com/rest/api/storageservices/set-share-metadata
*
* @param metadata - If no metadata provided, all existing directory metadata will be removed.
* @param option - Options to Share Set Metadata operation.
* @returns Response data for the Share Set Metadata operation.
*/
setMetadata(metadata?: Metadata, options?: ShareSetMetadataOptions): Promise<ShareSetMetadataResponse>;
/**
* Gets the permissions for the specified share. The permissions indicate
* whether share data may be accessed publicly.
*
* WARNING: JavaScript Date will potential lost precision when parsing start and expiry string.
* For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z".
*
* @see https://learn.microsoft.com/rest/api/storageservices/get-share-acl
*
* @param option - Options to Share Get Access Policy operation.
* @returns Response data for the Share Get Access Policy operation.
*/
getAccessPolicy(options?: ShareGetAccessPolicyOptions): Promise<ShareGetAccessPolicyResponse>;
/**
* Sets the permissions for the specified share. The permissions indicate
* whether directories or files in a share may be accessed publicly.
*
* When you set permissions for a share, the existing permissions are replaced.
* If no shareAcl provided, the existing share ACL will be
* removed.
*
* When you establish a stored access policy on a share, it may take up to 30 seconds to take effect.
* During this interval, a shared access signature that is associated with the stored access policy will
* fail with status code 403 (Forbidden), until the access policy becomes active.
* @see https://learn.microsoft.com/rest/api/storageservices/set-share-acl
*
* @param shareAcl - Array of signed identifiers, each having a unique Id and details of access policy.
* @param option - Options to Share Set Access Policy operation.
* @returns Response data for the Share Set Access Policy operation.
*/
setAccessPolicy(shareAcl?: SignedIdentifier[], options?: ShareSetAccessPolicyOptions): Promise<ShareSetAccessPolicyResponse>;
/**
* Creates a read-only snapshot of a share.
*
* @param options - Options to Share Create Snapshot operation.
* @returns Response data for the Share Create Snapshot operation.
*/
createSnapshot(options?: ShareCreateSnapshotOptions): Promise<ShareCreateSnapshotResponse>;
/**
* Sets quota for the specified share.
*
* @deprecated Use {@link ShareClient.setProperties} instead.
*
* @param quotaInGB - Specifies the maximum size of the share in gigabytes
* @param option - Options to Share Set Quota operation.
* @returns Response data for the Share Get Quota operation.
*/
setQuota(quotaInGB: number, options?: ShareSetQuotaOptions): Promise<ShareSetQuotaResponse>;
/**
* Sets properties of the share.
*
* @param option - Options to Share Set Properties operation.
* @returns Response data for the Share Set Properties operation.
*/
setProperties(options?: ShareSetPropertiesOptions): Promise<ShareSetPropertiesResponse>;
/**
* Retrieves statistics related to the share.
*
* @param option - Options to Share Get Statistics operation.
* @returns Response data for the Share Get Statistics operation.
*/
getStatistics(options?: ShareGetStatisticsOptions): Promise<ShareGetStatisticsResponse>;
/**
* Creates a file permission (a security descriptor) at the share level.
* The created security descriptor can be used for the files/directories in the share.
* @see https://learn.microsoft.com/rest/api/storageservices/create-permission
*
* @param options - Options to Share Create Permission operation.
* @param filePermission - File permission described in the SDDL
*/
createPermission(filePermission: string | SharePermission, options?: ShareCreatePermissionOptions): Promise<ShareCreatePermissionResponse>;
/**
* Gets the Security Descriptor Definition Language (SDDL) for a given file permission key
* which indicates a security descriptor.
* @see https://learn.microsoft.com/rest/api/storageservices/get-permission
*
* @param options - Options to Share Create Permission operation.
* @param filePermissionKey - File permission key which indicates the security descriptor of the permission.
*/
getPermission(filePermissionKey: string, options?: ShareGetPermissionOptions): Promise<ShareGetPermissionResponse>;
/**
* Get a {@link ShareLeaseClient} that manages leases on the file.
*
* @param proposeLeaseId - Initial proposed lease Id.
* @returns A new ShareLeaseClient object for managing leases on the file.
*/
getShareLeaseClient(proposeLeaseId?: string): ShareLeaseClient;
/**
* Only available for ShareClient constructed with a shared key credential.
*
* Generates a Service Shared Access Signature (SAS) URI based on the client properties
* and parameters passed in. The SAS is signed by the shared key credential of the client.
*
* @see https://learn.microsoft.com/rest/api/storageservices/constructing-a-service-sas
*
* @param options - Optional parameters.
* @returns The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token.
*/
generateSasUrl(options: ShareGenerateSasUrlOptions): string;
/**
* Only available for ShareClient constructed with a shared key credential.
*
* Generates string to sign for a Service Shared Access Signature (SAS) URI based on the client properties
* and parameters passed in. The SAS is signed by the shared key credential of the client.
*
* @see https://learn.microsoft.com/rest/api/storageservices/constructing-a-service-sas
*
* @param options - Optional parameters.
* @returns The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token.
*/
generateSasStringToSign(options: ShareGenerateSasUrlOptions): string;
}
/**
* Options to configure {@link ShareDirectoryClient.create} operation.
*/
export interface DirectoryCreateOptions extends FileAndDirectoryCreateCommonOptions, CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* A collection of key-value string pair to associate with the file storage object.
*/
metadata?: Metadata;
}
export interface DirectoryProperties extends FileAndDirectorySetPropertiesCommonOptions, CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
}
/**
* Options to configure {@link ShareDirectoryClient.listFilesAndDirectories} operation.
*/
export interface DirectoryListFilesAndDirectoriesOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* Filters the results to return only entries whose
* name begins with the specified prefix.
*/
prefix?: string;
includeTimestamps?: boolean;
includeEtag?: boolean;
includeAttributes?: boolean;
includePermissionKey?: boolean;
/**
* Optional. Specified that extended info should be included in the returned {@link FileItem} or {@link DirectoryItem}.
* If true, the Content-Length property will be up-to-date, FileId will be returned in response.
*/
includeExtendedInfo?: boolean;
}
/**
* Options to configure the {@link ShareDirectoryClient.delete} operation.
*/
export interface DirectoryDeleteOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
}
/**
* Options to configure the {@link ShareDirectoryClient.exists} operation.
*/
export interface DirectoryExistsOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
}
/**
* Options to configure the {@link ShareDirectoryClient.getProperties} operation.
*/
export interface DirectoryGetPropertiesOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
}
/**
* Options to configure the {@link ShareDirectoryClient.setMetadata} operation.
*/
export interface DirectorySetMetadataOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
}
/**
* Options to configure Directory - List Handles Segment operations.
*
* See:
* - {@link ShareDirectoryClient.listHandlesSegment}
* - {@link ShareDirectoryClient.iterateHandleSegments}
* - {@link ShareDirectoryClient.listHandleItems}
*
*/
export interface DirectoryListHandlesSegmentOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* Specifies the maximum number of entries to return. If the request does not specify maxResults,
* or specifies a value greater than 5,000, the server will return up to 5,000 items.
*/
maxResults?: number;
/**
* Specifies operation should apply to the directory specified in the URI, its files, its
* subdirectories and their files.
*/
recursive?: boolean;
}
/**
* Options to configure the {@link ShareDirectoryClient.listHandles} operation.
*/
export interface DirectoryListHandlesOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* Specifies whether operation should apply to the directory specified in the URI, its files, its
* subdirectories and their files.
*/
recursive?: boolean;
}
/**
* Options to configure Directory - Force Close Handles Segment operations.
*
* See:
* - {@link ShareDirectoryClient.forceCloseHandlesSegment}
* - {@link ShareDirectoryClient.forceCloseAllHandles}
*/
export interface DirectoryForceCloseHandlesSegmentOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
/**
* Specifies operation should apply to the directory specified in the URI, its files, its
* subdirectories and their files.
*/
recursive?: boolean;
}
/**
* Additional response header values for close handles request.
*/
export interface DirectoryCloseHandlesHeaders {
/**
* This header uniquely identifies the request that was made and can be used for troubleshooting
* the request.
*/
requestId?: string;
/**
* Indicates the version of the File service used to execute the request.
*/
version?: string;
/**
* A UTC date/time value generated by the service that indicates the time at which the response
* was initiated.
*/
date?: Date;
/**
* A string describing next handle to be closed. It is returned when more handles need to be
* closed to complete the request.
*/
marker?: string;
}
/**
* Response type for {@link ShareDirectoryClient.forceCloseHandle}.
*/
export type DirectoryForceCloseHandlesResponse = WithResponse<CloseHandlesInfo & DirectoryCloseHandlesHeaders, DirectoryForceCloseHandlesHeaders>;
/**
* Options to configure {@link ShareDirectoryClient.forceCloseHandle}.
*/
export interface DirectoryForceCloseHandlesOptions extends CommonOptions {
/**
* An implementation of the `AbortSignalLike` interface to signal the request to cancel the operation.
* For example, use the @azure/abort-controller to create an `AbortSignal`.
*/
abortSignal?: AbortSignalLike;
}
/**
* Contains response data for the {@link DirectoryClient.createIfNotExists} operation.
*/
export interface DirectoryCreateIfNotExistsResponse extends DirectoryCreateResponse {
/**
* Indicate whether the directory is successfully created. Is false when the directory is not changed as it already exists.
*/
succeeded: boolean;
}
/**
* Contains response data for the {@link DirectoryClient.deleteIfExists} operation.
*/
export interface DirectoryDeleteIfExistsResponse extends DirectoryDeleteResponse {
/**
* Indicate whether the directory is successfully deleted. Is false if the directory does not exist in the first place.
*/
succeeded: boolean;
}
/**
* A ShareDirectoryClient represents a URL to the Azure Storage directory allowing you to manipulate its files and directories.
*/
export declare class ShareDirectoryClient extends StorageClient {
/**
* context provided by protocol layer.
*/
private context;
private _shareName;
private _path;
private _name;
private shareClientConfig?;
/**
* The share name corresponding to this directory client
*/
get shareName(): string;
/**
* The full path of the directory
*/
get path(): string;
/**
* The name of the directory
*/
get name(): string;
/**
* Creates an instance of DirectoryClient.
*
* @param url - A URL string pointing to Azure Storage file directory, such as
* "https://myaccount.file.core.windows.net/myshare/mydirectory". You can
* append a SAS if using AnonymousCredential, such as
* "https://myaccount.file.core.windows.net/myshare/mydirectory?sasString".
* This method accepts an encoded URL or non-encoded URL pointing to a directory.
* Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped.
* However, if a directory name includes %, directory name must be encoded in the URL.
* Such as a directory named "mydir%", the URL should be "https://myaccount.file.core.windows.net/myshare/mydir%25".
* @param credential - Such as AnonymousCredential or StorageSharedKeyCredential.
* If not specified, AnonymousCredential is used.
* @param options - Optional. Options to configure the HTTP pipeline.
*/
constructor(url: string, credential?: Credential | TokenCredential, options?: ShareClientOptions);
/**
* Creates an instance of DirectoryClient.
*
* @param url - A URL string pointing to Azure Storage file directory, such as
* "https://myaccount.file.core.windows.net/myshare/mydirectory". You can
* append a SAS if using AnonymousCredential, such as
* "https://myaccount.file.core.windows.net/myshare/mydirectory?sasString".
* This method accepts an encoded URL or non-encoded URL pointing to a directory.
* Encoded URL string will NOT be escaped twice, only special characters in URL path will be escaped.
* However, if a directory name includes %, directory name must be encoded in the URL.
* Such as a directory named "mydir%", the URL should be "https://myaccount.file.core.windows.net/myshare/mydir%25".
* @param pipeline - Call newPipeline() to create a default
* pipeline, or provide a customized pipeline.
*/
constructor(url: string, pipeline: Pipeline, options?: ShareClientConfig);
/**
* Creates a new directory under the specified share or parent directory.
* @see https://learn.microsoft.com/rest/api/storageservices/create-directory
*
* @param options - Options to Directory Create operation.
* @returns Response data for the Directory operation.
*/
create(options?: DirectoryCreateOptions): Promise<DirectoryCreateResponse>;
/**
* Creates a new directory under the specified share or parent directory if it does not already exists.
* If the directory already exists, it is not modified.
* @see https://learn.microsoft.com/rest/api/storageservices/create-directory
*
* @param options -
*/
createIfNotExists(options?: DirectoryCreateOptions): Promise<DirectoryCreateIfNotExistsResponse>;
/**
* Sets properties on the directory.
* @see https://learn.microsoft.com/rest/api/storageservices/set-directory-properties
*
* @param DirectoryProperties - Directory properties. If no values are provided,
* existing values will be preserved.
*/
setProperties(properties?: DirectoryProperties): Promise<DirectorySetPropertiesResponse>;
/**
* Creates a ShareDirectoryClient object for a sub directory.
*
* @param subDirectoryName - A subdirectory name
* @returns The ShareDirectoryClient object for the given subdirectory name.
*
* Example usage:
*
* ```ts snippet:ReadmeSampleGetDirectoryClient
* import { StorageSharedKeyCredential, ShareServiceClient } from "@azure/storage-file-share";
*
* const account = "<account>";
* const accountKey = "<accountkey>";
*
* const credential = new StorageSharedKeyCredential(account, accountKey);
* const serviceClient = new ShareServiceClient(
* `https://${account}.file.core.windows.net`,
* credential,
* );
*
* const shareName = "<share name>";
* const directoryName = "<directory name>";
* const shareClient = serviceClient.getShareClient(shareName);
* const directoryClient = shareClient.getDirectoryClient(directoryName);
* await directoryClient.create();
* ```
*/
getDirectoryClient(subDirectoryName: string): ShareDirectoryClient;
/**
* Creates a new subdirectory under this directory.
* @see https://learn.microsoft.com/rest/api/storageservices/create-directory
*
* @param directoryName -
* @param options - Options to Directory Create operation.
* @returns Directory create response data and the corresponding DirectoryClient instance.
*/
createSubdirectory(directoryName: string, options?: DirectoryCreateOptions): Promise<{
directoryClient: ShareDirectoryClient;
directoryCreateResponse: DirectoryCreateResponse;
}>;
/**
* Removes the specified empty sub directory under this directory.
* Note that the directory must be empty before it can be deleted.
* @see https://learn.microsoft.com/rest/api/storageservices/delete-directory
*
* @param directoryName -
* @param options - Options to Directory Delete operation.
* @returns Directory deletion response data.
*/
deleteSubdirectory(directoryName: string, options?: DirectoryDeleteOptions): Promise<DirectoryDeleteResponse>;
/**
* Creates a new file or replaces a file under this directory. Note it only initializes the file with no content.
* @see https://learn.microsoft.com/rest/api/storageservices/create-file
*
* @param fileName -
* @param size - Specifies the maximum size in bytes for the file, up to 4 TB.
* @param options - Options to File Create operation.
* @returns File creation response data and the corresponding file client.
*/
createFile(fileName: string, size: number, options?: FileCreateOptions): Promise<{
fileClient: ShareFileClient;
fileCreateResponse: FileCreateResponse;
}>;
/**
* Removes the specified file under this directory from the storage account.
* When a file is successfully deleted, it is immediately removed from the storage
* account's index and is no longer accessible to clients. The file's data is later
* removed from the service during garbage collection.
*
* Delete File will fail with status code 409 (Conflict) and error code SharingViolation
* if the file is open on an SMB client.
*
* Delete File is not supported on a share snapshot, which is a read-only copy of
* a share. An attempt to perform this operation on a share snapshot will fail with 400 (InvalidQueryParameterValue)
*
* @see https://learn.microsoft.com/rest/api/storageservices/delete-file2
*
* @param fileName - Name of the file to delete
* @param options - Options to File Del