你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

ShareDirectoryClient class

ShareDirectoryClient 表示 Azure 存储目录的 URL,可用于操作其文件和目录。

Extends

StorageClient

构造函数

ShareDirectoryClient(string, Credential_2 | TokenCredential, ShareClientOptions)

创建 DirectoryClient 的实例。

ShareDirectoryClient(string, Pipeline, ShareClientConfig)

创建 DirectoryClient 的实例。

属性

name

目录的名称

path

目录的完整路径

shareName

与此目录客户端对应的共享名称

继承属性

accountName
url

URL 字符串值。

方法

create(DirectoryCreateOptions)

在指定的共享目录或父目录下创建新目录。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-directory

createFile(string, number, FileCreateOptions)

创建新文件或替换此目录下的文件。 请注意,它仅初始化不带内容的文件。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-file

createIfNotExists(DirectoryCreateOptions)

在指定的共享目录或父目录下创建新目录(如果尚不存在)。 如果该目录已存在,则不会对其进行修改。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-directory

createSubdirectory(string, DirectoryCreateOptions)

在此目录下创建新的子目录。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-directory

delete(DirectoryDeleteOptions)

删除指定的空目录。 请注意,目录必须是空的,然后才能将其删除。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-directory

deleteFile(string, FileDeleteOptions)

从存储帐户中删除此目录下的指定文件。 成功删除文件后,它将从存储帐户的索引中删除,客户端不再能访问。 该文件的数据将在稍后的垃圾回收期间从服务中删除。

如果文件在 SMB 客户端上打开,则删除文件将失败,状态代码 409 (冲突) 和错误代码 SharingViolation。

共享快照(共享的只读副本)不支持删除文件。 尝试对共享快照执行此操作将失败,400 (InvalidQueryParameterValue)

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-file2

deleteIfExists(DirectoryDeleteOptions)

删除指定的空目录(如果存在)。 请注意,目录必须是空的,然后才能将其删除。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-directory

deleteSubdirectory(string, DirectoryDeleteOptions)

删除此目录下的指定空子目录。 请注意,目录必须是空的,然后才能将其删除。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-directory

exists(DirectoryExistsOptions)

如果指定的目录存在,则返回 true;否则为 false。

注意:请谨慎使用此函数,因为现有目录可能会被其他客户端或应用程序删除。 反之亦然,此函数完成后,其他客户端或应用程序可能会添加新目录。

forceCloseAllHandles(DirectoryForceCloseHandlesSegmentOptions)

强制关闭目录的所有句柄。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles

forceCloseHandle(string, DirectoryForceCloseHandlesOptions)

强制关闭目录的特定句柄。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles

getDirectoryClient(string)

为子目录创建 ShareDirectoryClient 对象。

getFileClient(string)

创建 ShareFileClient 对象。

getProperties(DirectoryGetPropertiesOptions)

返回指定目录的所有系统属性,还可用于检查目录是否存在。 返回的数据不包括该目录或其任何子目录中的文件。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/get-directory-properties

listFilesAndDirectories(DirectoryListFilesAndDirectoriesOptions)

返回一个异步可迭代迭代器,以列出指定帐户下的所有文件和目录。

.byPage () 返回一个异步可迭代器,用于列出页面中的文件和目录。

使用 for await 语法的示例:

let i = 1;
for await (const entity of directoryClient.listFilesAndDirectories()) {
  if (entity.kind === "directory") {
    console.log(`${i++} - directory\t: ${entity.name}`);
  } else {
    console.log(`${i++} - file\t: ${entity.name}`);
  }
}

使用 iter.next() 的示例:

let i = 1;
let iter = directoryClient.listFilesAndDirectories();
let entity = await iter.next();
while (!entity.done) {
  if (entity.value.kind === "directory") {
    console.log(`${i++} - directory\t: ${entity.value.name}`);
  } else {
    console.log(`${i++} - file\t: ${entity.value.name}`);
  }
  entity = await iter.next();
}

使用 byPage() 的示例:

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of directoryClient
  .listFilesAndDirectories()
  .byPage({ maxPageSize: 20 })) {
  for (const fileItem of response.segment.fileItems) {
    console.log(`${i++} - file\t: ${fileItem.name}`);
  }
  for (const dirItem of response.segment.directoryItems) {
    console.log(`${i++} - directory\t: ${dirItem.name}`);
  }
}

使用带标记的分页的示例:

let i = 1;
let iterator = directoryClient.listFilesAndDirectories().byPage({ maxPageSize: 3 });
let response = (await iterator.next()).value;

// Prints 3 file and directory names
for (const fileItem of response.segment.fileItems) {
  console.log(`${i++} - file\t: ${fileItem.name}`);
}

for (const dirItem of response.segment.directoryItems) {
  console.log(`${i++} - directory\t: ${dirItem.name}`);
}

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

// Passing next marker as continuationToken
iterator = directoryClient
  .listFilesAndDirectories()
  .byPage({ continuationToken: dirMarker, maxPageSize: 4 });
response = (await iterator.next()).value;

// Prints 10 file and directory names
for (const fileItem of response.segment.fileItems) {
  console.log(`${i++} - file\t: ${fileItem.name}`);
}

for (const dirItem of response.segment.directoryItems) {
  console.log(`${i++} - directory\t: ${dirItem.name}`);
}
listHandles(DirectoryListHandlesOptions)

返回一个异步可迭代迭代器以列出所有句柄。 指定帐户下。

.byPage () 返回一个异步可迭代器,以列出页面中的句柄。

使用 for await 语法的示例:

let i = 1;
let iter = dirClient.listHandles();
for await (const handle of iter) {
  console.log(`Handle ${i++}: ${handle.path}, opened time ${handle.openTime}, clientIp ${handle.clientIp}`);
}

使用 iter.next() 的示例:

let i = 1;
let iter = dirClient.listHandles();
let handleItem = await iter.next();
while (!handleItem.done) {
  console.log(`Handle ${i++}: ${handleItem.value.path}, opened time ${handleItem.value.openTime}, clientIp ${handleItem.value.clientIp}`);
  handleItem = await iter.next();
}

使用 byPage() 的示例:

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of dirClient.listHandles({ recursive: true }).byPage({ maxPageSize: 20 })) {
  if (response.handleList) {
    for (const handle of response.handleList) {
      console.log(`Handle ${i++}: ${handle.path}, opened time ${handle.openTime}, clientIp ${handle.clientIp}`);
    }
  }
}

使用带标记的分页的示例:

let i = 1;
let iterator = dirClient.listHandles().byPage({ maxPageSize: 2 });
let response = await iterator.next();

// Prints 2 handles
if (response.value.handleList) {
  for (const handle of response.value.handleList) {
    console.log(`Handle ${i++}: ${handle.path}, opened time ${handle.openTime}, clientIp ${handle.clientIp}`);
  }
}

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

// Passing next marker as continuationToken
console.log(`    continuation`);
iterator = dirClient.listHandles().byPage({ continuationToken: marker, maxPageSize: 10 });
response = await iterator.next();

// Prints 2 more handles assuming you have more than four directory/files opened
if (!response.done && response.value.handleList) {
  for (const handle of response.value.handleList) {
    console.log(`Handle ${i++}: ${handle.path}, opened time ${handle.openTime}, clientIp ${handle.clientIp}`);
  }
}
rename(string, DirectoryRenameOptions)

重命名目录。 此 API 仅支持重命名同一共享中的目录。

setMetadata(Metadata, DirectorySetMetadataOptions)

汇报指定目录的用户定义元数据。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/set-directory-metadata

setProperties(DirectoryProperties)

设置目录的属性。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/set-directory-properties

构造函数详细信息

ShareDirectoryClient(string, Credential_2 | TokenCredential, ShareClientOptions)

创建 DirectoryClient 的实例。

new ShareDirectoryClient(url: string, credential?: Credential_2 | TokenCredential, options?: ShareClientOptions)

参数

url

string

指向 Azure 存储文件目录的 URL 字符串,例如“https://myaccount.file.core.windows.net/myshare/mydirectory"”。 如果使用 AnonymousCredential,则可以追加 SAS,例如“https://myaccount.file.core.windows.net/myshare/mydirectory?sasString"”。 此方法接受指向目录的编码 URL 或非编码 URL。 编码的 URL 字符串不会转义两次,只会转义 URL 路径中的特殊字符。 但是,如果目录名称包含 %,则必须在 URL 中对目录名称进行编码。 例如名为“mydir%”的目录,URL 应为“https://myaccount.file.core.windows.net/myshare/mydir%25"”。

credential

Credential | TokenCredential

例如 AnonymousCredential 或 StorageSharedKeyCredential。 如果未指定,则使用 AnonymousCredential。

options
ShareClientOptions

可选。 用于配置 HTTP 管道的选项。

ShareDirectoryClient(string, Pipeline, ShareClientConfig)

创建 DirectoryClient 的实例。

new ShareDirectoryClient(url: string, pipeline: Pipeline, options?: ShareClientConfig)

参数

url

string

指向 Azure 存储文件目录的 URL 字符串,例如“https://myaccount.file.core.windows.net/myshare/mydirectory"”。 如果使用 AnonymousCredential,则可以追加 SAS,例如“https://myaccount.file.core.windows.net/myshare/mydirectory?sasString"”。 此方法接受指向目录的编码 URL 或非编码 URL。 编码的 URL 字符串不会转义两次,只会转义 URL 路径中的特殊字符。 但是,如果目录名称包含 %,则必须在 URL 中对目录名称进行编码。 例如名为“mydir%”的目录,URL 应为“https://myaccount.file.core.windows.net/myshare/mydir%25"”。

pipeline
Pipeline

调用 newPipeline () 以创建默认管道或提供自定义管道。

属性详细信息

name

目录的名称

string name

属性值

string

path

目录的完整路径

string path

属性值

string

shareName

与此目录客户端对应的共享名称

string shareName

属性值

string

继承属性详细信息

accountName

accountName: string

属性值

string

继承自 StorageClient.accountName

url

URL 字符串值。

url: string

属性值

string

继承自 StorageClient.url

方法详细信息

create(DirectoryCreateOptions)

在指定的共享目录或父目录下创建新目录。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-directory

function create(options?: DirectoryCreateOptions): Promise<DirectoryCreateResponse>

参数

options
DirectoryCreateOptions

目录创建操作的选项。

返回

目录操作的响应数据。

createFile(string, number, FileCreateOptions)

创建新文件或替换此目录下的文件。 请注意,它仅初始化不带内容的文件。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-file

function createFile(fileName: string, size: number, options?: FileCreateOptions): Promise<{ fileClient: ShareFileClient, fileCreateResponse: FileCreateResponse }>

参数

fileName

string

size

number

指定文件的最大大小(以字节为单位),最大为 4 TB。

options
FileCreateOptions

文件创建操作的选项。

返回

Promise<{ fileClient: ShareFileClient, fileCreateResponse: FileCreateResponse }>

文件创建响应数据和相应的文件客户端。

createIfNotExists(DirectoryCreateOptions)

在指定的共享目录或父目录下创建新目录(如果尚不存在)。 如果该目录已存在,则不会对其进行修改。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-directory

function createIfNotExists(options?: DirectoryCreateOptions): Promise<DirectoryCreateIfNotExistsResponse>

参数

返回

createSubdirectory(string, DirectoryCreateOptions)

在此目录下创建新的子目录。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-directory

function createSubdirectory(directoryName: string, options?: DirectoryCreateOptions): Promise<{ directoryClient: ShareDirectoryClient, directoryCreateResponse: DirectoryCreateResponse }>

参数

directoryName

string

options
DirectoryCreateOptions

目录创建操作的选项。

返回

Promise<{ directoryClient: ShareDirectoryClient, directoryCreateResponse: DirectoryCreateResponse }>

目录创建响应数据和相应的 DirectoryClient 实例。

delete(DirectoryDeleteOptions)

删除指定的空目录。 请注意,目录必须是空的,然后才能将其删除。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-directory

function delete(options?: DirectoryDeleteOptions): Promise<DirectoryDeleteResponse>

参数

options
DirectoryDeleteOptions

目录删除操作的选项。

返回

目录删除操作的响应数据。

deleteFile(string, FileDeleteOptions)

从存储帐户中删除此目录下的指定文件。 成功删除文件后,它将从存储帐户的索引中删除,客户端不再能访问。 该文件的数据将在稍后的垃圾回收期间从服务中删除。

如果文件在 SMB 客户端上打开,则删除文件将失败,状态代码 409 (冲突) 和错误代码 SharingViolation。

共享快照(共享的只读副本)不支持删除文件。 尝试对共享快照执行此操作将失败,400 (InvalidQueryParameterValue)

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-file2

function deleteFile(fileName: string, options?: FileDeleteOptions): Promise<FileDeleteResponse>

参数

fileName

string

要删除的文件的名称

options
FileDeleteOptions

文件删除操作的选项。

返回

文件删除响应数据。

deleteIfExists(DirectoryDeleteOptions)

删除指定的空目录(如果存在)。 请注意,目录必须是空的,然后才能将其删除。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-directory

function deleteIfExists(options?: DirectoryDeleteOptions): Promise<DirectoryDeleteIfExistsResponse>

参数

返回

deleteSubdirectory(string, DirectoryDeleteOptions)

删除此目录下的指定空子目录。 请注意,目录必须是空的,然后才能将其删除。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-directory

function deleteSubdirectory(directoryName: string, options?: DirectoryDeleteOptions): Promise<DirectoryDeleteResponse>

参数

directoryName

string

options
DirectoryDeleteOptions

目录删除操作的选项。

返回

目录删除响应数据。

exists(DirectoryExistsOptions)

如果指定的目录存在,则返回 true;否则为 false。

注意:请谨慎使用此函数,因为现有目录可能会被其他客户端或应用程序删除。 反之亦然,此函数完成后,其他客户端或应用程序可能会添加新目录。

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

参数

options
DirectoryExistsOptions

“存在”操作的选项。

返回

Promise<boolean>

forceCloseAllHandles(DirectoryForceCloseHandlesSegmentOptions)

强制关闭目录的所有句柄。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles

function forceCloseAllHandles(options?: DirectoryForceCloseHandlesSegmentOptions): Promise<CloseHandlesInfo>

参数

返回

Promise<CloseHandlesInfo>

forceCloseHandle(string, DirectoryForceCloseHandlesOptions)

强制关闭目录的特定句柄。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles

function forceCloseHandle(handleId: string, options?: DirectoryForceCloseHandlesOptions): Promise<DirectoryForceCloseHandlesResponse>

参数

handleId

string

特定句柄 ID 不能为星号“*”。 使用 forceCloseHandlesSegment () 关闭所有句柄。

返回

getDirectoryClient(string)

为子目录创建 ShareDirectoryClient 对象。

function getDirectoryClient(subDirectoryName: string): ShareDirectoryClient

参数

subDirectoryName

string

子目录名称

返回

给定子目录名称的 ShareDirectoryClient 对象。

用法示例:

const directoryClient = shareClient.getDirectoryClient("<directory name>");
await directoryClient.create();
console.log("Created directory successfully");

getFileClient(string)

创建 ShareFileClient 对象。

function getFileClient(fileName: string): ShareFileClient

参数

fileName

string

文件名。

返回

给定文件名的新 ShareFileClient 对象。

用法示例:

const content = "Hello world!"

const fileClient = directoryClient.getFileClient("<file name>");

await fileClient.create(content.length);
console.log("Created file successfully!");

await fileClient.uploadRange(content, 0, content.length);
console.log("Updated file successfully!")

getProperties(DirectoryGetPropertiesOptions)

返回指定目录的所有系统属性,还可用于检查目录是否存在。 返回的数据不包括该目录或其任何子目录中的文件。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/get-directory-properties

function getProperties(options?: DirectoryGetPropertiesOptions): Promise<DirectoryGetPropertiesResponse>

参数

options
DirectoryGetPropertiesOptions

“目录获取属性”操作的选项。

返回

目录获取属性操作的响应数据。

listFilesAndDirectories(DirectoryListFilesAndDirectoriesOptions)

返回一个异步可迭代迭代器,以列出指定帐户下的所有文件和目录。

.byPage () 返回一个异步可迭代器,用于列出页面中的文件和目录。

使用 for await 语法的示例:

let i = 1;
for await (const entity of directoryClient.listFilesAndDirectories()) {
  if (entity.kind === "directory") {
    console.log(`${i++} - directory\t: ${entity.name}`);
  } else {
    console.log(`${i++} - file\t: ${entity.name}`);
  }
}

使用 iter.next() 的示例:

let i = 1;
let iter = directoryClient.listFilesAndDirectories();
let entity = await iter.next();
while (!entity.done) {
  if (entity.value.kind === "directory") {
    console.log(`${i++} - directory\t: ${entity.value.name}`);
  } else {
    console.log(`${i++} - file\t: ${entity.value.name}`);
  }
  entity = await iter.next();
}

使用 byPage() 的示例:

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of directoryClient
  .listFilesAndDirectories()
  .byPage({ maxPageSize: 20 })) {
  for (const fileItem of response.segment.fileItems) {
    console.log(`${i++} - file\t: ${fileItem.name}`);
  }
  for (const dirItem of response.segment.directoryItems) {
    console.log(`${i++} - directory\t: ${dirItem.name}`);
  }
}

使用带标记的分页的示例:

let i = 1;
let iterator = directoryClient.listFilesAndDirectories().byPage({ maxPageSize: 3 });
let response = (await iterator.next()).value;

// Prints 3 file and directory names
for (const fileItem of response.segment.fileItems) {
  console.log(`${i++} - file\t: ${fileItem.name}`);
}

for (const dirItem of response.segment.directoryItems) {
  console.log(`${i++} - directory\t: ${dirItem.name}`);
}

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

// Passing next marker as continuationToken
iterator = directoryClient
  .listFilesAndDirectories()
  .byPage({ continuationToken: dirMarker, maxPageSize: 4 });
response = (await iterator.next()).value;

// Prints 10 file and directory names
for (const fileItem of response.segment.fileItems) {
  console.log(`${i++} - file\t: ${fileItem.name}`);
}

for (const dirItem of response.segment.directoryItems) {
  console.log(`${i++} - directory\t: ${dirItem.name}`);
}
function listFilesAndDirectories(options?: DirectoryListFilesAndDirectoriesOptions): PagedAsyncIterableIterator<({ kind: "file" } & FileItem) | ({ kind: "directory" } & DirectoryItem), DirectoryListFilesAndDirectoriesSegmentResponse, PageSettings>

参数

options
DirectoryListFilesAndDirectoriesOptions

用于列出文件和目录操作的选项。

返回

支持分页的 asyncIterableIterator。

listHandles(DirectoryListHandlesOptions)

返回一个异步可迭代迭代器以列出所有句柄。 指定帐户下。

.byPage () 返回一个异步可迭代器,以列出页面中的句柄。

使用 for await 语法的示例:

let i = 1;
let iter = dirClient.listHandles();
for await (const handle of iter) {
  console.log(`Handle ${i++}: ${handle.path}, opened time ${handle.openTime}, clientIp ${handle.clientIp}`);
}

使用 iter.next() 的示例:

let i = 1;
let iter = dirClient.listHandles();
let handleItem = await iter.next();
while (!handleItem.done) {
  console.log(`Handle ${i++}: ${handleItem.value.path}, opened time ${handleItem.value.openTime}, clientIp ${handleItem.value.clientIp}`);
  handleItem = await iter.next();
}

使用 byPage() 的示例:

// passing optional maxPageSize in the page settings
let i = 1;
for await (const response of dirClient.listHandles({ recursive: true }).byPage({ maxPageSize: 20 })) {
  if (response.handleList) {
    for (const handle of response.handleList) {
      console.log(`Handle ${i++}: ${handle.path}, opened time ${handle.openTime}, clientIp ${handle.clientIp}`);
    }
  }
}

使用带标记的分页的示例:

let i = 1;
let iterator = dirClient.listHandles().byPage({ maxPageSize: 2 });
let response = await iterator.next();

// Prints 2 handles
if (response.value.handleList) {
  for (const handle of response.value.handleList) {
    console.log(`Handle ${i++}: ${handle.path}, opened time ${handle.openTime}, clientIp ${handle.clientIp}`);
  }
}

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

// Passing next marker as continuationToken
console.log(`    continuation`);
iterator = dirClient.listHandles().byPage({ continuationToken: marker, maxPageSize: 10 });
response = await iterator.next();

// Prints 2 more handles assuming you have more than four directory/files opened
if (!response.done && response.value.handleList) {
  for (const handle of response.value.handleList) {
    console.log(`Handle ${i++}: ${handle.path}, opened time ${handle.openTime}, clientIp ${handle.clientIp}`);
  }
}
function listHandles(options?: DirectoryListHandlesOptions): PagedAsyncIterableIterator<HandleItem, DirectoryListHandlesResponse, PageSettings>

参数

options
DirectoryListHandlesOptions

用于列出句柄操作的选项。

支持分页的 asyncIterableIterator。

返回

rename(string, DirectoryRenameOptions)

重命名目录。 此 API 仅支持重命名同一共享中的目录。

function rename(destinationPath: string, options?: DirectoryRenameOptions): Promise<{ destinationDirectoryClient: ShareDirectoryClient, directoryRenameResponse: DirectoryRenameResponse }>

参数

destinationPath

string

指定要重命名的目标路径。 将对该路径进行编码以放入 URL 以指定目标。

options
DirectoryRenameOptions

重命名操作的选项。

返回

Promise<{ destinationDirectoryClient: ShareDirectoryClient, directoryRenameResponse: DirectoryRenameResponse }>

文件重命名操作的响应数据。

用法示例:


// Rename the directory
await diretoryClient.rename(destinationPath);
console.log("Renamed directory successfully!");

setMetadata(Metadata, DirectorySetMetadataOptions)

汇报指定目录的用户定义元数据。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/set-directory-metadata

function setMetadata(metadata?: Metadata, options?: DirectorySetMetadataOptions): Promise<DirectorySetMetadataResponse>

参数

metadata
Metadata

如果未提供元数据,则将删除所有现有目录元数据

options
DirectorySetMetadataOptions

目录设置元数据操作的选项。

返回

目录集元数据操作的响应数据。

setProperties(DirectoryProperties)

设置目录的属性。

请参见https://docs.microsoft.com/en-us/rest/api/storageservices/set-directory-properties

function setProperties(properties?: DirectoryProperties): Promise<DirectorySetPropertiesResponse>

参数

properties
DirectoryProperties

返回