ShareFileClient class

ShareFileClient의 인스턴스를 만듭니다.

new ShareFileClient(url: string, credential?: Credential | TokenCredential, options?: ShareClientOptions)

매개 변수

ShareFileClient의 인스턴스를 만듭니다.

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

매개 변수

파일의 이름입니다.

string name

속성 값

파일의 전체 경로

string path

속성 값

이 파일 클라이언트에 해당하는 공유 이름

string shareName

속성 값

accountName: string

속성 값

StorageClient.accountName에서 상속된

URL 문자열 값입니다.

url: string

속성 값

StorageClient.url에서 상속된

보류 중인 파일 복사 작업을 중단하고 길이가 0인 대상 파일과 전체 메타데이터를 남깁니다.

https://learn.microsoft.com/rest/api/storageservices/abort-copy-file 참조

function abortCopyFromURL(copyId: string, options?: FileAbortCopyFromURLOptions): Promise<FileAbortCopyResponse>

매개 변수

반환

지정된 범위를 지우고 해당 범위에 대한 스토리지에 사용되는 공간을 해제합니다.

function clearRange(offset: number, contentLength: number, options?: FileClearRangeOptions): Promise<FileUploadRangeResponse>

매개 변수

반환

새 파일을 만들거나 파일을 대체합니다. 콘텐츠가 없는 파일만 초기화합니다.

https://learn.microsoft.com/rest/api/storageservices/create-file 참조

function create(size: number, options?: FileCreateOptions): Promise<FileCreateResponse>

매개 변수

반환

파일 만들기 작업에 대한 응답 데이터입니다.

사용 예:

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 directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

const content = "Hello World!";
const fileName = `newdirectory${+new Date()}`;
const fileClient = directoryClient.getFileClient(fileName);
await fileClient.create(content.length);
console.log(`Create file ${fileName} successfully`);

// Upload file range
await fileClient.uploadRange(content, 0, content.length);
console.log(`Upload file range "${content}" to ${fileName} successfully`);

NFS만 해당됩니다. 경로로 지정된 파일 파일에 대한 하드 링크를 만듭니다.

function createHardLink(targetFile: string, options?: FileCreateHardLinkOptions): Promise<FileCreateHardLinkResponse>

매개 변수

반환

NFS만 해당됩니다. 기호 링크를 만듭니다.

function createSymbolicLink(linkText: string, options?: FileCreateSymbolicLinkOptions): Promise<FileCreateSymbolicLinkResponse>

매개 변수

반환

스토리지 계정에서 파일을 제거합니다. 파일이 성공적으로 삭제되면 스토리지 계정의 인덱스에서 즉시 제거되고 클라이언트가 더 이상 액세스할 수 없습니다. 파일의 데이터는 나중에 가비지 수집 중에 서비스에서 제거됩니다.

SMB 클라이언트에서 파일이 열려 있으면 상태 코드 409(충돌) 및 오류 코드 SharingViolation으로 파일 삭제가 실패합니다.

공유의 읽기 전용 복사본인 공유 스냅샷에서는 파일 삭제가 지원되지 않습니다. 공유 스냅샷에서 이 작업을 수행하려고 하면 400(InvalidQueryParameterValue)으로 실패합니다.

https://learn.microsoft.com/rest/api/storageservices/delete-file2 참조

function delete(options?: FileDeleteOptions): Promise<FileDeleteResponse>

매개 변수

반환

파일 삭제 작업에 대한 응답 데이터입니다.

파일이 있는 경우 스토리지 계정에서 파일을 제거합니다. 파일이 성공적으로 삭제되면 스토리지 계정의 인덱스에서 즉시 제거되고 클라이언트가 더 이상 액세스할 수 없습니다. 파일의 데이터는 나중에 가비지 수집 중에 서비스에서 제거됩니다.

SMB 클라이언트에서 파일이 열려 있으면 상태 코드 409(충돌) 및 오류 코드 SharingViolation으로 파일 삭제가 실패합니다.

공유의 읽기 전용 복사본인 공유 스냅샷에서는 파일 삭제가 지원되지 않습니다. 공유 스냅샷에서 이 작업을 수행하려고 하면 400(InvalidQueryParameterValue)으로 실패합니다.

https://learn.microsoft.com/rest/api/storageservices/delete-file2 참조

function deleteIfExists(options?: FileDeleteOptions): Promise<FileDeleteIfExistsResponse>

매개 변수

반환

메타데이터 및 속성을 포함하여 시스템에서 파일을 읽거나 다운로드합니다.

• Node.js데이터는 읽기 가능한 스트림 readableStreamBody 반환됩니다.
• 브라우저에서 데이터는 프라미스 contentAsBlob 반환됩니다.

https://learn.microsoft.com/rest/api/storageservices/get-file 참조

function download(offset?: number, count?: number, options?: FileDownloadOptions): Promise<FileDownloadResponseModel>

매개 변수

반환

파일 다운로드 작업에 대한 응답 데이터입니다.

예제 사용량(Node.js):

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 fileName = "<file name>";
const fileClient = serviceClient
  .getShareClient(shareName)
  .rootDirectoryClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In Node.js, get downloaded data by accessing downloadFileResponse.readableStreamBody
const downloadFileResponse = await fileClient.download();
if (downloadFileResponse.readableStreamBody) {
  const buffer = await streamToBuffer(downloadFileResponse.readableStreamBody);
  console.log(`Downloaded file content: ${buffer.toString()}`);
}

// [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
async function streamToBuffer(readableStream: NodeJS.ReadableStream): Promise<Buffer> {
  return new Promise((resolve, reject) => {
    const chunks: Buffer[] = [];
    readableStream.on("data", (data) => {
      chunks.push(data instanceof Buffer ? data : Buffer.from(data));
    });
    readableStream.on("end", () => {
      resolve(Buffer.concat(chunks));
    });
    readableStream.on("error", reject);
  });
}

사용 예(브라우저):

import { ShareServiceClient } from "@azure/storage-file-share";

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

const serviceClient = new ShareServiceClient(`https://${account}.file.core.windows.net?${sas}`);

const shareName = "<share name>";
const fileName = "<file name>";
const fileClient = serviceClient
  .getShareClient(shareName)
  .rootDirectoryClient.getFileClient(fileName);

// Get file content from position 0 to the end
// In browsers, get downloaded data by accessing downloadFileResponse.blobBody
const downloadFileResponse = await fileClient.download(0);
if (downloadFileResponse.blobBody) {
  console.log(`Downloaded file content: ${(await downloadFileResponse.blobBody).text()}`);
}

NODE.JS 런타임에서만 사용할 수 있습니다.

버퍼와 병렬로 Azure 파일을 다운로드합니다. 오프셋 및 개수는 선택 사항이며, 전체 파일을 다운로드하려면 둘 다 0을 전달합니다.

경고: 버퍼는 Node.js/V8의 제한으로 인해 32비트 시스템에서 최대 1GB 또는 64비트 시스템에서 약 2GB의 파일만 지원할 수 있습니다. 이 크기보다 큰 파일의 경우 downloadToFile 것이 좋습니다.

function downloadToBuffer(buffer: Buffer, offset?: number, count?: number, options?: FileDownloadToBufferOptions): Promise<Buffer>

매개 변수

반환

NODE.JS 런타임에서만 사용 가능

버퍼와 병렬로 Azure 파일을 다운로드합니다. 오프셋 및 개수는 선택 사항이며, 전체 파일을 다운로드하려면 둘 다 0을 전달합니다.

경고: 버퍼는 Node.js/V8의 제한으로 인해 32비트 시스템에서 최대 1GB 또는 64비트 시스템에서 약 2GB의 파일만 지원할 수 있습니다. 이 크기보다 큰 파일의 경우 downloadToFile 것이 좋습니다.

function downloadToBuffer(offset?: number, count?: number, options?: FileDownloadToBufferOptions): Promise<Buffer>

매개 변수

반환

NODE.JS 런타임에서만 사용할 수 있습니다.

로컬 파일에 Azure Blob을 다운로드합니다. 지정된 파일 경로가 이미 종료되면 실패합니다. 오프셋 및 개수는 선택 사항이며, 각각 0과 정의되지 않은 값을 전달하여 전체 Blob을 다운로드합니다.

function downloadToFile(filePath: string, offset?: number, count?: number, options?: FileDownloadOptions): Promise<FileDownloadResponseModel>

매개 변수

반환

Blob 다운로드 작업에 대한 응답 데이터이지만 읽기 가능한StreamBody는 해당 콘텐츠가 지정된 경로의 로컬 파일에 이미 읽고 쓰여졌기 때문에 정의되지 않은 상태로 설정됩니다.

지정된 파일이 있으면 true를 반환합니다. false이면 false입니다.

참고: 다른 클라이언트 또는 애플리케이션에서 기존 파일을 삭제할 수 있기 때문에 이 함수를 주의해서 사용합니다. 그 반대로 이 함수가 완료된 후 다른 클라이언트 또는 애플리케이션에서 새 파일을 추가할 수 있습니다.

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

매개 변수

반환

파일에 대한 모든 핸들을 강제로 닫습니다.

https://learn.microsoft.com/rest/api/storageservices/force-close-handles 참조

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

매개 변수

반환

파일에 대한 특정 핸들을 강제로 닫습니다.

https://learn.microsoft.com/rest/api/storageservices/force-close-handles 참조

function forceCloseHandle(handleId: string, options?: FileForceCloseHandlesOptions): Promise<FileForceCloseHandlesResponse>

매개 변수

반환

공유 키 자격 증명을 사용하여 생성된 클라이언트에만 사용할 수 있습니다.

전달된 클라이언트 속성 및 매개 변수를 기반으로 SAS(서비스 공유 액세스 서명) URI에 서명하는 문자열을 생성합니다. SAS는 클라이언트의 공유 키 자격 증명으로 서명됩니다.

https://learn.microsoft.com/rest/api/storageservices/constructing-a-service-sas 참조

function generateSasStringToSign(options: FileGenerateSasUrlOptions): string

매개 변수

반환

이 클라이언트가 나타내는 리소스에 대한 URI로 구성된 SAS URI와 생성된 SAS 토큰이 뒤따릅니다.

공유 키 자격 증명을 사용하여 생성된 클라이언트에만 사용할 수 있습니다.

전달된 클라이언트 속성 및 매개 변수를 기반으로 SAS(서비스 공유 액세스 서명) URI를 생성합니다. SAS는 클라이언트의 공유 키 자격 증명으로 서명됩니다.

https://learn.microsoft.com/rest/api/storageservices/constructing-a-service-sas 참조

function generateSasUrl(options: FileGenerateSasUrlOptions): string

매개 변수

반환

이 클라이언트가 나타내는 리소스에 대한 URI로 구성된 SAS URI와 생성된 SAS 토큰이 뒤따릅니다.

파일에 대한 모든 사용자 정의 메타데이터, 표준 HTTP 속성 및 시스템 속성을 반환합니다. 파일의 내용을 반환하지 않습니다.

https://learn.microsoft.com/rest/api/storageservices/get-file-properties 참조

function getProperties(options?: FileGetPropertiesOptions): Promise<FileGetPropertiesResponse>

매개 변수

반환

파일 가져오기 속성 작업에 대한 응답 데이터입니다.

파일의 유효한 범위 목록을 반환합니다.

function getRangeList(options?: FileGetRangeListOptions): Promise<FileGetRangeListResponse>

매개 변수

반환

이전 공유 스냅샷과 이 파일 간에 다른 범위 목록을 반환합니다.

function getRangeListDiff(prevShareSnapshot: string, options?: FileGetRangeListOptions): Promise<FileGetRangeListDiffResponse>

매개 변수

반환

파일에서 임대를 관리하는 ShareLeaseClient 가져옵니다.

function getShareLeaseClient(proposeLeaseId?: string): ShareLeaseClient

매개 변수

반환

파일에서 임대를 관리하기 위한 새 ShareLeaseClient 개체입니다.

NFS만 해당됩니다. 심볼 링크의 내용을 가져옵니다.

function getSymbolicLink(options?: FileGetSymbolicLinkOptions): Promise<FileGetSymbolicLinkResponse>

매개 변수

반환

모든 핸들을 나열하는 비동기 반복기를 반환합니다. 지정된 계정 아래에 있습니다.

.byPage()는 비동기 반복 반복기를 반환하여 페이지의 핸들을 나열합니다.

function listHandles(options?: FileListHandlesOptions): PagedAsyncIterableIterator<HandleItem, FileListHandlesResponse, PageSettings>

매개 변수

반환

파일 이름을 바꿉니다. 이 API는 동일한 공유의 파일 이름 바꾸기만 지원합니다.

function rename(destinationPath: string, options?: FileRenameOptions): Promise<{ destinationFileClient: ShareFileClient, fileRenameResponse: FileRenameResponse }>

매개 변수

반환

파일 이름 바꾸기 작업에 대한 응답 데이터입니다.

사용 예:

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 fileName = "<file name>";
const destinationPath = "<destination path>";
const fileClient = serviceClient
  .getShareClient(shareName)
  .getDirectoryClient(directoryName)
  .getFileClient(fileName);

await fileClient.rename(destinationPath);

파일 크기를 조정합니다.

https://learn.microsoft.com/rest/api/storageservices/set-file-properties 참조

function resize(length: number, options?: FileResizeOptions): Promise<FileSetHTTPHeadersResponse>

매개 변수

반환

파일 집합 HTTP 헤더 작업에 대한 응답 데이터입니다.

파일에서 HTTP 헤더를 설정합니다.

옵션이 제공되지 않거나 옵션에서 파일 HTTP 헤더에 대한 값이 제공되지 않은 경우 값이 없는 이러한 파일 HTTP 헤더는 지워지게 됩니다.

https://learn.microsoft.com/rest/api/storageservices/set-file-properties 참조

function setHttpHeaders(fileHttpHeaders?: FileHttpHeaders, options?: FileSetHttpHeadersOptions): Promise<FileSetHTTPHeadersResponse>

매개 변수

반환

파일 집합 HTTP 헤더 작업에 대한 응답 데이터입니다.

지정된 파일에 대한 사용자 정의 메타데이터를 업데이트합니다.

옵션 매개 변수에 정의된 메타데이터가 없으면 파일 메타데이터가 제거됩니다.

https://learn.microsoft.com/rest/api/storageservices/set-file-metadata 참조

function setMetadata(metadata?: Metadata, options?: FileSetMetadataOptions): Promise<FileSetMetadataResponse>

매개 변수

반환

파일 집합 메타데이터 작업에 대한 응답 데이터입니다.

파일의 속성을 설정합니다.

https://learn.microsoft.com/rest/api/storageservices/set-file-properties 참조

function setProperties(properties?: FileProperties): Promise<SetPropertiesResponse>

매개 변수

반환

스토리지 계정 내의 대상 파일에 Blob 또는 파일을 복사합니다.

function startCopyFromURL(copySource: string, options?: FileStartCopyOptions): Promise<FileStartCopyResponse>

매개 변수

반환

새 Azure 파일을 만들거나 기존 Azure 파일을 대체한 다음 버퍼(Node)/Blob/ArrayBuffer/ArrayBufferView를 업로드합니다.

function uploadData(data: Blob | ArrayBuffer | ArrayBufferView | Buffer, options?: FileParallelUploadOptions): Promise<void>

매개 변수

반환

NODE.JS 런타임에서만 사용할 수 있습니다.

새 Azure 파일을 만들거나 기존 Azure 파일을 바꾼 다음 로컬 파일을 업로드합니다.

function uploadFile(filePath: string, options?: FileParallelUploadOptions): Promise<void>

매개 변수

반환

파일에 바이트 범위를 업로드합니다. 이 작업은 기존 파일에서만 호출할 수 있습니다. 파일의 크기, 속성 또는 메타데이터는 변경되지 않습니다. 범위의 시작 및 개수를 모두 지정해야 합니다. 범위의 크기는 최대 4MB입니다.

function uploadRange(body: RequestBodyType, offset: number, contentLength: number, options?: FileUploadRangeOptions): Promise<FileUploadRangeResponse>

매개 변수

반환

파일 업로드 범위 작업에 대한 응답 데이터입니다.

사용 예:

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 directoryClient = serviceClient.getShareClient(shareName).getDirectoryClient(directoryName);

const content = "Hello World!";
const fileName = `newdirectory${+new Date()}`;
const fileClient = directoryClient.getFileClient(fileName);
await fileClient.create(content.length);
console.log(`Create file ${fileName} successfully`);

// Upload file range
await fileClient.uploadRange(content, 0, content.length);
console.log(`Upload file range "${content}" to ${fileName} successfully`);

다른 파일의 URL에서 콘텐츠를 읽는 파일에 바이트 범위를 업로드합니다. 범위의 크기는 최대 4MB입니다.

function uploadRangeFromURL(sourceURL: string, sourceOffset: number, destOffset: number, count: number, options?: FileUploadRangeFromURLOptions): Promise<FileUploadRangeFromURLResponse>

매개 변수

반환

NODE.JS 런타임에서만 사용할 수 있습니다.

Node.js 읽기 가능한 스트림 팩터리를 수락하고 블록 단위로 Azure File에 업로드합니다. 읽기 가능한 스트림 팩터리는 정의된 오프셋에서 시작하는 Node.js 읽기 가능한 스트림을 반환해야 합니다. 오프셋은 업로드할 Azure 파일의 오프셋입니다.

function uploadResetableStream(streamFactory: (offset: number, count?: number) => ReadableStream, size: number, options?: FileParallelUploadOptions): Promise<void>

매개 변수

반환

브라우저에서만 사용할 수 있습니다.

브라우저 Blob 개체를 Azure 파일에 업로드합니다. 제공된 오프셋 및 크기가 있는 Blob 개체를 반환해야 하는 데이터 원본으로 BlobFactory가 필요합니다.

function uploadSeekableBlob(blobFactory: (offset: number, size: number) => Blob, size: number, options?: FileParallelUploadOptions): Promise<void>

매개 변수

반환

NODE.JS 런타임에서만 사용할 수 있습니다.

새 Azure 파일을 만들거나 기존 Azure 파일을 바꾼 다음 Node.js 읽기 가능한 스트림을 업로드합니다. 이 메서드는 Azure 파일을 만든 다음 청크로 청크 업로드를 시작합니다. 청크의 크기는 bufferSize 매개 변수에 의해 정의됩니다. 스트림의 잠재적 크기가 파일 크기를 초과하지 않는지 확인하세요.

성능 향상 팁:

• 입력 스트림 highWaterMark는 Buffer.concat() 작업을 방지하는 bufferSize 매개 변수를 사용하여 동일한 값을 설정하는 것이 좋습니다.

function uploadStream(stream: Readable, size: number, bufferSize: number, maxBuffers: number, options?: FileUploadStreamOptions): Promise<void>

매개 변수

반환

원본과 동일하지만 지정된 공유 스냅샷 타임스탬프를 사용하여 새 ShareFileClient 개체를 만듭니다. ""를 입력하면 스냅샷이 제거되고 기본 ShareFileClient에 URL이 반환됩니다.

function withShareSnapshot(shareSnapshot: string): ShareFileClient

매개 변수

반환

새 ShareFileClient 개체는 원본과 동일하지만 지정된 공유 스냅샷 타임스탬프가 있습니다.