Share via

DataLakeServiceClient class

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

DataLakeServiceClient allows you to manipulate Azure Data Lake service resources and file systems. The storage account provides the top-level namespace for the Data Lake service.

Extends

StorageClient

Constructors

DataLakeServiceClient(string, Pipeline)

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

Creates an instance of DataLakeServiceClient from url.

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

fromConnectionString(string, StoragePipelineOptions)

Creates an instance of DataLakeServiceClient from connection string.
generateAccountSasUrl(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for DataLakeServiceClient constructed with a shared key credential.

Generates an account 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/create-account-sas
generateSasStringToSign(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for DataLakeServiceClient constructed with a shared key credential.

Generates string to sign for an account Shared Access Signature (SAS) 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/create-account-sas
getFileSystemClient(string)

Creates a DataLakeFileSystemClient object.
getProperties(ServiceGetPropertiesOptions)

Gets the properties of a storage account’s Blob service endpoint, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-blob-service-properties
getUserDelegationKey(Date, Date, ServiceGetUserDelegationKeyOptions)

ONLY AVAILABLE WHEN USING BEARER TOKEN AUTHENTICATION (TokenCredential).

Retrieves a user delegation key for the Data Lake service. This is only a valid operation when using bearer token authentication.

Example

// Generate user delegation SAS for a file system
const userDelegationKey = await dataLakeServiceClient.getUserDelegationKey(startsOn, expiresOn);
const fileSystemSAS = generateDataLakeSASQueryParameters({
    fileSystemName, // Required
    permissions: FileSystemSASPermissions.parse("racwdl"), // Required
    startsOn, // Required. Date type
    expiresOn, // Optional. Date type
    ipRange: { start: "0.0.0.0", end: "255.255.255.255" }, // Optional
    protocol: SASProtocol.HttpsAndHttp, // Optional
    version: "2018-11-09" // Must greater than or equal to 2018-11-09 to generate user delegation SAS
  },
  userDelegationKey, // UserDelegationKey
  accountName
).toString();

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-user-delegation-key
listFileSystems(ServiceListFileSystemsOptions)

Returns an async iterable iterator to list all the file systems under the specified account.

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

Example using for await syntax:

let i = 1;
for await (const fileSystem of serviceClient.listFileSystems()) {
  console.log(`FileSystem ${i++}: ${fileSystem.name}`);
}

Example using iter.next():

let i = 1;
const iter = serviceClient.listFileSystems();
let fileSystemItem = await iter.next();
while (!fileSystemItem.done) {
  console.log(`FileSystem ${i++}: ${fileSystemItem.value.name}`);
  fileSystemItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of serviceClient.listFileSystems().byPage({ maxPageSize: 20 })) {
  if (response.fileSystemItems) {
    for (const fileSystem of response.fileSystemItems) {
      console.log(`FileSystem ${i++}: ${fileSystem.name}`);
    }
  }
}

Example using paging with a marker:

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

// Prints 2 file system names
if (response.fileSystemItems) {
  for (const fileSystem of response.fileSystemItems) {
    console.log(`FileSystem ${i++}: ${fileSystem.name}`);
  }
}

// Gets next marker
let marker = response.continuationToken;
// Passing next marker as continuationToken
iterator = serviceClient
  .listContainers()
  .byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 file system names
if (response.fileSystemItems) {
  for (const fileSystem of response.fileSystemItems) {
     console.log(`FileSystem ${i++}: ${fileSystem.name}`);
  }
}

See https://docs.microsoft.com/en-us/rest/api/storageservices/list-containers2
setProperties(BlobServiceProperties, ServiceSetPropertiesOptions)

Sets properties for a storage account’s Blob service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-service-properties
undeleteFileSystem(string, string, ServiceUndeleteFileSystemOptions)

Restore a previously deleted File System. This API is only functional if Container Soft Delete is enabled for the storage account.

Constructor Details

DataLakeServiceClient(string, Pipeline)

Creates an instance of DataLakeServiceClient from url and pipeline.

new DataLakeServiceClient(url: string, pipeline: Pipeline)

Parameters

url

string

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

pipeline
Pipeline

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

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

Creates an instance of DataLakeServiceClient from url.

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

Parameters

url

string

A Client string pointing to Azure Storage data lake service, such as "https://myaccount.dfs.core.windows.net". You can append a SAS if using AnonymousCredential, such as "https://myaccount.dfs.core.windows.net?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.

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

fromConnectionString(string, StoragePipelineOptions)

Creates an instance of DataLakeServiceClient from connection string.

static function fromConnectionString(connectionString: string, options?: StoragePipelineOptions): DataLakeServiceClient

Parameters

connectionString

string

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

options
StoragePipelineOptions

Optional. Options to configure the HTTP pipeline.

Returns

DataLakeServiceClient

generateAccountSasUrl(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for DataLakeServiceClient constructed with a shared key credential.

Generates an account 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/create-account-sas

function generateAccountSasUrl(expiresOn?: Date, permissions?: AccountSASPermissions, resourceTypes?: string, options?: ServiceGenerateAccountSasUrlOptions): string

Parameters

expiresOn

Date

Optional. The time at which the shared access signature becomes invalid. Default to an hour later if not specified.

permissions
AccountSASPermissions

Specifies the list of permissions to be associated with the SAS.

resourceTypes

string

Specifies the resource types associated with the shared access signature.

options
ServiceGenerateAccountSasUrlOptions

Optional parameters.

Returns

string

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

generateSasStringToSign(Date, AccountSASPermissions, string, ServiceGenerateAccountSasUrlOptions)

Only available for DataLakeServiceClient constructed with a shared key credential.

Generates string to sign for an account Shared Access Signature (SAS) 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/create-account-sas

function generateSasStringToSign(expiresOn?: Date, permissions?: AccountSASPermissions, resourceTypes?: string, options?: ServiceGenerateAccountSasUrlOptions): string

Parameters

expiresOn

Date

Optional. The time at which the shared access signature becomes invalid. Default to an hour later if not specified.

permissions
AccountSASPermissions

Specifies the list of permissions to be associated with the SAS.

resourceTypes

string

Specifies the resource types associated with the shared access signature.

options
ServiceGenerateAccountSasUrlOptions

Optional parameters.

Returns

string

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

getFileSystemClient(string)

Creates a DataLakeFileSystemClient object.

function getFileSystemClient(fileSystemName: string): DataLakeFileSystemClient

Parameters

fileSystemName

string

File system name.

Returns

DataLakeFileSystemClient

getProperties(ServiceGetPropertiesOptions)

Gets the properties of a storage account’s Blob service endpoint, including properties for Storage Analytics and CORS (Cross-Origin Resource Sharing) rules.

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

function getProperties(options?: ServiceGetPropertiesOptions): Promise<ServiceGetPropertiesResponse>

Parameters

options
ServiceGetPropertiesOptions

Options to the Service Get Properties operation.

Returns

Promise<DataLakeServiceGetPropertiesResponse>

Response data for the Service Get Properties operation.

getUserDelegationKey(Date, Date, ServiceGetUserDelegationKeyOptions)

ONLY AVAILABLE WHEN USING BEARER TOKEN AUTHENTICATION (TokenCredential).

Retrieves a user delegation key for the Data Lake service. This is only a valid operation when using bearer token authentication.

Example

// Generate user delegation SAS for a file system
const userDelegationKey = await dataLakeServiceClient.getUserDelegationKey(startsOn, expiresOn);
const fileSystemSAS = generateDataLakeSASQueryParameters({
    fileSystemName, // Required
    permissions: FileSystemSASPermissions.parse("racwdl"), // Required
    startsOn, // Required. Date type
    expiresOn, // Optional. Date type
    ipRange: { start: "0.0.0.0", end: "255.255.255.255" }, // Optional
    protocol: SASProtocol.HttpsAndHttp, // Optional
    version: "2018-11-09" // Must greater than or equal to 2018-11-09 to generate user delegation SAS
  },
  userDelegationKey, // UserDelegationKey
  accountName
).toString();

See https://docs.microsoft.com/en-us/rest/api/storageservices/get-user-delegation-key

function getUserDelegationKey(startsOn: Date, expiresOn: Date, options?: ServiceGetUserDelegationKeyOptions): Promise<ServiceGetUserDelegationKeyResponse>

Parameters

startsOn

Date

The start time for the user delegation SAS. Must be within 7 days of the current time.

expiresOn

Date

The end time for the user delegation SAS. Must be within 7 days of the current time.

options
ServiceGetUserDelegationKeyOptions

Returns

Promise<ServiceGetUserDelegationKeyResponse>

listFileSystems(ServiceListFileSystemsOptions)

Returns an async iterable iterator to list all the file systems under the specified account.

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

Example using for await syntax:

let i = 1;
for await (const fileSystem of serviceClient.listFileSystems()) {
  console.log(`FileSystem ${i++}: ${fileSystem.name}`);
}

Example using iter.next():

let i = 1;
const iter = serviceClient.listFileSystems();
let fileSystemItem = await iter.next();
while (!fileSystemItem.done) {
  console.log(`FileSystem ${i++}: ${fileSystemItem.value.name}`);
  fileSystemItem = await iter.next();
}

Example using byPage():

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of serviceClient.listFileSystems().byPage({ maxPageSize: 20 })) {
  if (response.fileSystemItems) {
    for (const fileSystem of response.fileSystemItems) {
      console.log(`FileSystem ${i++}: ${fileSystem.name}`);
    }
  }
}

Example using paging with a marker:

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

// Prints 2 file system names
if (response.fileSystemItems) {
  for (const fileSystem of response.fileSystemItems) {
    console.log(`FileSystem ${i++}: ${fileSystem.name}`);
  }
}

// Gets next marker
let marker = response.continuationToken;
// Passing next marker as continuationToken
iterator = serviceClient
  .listContainers()
  .byPage({ continuationToken: marker, maxPageSize: 10 });
response = (await iterator.next()).value;

// Prints 10 file system names
if (response.fileSystemItems) {
  for (const fileSystem of response.fileSystemItems) {
     console.log(`FileSystem ${i++}: ${fileSystem.name}`);
  }
}

See https://docs.microsoft.com/en-us/rest/api/storageservices/list-containers2

function listFileSystems(options?: ServiceListFileSystemsOptions): PagedAsyncIterableIterator<FileSystemItem, ServiceListFileSystemsSegmentResponse, PageSettings>

Parameters

options
ServiceListFileSystemsOptions

Returns

PagedAsyncIterableIterator<FileSystemItem, ServiceListFileSystemsSegmentResponse, PageSettings>

setProperties(BlobServiceProperties, ServiceSetPropertiesOptions)

Sets properties for a storage account’s Blob service endpoint, including properties for Storage Analytics, CORS (Cross-Origin Resource Sharing) rules and soft delete settings.

See https://docs.microsoft.com/en-us/rest/api/storageservices/set-blob-service-properties

function setProperties(properties: BlobServiceProperties, options?: ServiceSetPropertiesOptions): Promise<ServiceSetPropertiesResponse>

Parameters

properties
DataLakeServiceProperties
options
ServiceSetPropertiesOptions

Options to the Service Set Properties operation.

Returns

Promise<ServiceSetPropertiesResponse>

Response data for the Service Set Properties operation.

undeleteFileSystem(string, string, ServiceUndeleteFileSystemOptions)

Restore a previously deleted File System. This API is only functional if Container Soft Delete is enabled for the storage account.

function undeleteFileSystem(deletedFileSystemName: string, deleteFileSystemVersion: string, options?: ServiceUndeleteFileSystemOptions): Promise<{ fileSystemClient: DataLakeFileSystemClient, fileSystemUndeleteResponse: ContainerUndeleteResponse }>

Parameters

deletedFileSystemName

string

The name of the source File System.

deleteFileSystemVersion

string

The new name of the File System.

options
ServiceUndeleteFileSystemOptions

Options to configure File System Restore operation.

Returns

Promise<{ fileSystemClient: DataLakeFileSystemClient, fileSystemUndeleteResponse: ContainerUndeleteResponse }>