Share via

DataLakeFileSystemClient class

  • Reference
Package:
@azure/storage-file-datalake

A DataLakeFileSystemClient represents a URL to the Azure Storage file system allowing you to manipulate its directories and files.

Extends

StorageClient

Constructors

DataLakeFileSystemClient(string, Pipeline)

Creates an instance of DataLakeFileSystemClient from url and pipeline.
DataLakeFileSystemClient(string, StorageSharedKeyCredential | AnonymousCredential | TokenCredential, StoragePipelineOptions)

Creates an instance of DataLakeFileSystemClient from url and credential.

Properties

name

Name of current file system.

Inherited Properties

accountName
credential

Such as AnonymousCredential, StorageSharedKeyCredential or any credential from the @azure/identity package to authenticate requests to the service. You can also provide an object that implements the TokenCredential interface. If not specified, AnonymousCredential is used.
url

Encoded URL string value.

Methods

create(FileSystemCreateOptions)

Creates a new file system under the specified account. If the file system with the same name already exists, the operation fails.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container
createIfNotExists(FileSystemCreateOptions)

Creates a new file system under the specified account. If the file system with the same name already exists, it is not changed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container
delete(FileSystemDeleteOptions)

Delete current file system.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-container
deleteIfExists(FileSystemDeleteOptions)

Delete current file system if it exists.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-container
exists(FileSystemExistsOptions)

Returns true if the File system represented by this client exists; false otherwise.

NOTE: use this function with care since an existing file system might be deleted by other clients or applications. Vice versa new file system with the same name might be added by other clients or applications after this function completes.
generateSasStringToSign(FileSystemGenerateSasUrlOptions)

Only available for DataLakeFileSystemClient 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://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas
generateSasUrl(FileSystemGenerateSasUrlOptions)

Only available for DataLakeFileSystemClient 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://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas
getAccessPolicy(FileSystemGetAccessPolicyOptions)

Gets the permissions for the specified file system. The permissions indicate whether file system data may be accessed publicly.

WARNING: JavaScript Date will potentially lose precision when parsing startsOn and expiresOn strings. For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z".

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-container-acl
getDataLakeLeaseClient(string)

Get a DataLakeLeaseClient that manages leases on the file system.
getDirectoryClient(string)

Creates a DataLakeDirectoryClient object under current file system.
getFileClient(string)

Creates a DataLakeFileClient object under current file system.
getProperties(FileSystemGetPropertiesOptions)

Returns all user-defined metadata and system properties for the specified file system.

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 listFileSystems method of DataLakeServiceClient using the includeMetadata option, which will retain their original casing.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-container-properties
listDeletedPaths(ListDeletedPathsOptions)

Returns an async iterable iterator to list all the paths (directories and files) under the specified file system.

.byPage() returns an async iterable iterator to list the paths in pages.

Example using for await syntax:

// Get the fileSystemClient before you run these snippets,
// Can be obtained from `serviceClient.getFileSystemClient("<your-filesystem-name>");`
let i = 1;
for await (const deletePath of fileSystemClient.listDeletedPaths()) {
  console.log(`Path ${i++}: ${deletePath.name}`);
}

Example using iter.next():

let i = 1;
let iter = fileSystemClient.listDeletedPaths();
let deletedPathItem = await iter.next();
while (!deletedPathItem.done) {
  console.log(`Path ${i++}: ${deletedPathItem.value.name}`);
  pathItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of fileSystemClient.listDeletedPaths().byPage({ maxPageSize: 20 })) {
  for (const deletePath of response.pathItems) {
    console.log(`Path ${i++}: ${deletePath.name}`);
  }
}

Example using paging with a marker:

let i = 1;
let iterator = fileSystemClient.listDeletedPaths().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 path names
for (const path of response.pathItems) {
  console.log(`Path ${i++}: ${path.name}}`);
}

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken

iterator = fileSystemClient.listDeletedPaths().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 path names
for (const deletePath of response.deletedPathItems) {
  console.log(`Path ${i++}: ${deletePath.name}`);
}

See https://docs.microsoft.com/rest/api/storageservices/list-blobs
listPaths(ListPathsOptions)

Returns an async iterable iterator to list all the paths (directories and files) under the specified file system.

.byPage() returns an async iterable iterator to list the paths in pages.

Example using for await syntax:

// Get the fileSystemClient before you run these snippets,
// Can be obtained from `serviceClient.getFileSystemClient("<your-filesystem-name>");`
let i = 1;
for await (const path of fileSystemClient.listPaths()) {
  console.log(`Path ${i++}: ${path.name}, isDirectory?: ${path.isDirectory}`);
}

Example using iter.next():

let i = 1;
let iter = fileSystemClient.listPaths();
let pathItem = await iter.next();
while (!pathItem.done) {
  console.log(`Path ${i++}: ${pathItem.value.name}, isDirectory?: ${pathItem.value.isDirectory}`);
  pathItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of fileSystemClient.listPaths().byPage({ maxPageSize: 20 })) {
  for (const path of response.pathItems) {
    console.log(`Path ${i++}: ${path.name}, isDirectory?: ${path.isDirectory}`);
  }
}

Example using paging with a marker:

let i = 1;
let iterator = fileSystemClient.listPaths().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 path names
for (const path of response.pathItems) {
  console.log(`Path ${i++}: ${path.name}, isDirectory?: ${path.isDirectory}`);
}

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken

iterator = fileSystemClient.listPaths().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 path names
for (const path of response.pathItems) {
  console.log(`Path ${i++}: ${path.name}, isDirectory?: ${path.isDirectory}`);
}

See https://docs.microsoft.com/rest/api/storageservices/list-blobs
setAccessPolicy(PublicAccessType, SignedIdentifier<AccessPolicy>[], FileSystemSetAccessPolicyOptions)

Sets the permissions for the specified file system. The permissions indicate whether directories or files in a file system may be accessed publicly.

When you set permissions for a file system, the existing permissions are replaced. If no access or containerAcl provided, the existing file system ACL will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-container-acl
setMetadata(Metadata, FileSystemSetMetadataOptions)

Sets one or more user-defined name-value pairs for the specified file system.

If no option provided, or no metadata defined in the parameter, the file system metadata will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-container-metadata
undeletePath(string, string, FileSystemUndeletePathOption)

Restores a soft deleted path.

See https://docs.microsoft.com/en-us/rest/api/storageservices/undelete-blob

Constructor Details

DataLakeFileSystemClient(string, Pipeline)

Creates an instance of DataLakeFileSystemClient from url and pipeline.

new DataLakeFileSystemClient(url: string, pipeline: Pipeline)

Parameters

url

string

A Client string pointing to Azure Storage data lake file system, such as "https://myaccount.dfs.core.windows.net/filesystem". You can append a SAS if using AnonymousCredential, such as "https://myaccount.dfs.core.windows.net/filesystem?sasString".

pipeline
Pipeline

Call newPipeline() to create a default pipeline, or provide a customized pipeline.

DataLakeFileSystemClient(string, StorageSharedKeyCredential | AnonymousCredential | TokenCredential, StoragePipelineOptions)

Creates an instance of DataLakeFileSystemClient from url and credential.

new DataLakeFileSystemClient(url: string, credential?: StorageSharedKeyCredential | AnonymousCredential | TokenCredential, options?: StoragePipelineOptions)

Parameters

url

string

A Client string pointing to Azure Storage data lake file system, such as "https://myaccount.dfs.core.windows.net/filesystem". You can append a SAS if using AnonymousCredential, such as "https://myaccount.dfs.core.windows.net/filesystem?sasString".

credential

StorageSharedKeyCredential | AnonymousCredential | TokenCredential

Such as AnonymousCredential, StorageSharedKeyCredential or any credential from the @azure/identity package to authenticate requests to the service. You can also provide an object that implements the TokenCredential interface. If not specified, AnonymousCredential is used.

options
StoragePipelineOptions

Optional. Options to configure the HTTP pipeline.

Property Details

name

Name of current file system.

string name

Property Value

string

Inherited Property Details

accountName 

accountName: string

Property Value

string

Inherited From StorageClient.accountName

credential

Such as AnonymousCredential, StorageSharedKeyCredential or any credential from the @azure/identity package to authenticate requests to the service. You can also provide an object that implements the TokenCredential interface. If not specified, AnonymousCredential is used.

credential: StorageSharedKeyCredential | AnonymousCredential | TokenCredential

Property Value

StorageSharedKeyCredential | AnonymousCredential | TokenCredential

Inherited From StorageClient.credential

url

Encoded URL string value.

url: string

Property Value

string

Inherited From StorageClient.url

Method Details

create(FileSystemCreateOptions)

Creates a new file system under the specified account. If the file system with the same name already exists, the operation fails.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container

function create(options?: FileSystemCreateOptions): Promise<FileSystemCreateResponse>

Parameters

options
FileSystemCreateOptions

Optional. Options when creating file system.

Returns

Promise<FileSystemCreateResponse>

createIfNotExists(FileSystemCreateOptions)

Creates a new file system under the specified account. If the file system with the same name already exists, it is not changed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/create-container

function createIfNotExists(options?: FileSystemCreateOptions): Promise<FileSystemCreateIfNotExistsResponse>

Parameters

options
FileSystemCreateOptions

Returns

Promise<FileSystemCreateIfNotExistsResponse>

delete(FileSystemDeleteOptions)

Delete current file system.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-container

function delete(options?: FileSystemDeleteOptions): Promise<FileSystemDeleteResponse>

Parameters

options
FileSystemDeleteOptions

Optional. Options when deleting file system.

Returns

Promise<FileSystemDeleteResponse>

deleteIfExists(FileSystemDeleteOptions)

Delete current file system if it exists.

See https://docs.microsoft.com/en-us/rest/api/storageservices/delete-container

function deleteIfExists(options?: FileSystemDeleteOptions): Promise<FileSystemDeleteIfExistsResponse>

Parameters

options
FileSystemDeleteOptions

Returns

Promise<FileSystemDeleteIfExistsResponse>

exists(FileSystemExistsOptions)

Returns true if the File system represented by this client exists; false otherwise.

NOTE: use this function with care since an existing file system might be deleted by other clients or applications. Vice versa new file system with the same name might be added by other clients or applications after this function completes.

function exists(options?: FileSystemExistsOptions): Promise<boolean>

Parameters

options
FileSystemExistsOptions

Returns

Promise<boolean>

generateSasStringToSign(FileSystemGenerateSasUrlOptions)

Only available for DataLakeFileSystemClient 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://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas

function generateSasStringToSign(options: FileSystemGenerateSasUrlOptions): string

Parameters

options
FileSystemGenerateSasUrlOptions

Optional parameters.

Returns

string

The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token.

generateSasUrl(FileSystemGenerateSasUrlOptions)

Only available for DataLakeFileSystemClient 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://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas

function generateSasUrl(options: FileSystemGenerateSasUrlOptions): Promise<string>

Parameters

options
FileSystemGenerateSasUrlOptions

Optional parameters.

Returns

Promise<string>

The SAS URI consisting of the URI to the resource represented by this client, followed by the generated SAS token.

getAccessPolicy(FileSystemGetAccessPolicyOptions)

Gets the permissions for the specified file system. The permissions indicate whether file system data may be accessed publicly.

WARNING: JavaScript Date will potentially lose precision when parsing startsOn and expiresOn strings. For example, new Date("2018-12-31T03:44:23.8827891Z").toISOString() will get "2018-12-31T03:44:23.882Z".

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-container-acl

function getAccessPolicy(options?: FileSystemGetAccessPolicyOptions): Promise<FileSystemGetAccessPolicyResponse>

Parameters

options
FileSystemGetAccessPolicyOptions

Optional. Options when getting file system access policy.

Returns

Promise<FileSystemGetAccessPolicyResponse>

getDataLakeLeaseClient(string)

Get a DataLakeLeaseClient that manages leases on the file system.

function getDataLakeLeaseClient(proposeLeaseId?: string): DataLakeLeaseClient

Parameters

proposeLeaseId

string

Optional. Initial proposed lease Id.

Returns

DataLakeLeaseClient

getDirectoryClient(string)

Creates a DataLakeDirectoryClient object under current file system.

function getDirectoryClient(directoryName: string): DataLakeDirectoryClient

Parameters

directoryName

string

Returns

DataLakeDirectoryClient

getFileClient(string)

Creates a DataLakeFileClient object under current file system.

function getFileClient(fileName: string): DataLakeFileClient

Parameters

fileName

string

Returns

DataLakeFileClient

getProperties(FileSystemGetPropertiesOptions)

Returns all user-defined metadata and system properties for the specified file system.

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 listFileSystems method of DataLakeServiceClient using the includeMetadata option, which will retain their original casing.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-container-properties

function getProperties(options?: FileSystemGetPropertiesOptions): Promise<FileSystemGetPropertiesResponse>

Parameters

options
FileSystemGetPropertiesOptions

Optional. Options when getting file system properties.

Returns

Promise<FileSystemGetPropertiesResponse>

listDeletedPaths(ListDeletedPathsOptions)

Returns an async iterable iterator to list all the paths (directories and files) under the specified file system.

.byPage() returns an async iterable iterator to list the paths in pages.

Example using for await syntax:

// Get the fileSystemClient before you run these snippets,
// Can be obtained from `serviceClient.getFileSystemClient("<your-filesystem-name>");`
let i = 1;
for await (const deletePath of fileSystemClient.listDeletedPaths()) {
  console.log(`Path ${i++}: ${deletePath.name}`);
}

Example using iter.next():

let i = 1;
let iter = fileSystemClient.listDeletedPaths();
let deletedPathItem = await iter.next();
while (!deletedPathItem.done) {
  console.log(`Path ${i++}: ${deletedPathItem.value.name}`);
  pathItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of fileSystemClient.listDeletedPaths().byPage({ maxPageSize: 20 })) {
  for (const deletePath of response.pathItems) {
    console.log(`Path ${i++}: ${deletePath.name}`);
  }
}

Example using paging with a marker:

let i = 1;
let iterator = fileSystemClient.listDeletedPaths().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 path names
for (const path of response.pathItems) {
  console.log(`Path ${i++}: ${path.name}}`);
}

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken

iterator = fileSystemClient.listDeletedPaths().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 path names
for (const deletePath of response.deletedPathItems) {
  console.log(`Path ${i++}: ${deletePath.name}`);
}

See https://docs.microsoft.com/rest/api/storageservices/list-blobs

function listDeletedPaths(options?: ListDeletedPathsOptions): PagedAsyncIterableIterator<DeletedPath, FileSystemListDeletedPathsResponse, PageSettings>

Parameters

options
ListDeletedPathsOptions

Optional. Options when listing deleted paths.

Returns

PagedAsyncIterableIterator<DeletedPath, FileSystemListDeletedPathsResponse, PageSettings>

listPaths(ListPathsOptions)

Returns an async iterable iterator to list all the paths (directories and files) under the specified file system.

.byPage() returns an async iterable iterator to list the paths in pages.

Example using for await syntax:

// Get the fileSystemClient before you run these snippets,
// Can be obtained from `serviceClient.getFileSystemClient("<your-filesystem-name>");`
let i = 1;
for await (const path of fileSystemClient.listPaths()) {
  console.log(`Path ${i++}: ${path.name}, isDirectory?: ${path.isDirectory}`);
}

Example using iter.next():

let i = 1;
let iter = fileSystemClient.listPaths();
let pathItem = await iter.next();
while (!pathItem.done) {
  console.log(`Path ${i++}: ${pathItem.value.name}, isDirectory?: ${pathItem.value.isDirectory}`);
  pathItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of fileSystemClient.listPaths().byPage({ maxPageSize: 20 })) {
  for (const path of response.pathItems) {
    console.log(`Path ${i++}: ${path.name}, isDirectory?: ${path.isDirectory}`);
  }
}

Example using paging with a marker:

let i = 1;
let iterator = fileSystemClient.listPaths().byPage({ maxPageSize: 2 });
let response = (await iterator.next()).value;

// Prints 2 path names
for (const path of response.pathItems) {
  console.log(`Path ${i++}: ${path.name}, isDirectory?: ${path.isDirectory}`);
}

// Gets next marker
let marker = response.continuationToken;

// Passing next marker as continuationToken

iterator = fileSystemClient.listPaths().byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 path names
for (const path of response.pathItems) {
  console.log(`Path ${i++}: ${path.name}, isDirectory?: ${path.isDirectory}`);
}

See https://docs.microsoft.com/rest/api/storageservices/list-blobs

function listPaths(options?: ListPathsOptions): PagedAsyncIterableIterator<Path, FileSystemListPathsResponse, PageSettings>

Parameters

options
ListPathsOptions

Optional. Options when listing paths.

Returns

PagedAsyncIterableIterator<Path, FileSystemListPathsResponse, PageSettings>

setAccessPolicy(PublicAccessType, SignedIdentifier<AccessPolicy>[], FileSystemSetAccessPolicyOptions)

Sets the permissions for the specified file system. The permissions indicate whether directories or files in a file system may be accessed publicly.

When you set permissions for a file system, the existing permissions are replaced. If no access or containerAcl provided, the existing file system ACL will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-container-acl

function setAccessPolicy(access?: PublicAccessType, fileSystemAcl?: SignedIdentifier<AccessPolicy>[], options?: FileSystemSetAccessPolicyOptions): Promise<FileSystemSetAccessPolicyResponse>

Parameters

access
PublicAccessType

Optional. The level of public access to data in the file system.

fileSystemAcl

SignedIdentifier<AccessPolicy>[]

Optional. Array of elements each having a unique Id and details of the access policy.

options
FileSystemSetAccessPolicyOptions

Optional. Options when setting file system access policy.

Returns

Promise<FileSystemSetAccessPolicyResponse>

setMetadata(Metadata, FileSystemSetMetadataOptions)

Sets one or more user-defined name-value pairs for the specified file system.

If no option provided, or no metadata defined in the parameter, the file system metadata will be removed.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-container-metadata

function setMetadata(metadata?: Metadata, options?: FileSystemSetMetadataOptions): Promise<FileSystemSetMetadataResponse>

Parameters

metadata
Metadata

Replace existing metadata with this value. If no value provided the existing metadata will be removed.

options
FileSystemSetMetadataOptions

Optional. Options when setting file system metadata.

Returns

Promise<FileSystemSetMetadataResponse>

undeletePath(string, string, FileSystemUndeletePathOption)

Restores a soft deleted path.

See https://docs.microsoft.com/en-us/rest/api/storageservices/undelete-blob

function undeletePath(deletedPath: string, deletionId: string, options?: FileSystemUndeletePathOption): Promise<FileSystemUndeletePathResponse>

Parameters

deletedPath

string

Required. The path of the deleted path.

deletionId

string

Required. The deletion ID associated with the soft deleted path.

options
FileSystemUndeletePathOption

Returns

Promise<FileSystemUndeletePathResponse>