你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
ShareFileClient class
ShareFileClient 表示 Azure 存储文件的 URL。
- 扩展
-
StorageClient
构造函数
| Share |
创建 ShareFileClient 的实例。 |
| Share |
创建 ShareFileClient 的实例。 |
属性
| name | 文件的名称 |
| path | 文件的完整路径 |
| share |
与此文件客户端对应的共享名称 |
继承属性
| account |
|
| url | URL 字符串值。 |
方法
构造函数详细信息
ShareFileClient(string, Credential_2 | TokenCredential, ShareClientOptions)
创建 ShareFileClient 的实例。
new ShareFileClient(url: string, credential?: Credential_2 | TokenCredential, options?: ShareClientOptions)参数
- url
-
string
指向 Azure 存储文件的 URL 字符串，例如“https://myaccount.file.core.windows.net/myshare/mydirectory/file"”。 如果使用 AnonymousCredential，则可以追加 SAS，例如“https://myaccount.file.core.windows.net/myshare/mydirectory/file?sasString"”。 此方法接受指向文件的编码 URL 或非编码 URL。 编码的 URL 字符串不会转义两次，只会转义 URL 路径中的特殊字符。 但是，如果文件或目录名称包含 %，则必须在 URL 中对文件或目录名称进行编码。 例如名为“myfile%”的文件，URL 应为“https://myaccount.file.core.windows.net/myshare/mydirectory/myfile%25"”。
- credential
例如 ，StorageSharedKeyCredential 或 TokenCredential，如果未指定，则使用 AnonymousCredential。
- options
- ShareClientOptions
可选。 用于配置 HTTP 管道的选项。
ShareFileClient(string, Pipeline, ShareClientConfig)
创建 ShareFileClient 的实例。
new ShareFileClient(url: string, pipeline: Pipeline, options?: ShareClientConfig)参数
- url
-
string
指向 Azure 存储文件的 URL 字符串，例如“https://myaccount.file.core.windows.net/myshare/mydirectory/file"”。 如果使用 AnonymousCredential，则可以追加 SAS，例如“https://myaccount.file.core.windows.net/myshare/mydirectory/file?sasString"”。 此方法接受指向文件的编码 URL 或非编码 URL。 编码的 URL 字符串不会转义两次，只会转义 URL 路径中的特殊字符。 但是，如果文件或目录名称包含 %，则必须在 URL 中对文件或目录名称进行编码。 例如名为“myfile%”的文件，URL 应为“https://myaccount.file.core.windows.net/myshare/mydirectory/myfile%25"”。
- pipeline
- Pipeline
调用 newPipeline () 以创建默认管道或提供自定义管道。
- options
- ShareClientConfig
属性详细信息
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
方法详细信息
abortCopyFromURL(string, FileAbortCopyFromURLOptions)
中止挂起的复制文件操作，并保留具有零长度和完整元数据的目标文件。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/abort-copy-file
function abortCopyFromURL(copyId: string, options?: FileAbortCopyFromURLOptions): Promise<FileAbortCopyResponse>参数
- copyId
-
string
要中止的复制文件操作的 ID。
- options
- FileAbortCopyFromURLOptions
“从 URL 中中止复制文件”操作的选项。
返回
Promise<FileAbortCopyResponse>
clearRange(number, number, FileClearRangeOptions)
清除指定范围并释放存储中用于该范围的空间。
function clearRange(offset: number, contentLength: number, options?: FileClearRangeOptions): Promise<FileUploadRangeResponse>参数
- offset
-
number
- contentLength
-
number
- options
- FileClearRangeOptions
文件清除范围操作的选项。
返回
Promise<FileUploadRangeResponse>
create(number, FileCreateOptions)
创建新文件或替换文件。 请注意，它仅初始化不带内容的文件。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/create-file
function create(size: number, options?: FileCreateOptions): Promise<FileCreateResponse>参数
- size
-
number
指定文件的最大大小（以字节为单位），最大为 4 TB。
- options
- FileCreateOptions
文件创建操作的选项。
返回
Promise<FileCreateResponse>
文件创建操作的响应数据。
用法示例：
const content = "Hello world!";
// Create the file
await fileClient.create(content.length);
console.log("Created file successfully!");
// Then upload data to the file
await fileClient.uploadRange(content, 0, content.length);
console.log("Updated file successfully!")
delete(FileDeleteOptions)
从存储帐户中删除文件。 成功删除文件后，它将从存储帐户的索引中删除，客户端不再能访问。 该文件的数据将在稍后的垃圾回收期间从服务中删除。
如果文件在 SMB 客户端上打开，则删除文件将失败，状态代码 409 (冲突) 和错误代码 SharingViolation。
共享快照（共享的只读副本）不支持删除文件。 尝试对共享快照执行此操作将失败，400 (InvalidQueryParameterValue)
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-file2
function delete(options?: FileDeleteOptions): Promise<FileDeleteResponse>参数
- options
- FileDeleteOptions
文件删除操作的选项。
返回
Promise<FileDeleteResponse>
文件删除操作的响应数据。
deleteIfExists(FileDeleteOptions)
从存储帐户中删除文件（如果存在）。 成功删除文件后，它将从存储帐户的索引中删除，客户端不再能访问。 该文件的数据将在稍后的垃圾回收期间从服务中删除。
如果文件在 SMB 客户端上打开，则删除文件将失败，状态代码 409 (冲突) 和错误代码 SharingViolation。
共享快照（共享的只读副本）不支持删除文件。 尝试对共享快照执行此操作将失败，400 (InvalidQueryParameterValue)
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/delete-file2
function deleteIfExists(options?: FileDeleteOptions): Promise<FileDeleteIfExistsResponse>参数
- options
- FileDeleteOptions
返回
Promise<FileDeleteIfExistsResponse>
download(number, number, FileDownloadOptions)
从系统读取或下载文件，包括其元数据和属性。
- 在 Node.js 中，数据在可读流中返回
readableStreamBody - 在浏览器中，数据在承诺中返回
contentAsBlob
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/get-file
function download(offset?: number, count?: number, options?: FileDownloadOptions): Promise<FileDownloadResponseModel>参数
- offset
-
number
要下载的文件从哪个位置下载，大于或等于 0
- count
-
number
要下载的数据量，大于 0。 未定义时将下载到末尾
- options
- FileDownloadOptions
文件下载操作的选项。
返回
Promise<FileDownloadResponseModel>
文件下载操作的响应数据。
示例用法 (Node.js) ：
// Download a file to a string
const downloadFileResponse = await fileClient.download();
console.log(
"Downloaded file content:",
(await streamToBuffer(downloadFileResponse.readableStreamBody)).toString()}
);
// A helper method used to read a Node.js readable stream into string
async function streamToBuffer(readableStream) {
return new Promise((resolve, reject) => {
const chunks = [];
readableStream.on("data", (data) => {
chunks.push(data instanceof Buffer ? data : Buffer.from(data));
});
readableStream.on("end", () => {
resolve(Buffer.concat(chunks));
});
readableStream.on("error", reject);
});
}
) (浏览器的示例用法：
// Download a file to a string
const downloadFileResponse = await fileClient.download(0);
console.log(
"Downloaded file content:",
await blobToString(await downloadFileResponse.blobBody)}
);
// A helper method used to convert a browser Blob into string.
export async function blobToString(blob: Blob): Promise<string> {
const fileReader = new FileReader();
return new Promise<string>((resolve, reject) => {
fileReader.onloadend = (ev: any) => {
resolve(ev.target!.result);
};
fileReader.onerror = reject;
fileReader.readAsText(blob);
});
}
downloadToBuffer(Buffer, number, number, FileDownloadToBufferOptions)
仅在 NODE.JS RUNTIME 中可用。
将 Azure 文件并行下载到缓冲区。 偏移量和计数是可选的，两者都传递 0 以下载整个文件。
警告：由于 Node.js/V8 的限制，缓冲区在 32 位系统上最多只能支持大约 1 GB 的文件，在 64 位系统上只能支持大约 2 GB 的文件。 对于大于此大小的文件，请考虑 downloadToFile。
function downloadToBuffer(buffer: Buffer, offset?: number, count?: number, options?: FileDownloadToBufferOptions): Promise<Buffer>参数
- buffer
-
Buffer
要填充的缓冲区，长度必须大于计数
- offset
-
number
要从哪个位置下载 Azure 文件
- count
-
number
要下载的数据量。 传递未定义时，将下载到末尾
- options
- FileDownloadToBufferOptions
返回
Promise<Buffer>
downloadToBuffer(number, number, FileDownloadToBufferOptions)
仅在 NODE.JS RUNTIME 中可用
将 Azure 文件并行下载到缓冲区。 偏移量和计数是可选的，两者都传递 0 以下载整个文件
警告：由于 Node.js/V8 的限制，缓冲区在 32 位系统上最多只能支持大约 1 GB 的文件，在 64 位系统上只能支持大约 2 GB 的文件。 对于大于此大小的文件，请考虑 downloadToFile。
function downloadToBuffer(offset?: number, count?: number, options?: FileDownloadToBufferOptions): Promise<Buffer>参数
- offset
-
number
要从哪个位置下载 Azure 文件
- count
-
number
要下载的数据量。 传递未定义时，将下载到末尾
- options
- FileDownloadToBufferOptions
返回
Promise<Buffer>
downloadToFile(string, number, number, FileDownloadOptions)
仅在 NODE.JS RUNTIME 中可用。
将 Azure Blob 下载到本地文件。 如果给定的文件路径已退出，则失败。 偏移量和计数是可选的，分别传递 0 和未定义以下载整个 Blob。
function downloadToFile(filePath: string, offset?: number, count?: number, options?: FileDownloadOptions): Promise<FileDownloadResponseModel>参数
- filePath
-
string
- offset
-
number
要从哪个位置下载块 Blob。
- count
-
number
要下载的数据量。 传递未定义时，将下载到末尾。
- options
- FileDownloadOptions
Blob 下载选项的选项。
返回
Promise<FileDownloadResponseModel>
Blob 下载操作的响应数据，但当 readableStreamBody 设置为 undefined 时，其内容已读取并写入指定路径处的本地文件。
exists(FileExistsOptions)
如果指定的文件存在，则返回 true;否则为 false。
注意：请谨慎使用此函数，因为现有文件可能被其他客户端或应用程序删除。 反之亦然，此函数完成后，其他客户端或应用程序可能会添加新文件。
function exists(options?: FileExistsOptions): Promise<boolean>参数
- options
- FileExistsOptions
“存在”操作的选项。
返回
Promise<boolean>
forceCloseAllHandles(FileForceCloseHandlesOptions)
强制关闭文件的所有句柄。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles
function forceCloseAllHandles(options?: FileForceCloseHandlesOptions): Promise<CloseHandlesInfo>参数
- options
- FileForceCloseHandlesOptions
强制关闭句柄操作的选项。
返回
Promise<CloseHandlesInfo>
forceCloseHandle(string, FileForceCloseHandlesOptions)
强制关闭文件的特定句柄。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/force-close-handles
function forceCloseHandle(handleId: string, options?: FileForceCloseHandlesOptions): Promise<FileForceCloseHandlesResponse>参数
- handleId
-
string
特定句柄 ID 不能为星号“*”。 使用 forceCloseAllHandles () 关闭所有句柄。
- options
- FileForceCloseHandlesOptions
返回
Promise<FileForceCloseHandlesResponse>
generateSasUrl(FileGenerateSasUrlOptions)
仅适用于使用共享密钥凭据构造的客户端。
根据传入的客户端属性和参数， (SAS) URI 生成服务共享访问签名。 SAS 由客户端的共享密钥凭据签名。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/constructing-a-service-sas
function generateSasUrl(options: FileGenerateSasUrlOptions): string参数
- options
- FileGenerateSasUrlOptions
可选参数。
返回
string
SAS URI 由此客户端表示的资源的 URI 组成，后跟生成的 SAS 令牌。
getProperties(FileGetPropertiesOptions)
返回文件的所有用户定义的元数据、标准 HTTP 属性和系统属性。 它不返回文件的内容。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/get-file-properties
function getProperties(options?: FileGetPropertiesOptions): Promise<FileGetPropertiesResponse>参数
- options
- FileGetPropertiesOptions
文件获取属性操作的选项。
返回
Promise<FileGetPropertiesResponse>
文件获取属性操作的响应数据。
getRangeList(FileGetRangeListOptions)
返回文件的有效范围列表。
function getRangeList(options?: FileGetRangeListOptions): Promise<FileGetRangeListResponse>参数
- options
- FileGetRangeListOptions
文件获取范围列表操作的选项。
返回
Promise<FileGetRangeListResponse>
getRangeListDiff(string, FileGetRangeListOptions)
返回在以前的共享快照和此文件之间不同的范围列表。
function getRangeListDiff(prevShareSnapshot: string, options?: FileGetRangeListOptions): Promise<FileGetRangeListDiffResponse>参数
- prevShareSnapshot
-
string
上一个快照参数是一个不透明的 DateTime 值，用于指定要与之进行比较的上一个共享快照。
- options
- FileGetRangeListOptions
返回
Promise<FileGetRangeListDiffResponse>
getShareLeaseClient(string)
获取管理文件租约的 ShareLeaseClient 。
function getShareLeaseClient(proposeLeaseId?: string): ShareLeaseClient参数
- proposeLeaseId
-
string
初始建议租约 ID。
返回
用于管理文件租约的新 ShareLeaseClient 对象。
listHandles(FileListHandlesOptions)
返回一个异步可迭代迭代器，用于列出所有句柄。 在指定帐户下。
.byPage () 返回一个异步可迭代器，用于列出页面中的句柄。
function listHandles(options?: FileListHandlesOptions): PagedAsyncIterableIterator<HandleItem, FileListHandlesResponse, PageSettings>参数
返回
rename(string, FileRenameOptions)
重命名文件。 此 API 仅支持重命名同一共享中的文件。
function rename(destinationPath: string, options?: FileRenameOptions): Promise<{ destinationFileClient: ShareFileClient, fileRenameResponse: FileRenameResponse }>参数
- destinationPath
-
string
指定要重命名的目标路径。 将对该路径进行编码以放入 URL 以指定目标。
- options
- FileRenameOptions
重命名操作的选项。
返回
Promise<{ destinationFileClient: ShareFileClient, fileRenameResponse: FileRenameResponse }>
文件重命名操作的响应数据。
用法示例：
// Rename the file
await fileClient.rename(destinationPath);
console.log("Renamed file successfully!");
resize(number, FileResizeOptions)
调整文件大小。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties
function resize(length: number, options?: FileResizeOptions): Promise<FileSetHTTPHeadersResponse>参数
- length
-
number
将文件大小调整为指定大小（以字节为单位）。 如果指定的字节值小于当前的文件大小，则会清除超过指定字节值的所有范围。
- options
- FileResizeOptions
文件重设大小操作的选项。
返回
Promise<FileSetHTTPHeadersResponse>
文件集 HTTP 标头操作的响应数据。
setHttpHeaders(FileHttpHeaders, FileSetHttpHeadersOptions)
设置文件中的 HTTP 标头。
如果未提供任何选项，或者选项中没有为文件 HTTP 标头提供值，则会清除这些没有值的文件 HTTP 标头。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties
function setHttpHeaders(fileHttpHeaders?: FileHttpHeaders, options?: FileSetHttpHeadersOptions): Promise<FileSetHTTPHeadersResponse>参数
- fileHttpHeaders
- FileHttpHeaders
- options
- FileSetHttpHeadersOptions
文件设置 HTTP 标头操作的选项。
返回
Promise<FileSetHTTPHeadersResponse>
文件集 HTTP 标头操作的响应数据。
setMetadata(Metadata, FileSetMetadataOptions)
更新指定文件的用户定义元数据。
如果未在选项参数中定义元数据，则将删除文件元数据。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-metadata
function setMetadata(metadata?: Metadata, options?: FileSetMetadataOptions): Promise<FileSetMetadataResponse>参数
- metadata
- Metadata
如果未提供元数据，则将删除所有现有目录元数据
- options
- FileSetMetadataOptions
文件集元数据操作的选项。
返回
Promise<FileSetMetadataResponse>
文件集元数据操作的响应数据。
setProperties(FileProperties)
设置文件的属性。
请参见https://docs.microsoft.com/en-us/rest/api/storageservices/set-file-properties
function setProperties(properties?: FileProperties): Promise<SetPropertiesResponse>参数
- properties
- FileProperties
文件属性。 对于文件 HTTP 标头 (例如 Content-Type) ，如果未提供任何值，则将删除现有的 HTTP 标头。 对于其他文件属性 (例如 fileAttributes) ，如果未提供任何值，则将保留现有值。
返回
Promise<SetPropertiesResponse>
startCopyFromURL(string, FileStartCopyOptions)
将 Blob 或文件复制到存储帐户内的目标文件。
function startCopyFromURL(copySource: string, options?: FileStartCopyOptions): Promise<FileStartCopyResponse>参数
- copySource
-
string
指定源文件或 Blob 的 URL，长度最大为 2 KB。 若要将文件复制到同一存储帐户中的另一个文件，可以使用共享密钥对源文件进行身份验证。 如果要从另一个存储帐户复制文件，或者从同一存储帐户或另一个存储帐户复制 Blob，则必须使用共享访问签名对源文件或 Blob 进行身份验证。 如果源是公共 Blob，则无需身份验证即可执行复制操作。 共享快照中的文件也可以指定为复制源。
- options
- FileStartCopyOptions
文件开始复制操作的选项。
返回
Promise<FileStartCopyResponse>
uploadData(Blob | ArrayBuffer | ArrayBufferView | Buffer, FileParallelUploadOptions)
创建新的 Azure 文件或替换现有的 Azure 文件，然后将缓冲区 (Node) /Blob/ArrayBuffer/ArrayBufferView 上传到其中。
function uploadData(data: Blob | ArrayBuffer | ArrayBufferView | Buffer, options?: FileParallelUploadOptions): Promise<void>参数
- data
-
Blob | ArrayBuffer | ArrayBufferView | Buffer
缓冲区 (节点) 、Blob、ArrayBuffer 或 ArrayBufferView
- options
- FileParallelUploadOptions
返回
Promise<void>
uploadFile(string, FileParallelUploadOptions)
仅在 NODE.JS RUNTIME 中可用。
创建新的 Azure 文件或替换现有的 Azure 文件，然后将本地文件上传到该文件。
function uploadFile(filePath: string, options?: FileParallelUploadOptions): Promise<void>参数
- filePath
-
string
本地文件的完整路径
- options
- FileParallelUploadOptions
返回
Promise<void>
uploadRange(RequestBodyType, number, number, FileUploadRangeOptions)
将字节范围上传到文件。 只能对现有文件调用此操作。 它不会更改文件的大小、属性或元数据。 必须指定范围的开始和计数。 范围最大可以为 4 MB。
function uploadRange(body: RequestBodyType, offset: number, contentLength: number, options?: FileUploadRangeOptions): Promise<FileUploadRangeResponse>参数
- body
- HttpRequestBody
Blob、字符串、ArrayBuffer、ArrayBufferView 或函数，该函数返回新的可读流，其偏移量从数据源开始。
- offset
-
number
要上传的目标 Azure 文件的偏移位置。
- contentLength
-
number
正文的长度（以字节为单位）。 使用 Buffer.byteLength () 计算字符串的正文长度，包括非 Base64/Hex 编码字符。
- options
- FileUploadRangeOptions
文件上传范围操作的选项。
返回
Promise<FileUploadRangeResponse>
文件上传范围操作的响应数据。
用法示例：
const content = "Hello world!";
// Create the file
await fileClient.create(content.length);
console.log("Created file successfully!");
// Then upload data to the file
await fileClient.uploadRange(content, 0, content.length);
console.log("Updated file successfully!")
uploadRangeFromURL(string, number, number, number, FileUploadRangeFromURLOptions)
将一系列字节上传到从另一个文件的 URL 读取内容的文件。 范围最大可以为 4 MB。
function uploadRangeFromURL(sourceURL: string, sourceOffset: number, destOffset: number, count: number, options?: FileUploadRangeFromURLOptions): Promise<FileUploadRangeFromURLResponse>参数
- sourceURL
-
string
指定复制源的 URL、共享访问签名 (SAS) 身份验证可能需要。
- sourceOffset
-
number
要从中复制的源偏移量。 传递 0 以从源文件开头复制。
- destOffset
-
number
目标文件的偏移量。
- count
-
number
要从源文件上传的字节数。
- options
- FileUploadRangeFromURLOptions
用于配置文件 - 从 URL 上传范围操作的选项。
返回
Promise<FileUploadRangeFromURLResponse>
uploadResetableStream((offset: number, count?: number) => ReadableStream, number, FileParallelUploadOptions)
仅在 NODE.JS RUNTIME 中可用。
接受 Node.js 可读流工厂，并在块中上传到 Azure 文件。 可读流工厂必须从定义的偏移量开始返回 Node.js 可读流。 偏移量是要上传的 Azure 文件中的偏移量。
function uploadResetableStream(streamFactory: (offset: number, count?: number) => ReadableStream, size: number, options?: FileParallelUploadOptions): Promise<void>参数
- streamFactory
-
(offset: number, count?: number) => ReadableStream
返回从定义的偏移量开始 Node.js 可读流
- size
-
number
Azure 文件的大小
- options
- FileParallelUploadOptions
返回
Promise<void>
uploadSeekableBlob((offset: number, size: number) => Blob, number, FileParallelUploadOptions)
仅在浏览器中可用。
将浏览器 Blob 对象上传到 Azure 文件。 需要 blobFactory 作为数据源，该数据源需要返回具有提供的偏移量和大小的 Blob 对象。
function uploadSeekableBlob(blobFactory: (offset: number, size: number) => Blob, size: number, options?: FileParallelUploadOptions): Promise<void>参数
- blobFactory
-
(offset: number, size: number) => Blob
- size
-
number
- options
- FileParallelUploadOptions
返回
Promise<void>
uploadStream(Readable, number, number, number, FileUploadStreamOptions)
仅在 NODE.JS RUNTIME 中可用。
创建新的 Azure 文件或替换现有的 Azure 文件，然后将 Node.js 可读流上传到其中。
此方法将尝试创建 Azure 文件，然后开始逐个上传区块。
区块大小由 bufferSize 参数定义。
请确保流的潜在大小不超过文件大小。
性能改进提示：
- 输入流 highWaterMark 最好使用 bufferSize 参数设置相同的值，这将避免 Buffer.concat () 操作。
function uploadStream(stream: Readable, size: number, bufferSize: number, maxBuffers: number, options?: FileUploadStreamOptions): Promise<void>参数
- stream
-
Readable
Node.js 可读流。 必须小于或等于文件大小。
- size
-
number
要创建的文件大小。 允许的最大大小为 4 TB。 如果此值大于流大小，则文件结尾中将存在空字节。
- bufferSize
-
number
每个分配的缓冲区的大小（以字节为单位），以及上传文件期间的区块/范围大小。 大小必须大于 0 且小于或等于 4 * 1024 * 1024 (4MB)
- maxBuffers
-
number
上传期间将分配的最大缓冲区，与最大上传并发正相关
- options
- FileUploadStreamOptions
返回
Promise<void>
withShareSnapshot(string)
创建与源相同但具有指定共享快照时间戳的新 ShareFileClient 对象。 提供“”将删除快照并将 URL 返回到基本 ShareFileClient。
function withShareSnapshot(shareSnapshot: string): ShareFileClient参数
- shareSnapshot
-
string
共享快照时间戳。
返回
与源相同的新 ShareFileClient 对象，但具有指定的共享快照时间戳。