파일 복사

아티클
03/29/2023

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

버전 2015-02-21 이상에서 사용할 수 있습니다.

프로토콜 가용성

활성화된 파일 공유 프로토콜	사용 가능
SMB
NFS

요청

다음과 같이 요청을 생성할 Copy File 수 있습니다. HTTPS를 사용하는 것이 좋습니다.

버전 2013-08-15부터 원본 파일과 동일한 계정에 있는 경우 대상 파일에 대한 공유 액세스 서명을 지정할 수 있습니다. 버전 2015-04-05부터 다른 스토리지 계정에 있는 경우 대상 파일에 대한 공유 액세스 서명을 지정할 수도 있습니다.

메서드	요청 URI	HTTP 버전
`PUT`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile`	HTTP/1.1

다음과 같이 요청 URI에 표시된 경로 구성 요소를 사용자 경로 구성 요소로 바꿉니다.

경로 구성 요소	설명
`myaccount`	사용자 스토리지 계정의 이름입니다.
`myshare`	파일 공유 이름입니다.
`mydirectorypath`	선택 사항입니다. 부모 디렉터리 경로입니다.
`myfile`	파일 이름입니다.

경로 명명 제한에 대한 자세한 내용은 공유, 디렉터리, 파일 및 메타데이터 명명 및 참조를 참조하세요.

URI 매개 변수

요청 URI에 다음과 같은 추가 매개 변수를 지정할 수 있습니다.

매개 변수	설명
`timeout`	선택 사항입니다. 시간 초과 매개 변수는 초 단위로 표현됩니다. 자세한 내용은 Azure Files 작업에 대한 시간 제한 설정을 참조하세요.

요청 헤더

다음 표에서는 필수 및 선택적 요청 헤더에 대해 설명합니다.

요청 헤더	Description
`Authorization`	필수 사항입니다. 권한 부여 체계, 계정 이름 및 서명을 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
`Date` 또는 `x-ms-date`	필수 사항입니다. 요청에 대한 UTC(협정 세계시)를 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요.
`x-ms-version`	모든 권한 있는 요청에 필요합니다. 이 요청에 사용할 작업의 버전을 지정합니다. 이 작업은 버전 2015-02-21 이상에서만 사용할 수 있습니다. 자세한 내용은 Azure Storage 서비스에 대한 버전 관리를 참조하세요.
`x-ms-meta-name:value`	선택 사항입니다. 파일과 연결된 이름/값 쌍을 메타데이터로 지정합니다. 이름/값 쌍을 지정하지 않으면 작업은 원본 Blob 또는 파일의 메타데이터를 대상 파일로 복사합니다. 하나 이상의 이름/값 쌍을 지정하면 대상 파일이 지정된 메타데이터로 만들어지고 메타데이터가 원본 Blob 또는 파일에서 복사되지 않습니다. 메타데이터 이름은 C# 식별자에 대한 명명 규칙을 준수해야 합니다. Azure Files 통해 지정된 파일 메타데이터는 SMB 클라이언트에서 액세스할 수 없습니다.
`x-ms-copy-source:name`	필수 사항입니다. 최대 2키비바이트(KiB)의 원본 파일 또는 Blob URL을 지정합니다. 동일한 스토리지 계정 내의 다른 파일에 파일을 복사하려면 공유 키를 사용하여 원본 파일에 권한을 부여할 수 있습니다. 다른 스토리지 계정에서 파일을 복사하거나 동일한 스토리지 계정 또는 다른 스토리지 계정에서 Blob을 복사하는 경우 공유 액세스 서명을 사용하여 원본 파일 또는 Blob에 권한을 부여해야 합니다. 원본이 공용 Blob인 경우 복사 작업을 수행하기 위해 권한 부여가 필요하지 않습니다. 공유 스냅샷 파일을 복사 원본으로 지정할 수도 있습니다. 다음은 원본 개체 URL의 몇 가지 예입니다. `https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile` `https://myaccount.blob.core.windows.net/mycontainer/myblob?sastoken` `http://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>`
`x-ms-lease-id:<ID>`	대상 파일에 활성 임대가 있는 경우 필요합니다. 버전 2019-02-02 이상에 사용할 수 있습니다. 이 헤더에 지정된 임대 ID는 대상 파일의 임대 ID와 일치해야 합니다. 요청에 임대 ID가 포함되지 않거나 ID가 유효하지 않으면 상태 코드 412(사전 조건 실패)로 인해 작업이 실패합니다. 이 헤더를 지정하고 대상 파일에 현재 활성 임대가 없는 경우 상태 코드 412(사전 조건 실패)로 인해 작업이 실패합니다.
`x-ms-file-permission-copy-mode: { source ¦ override }`	선택 사항입니다. 버전 2019-07-07 이상에 사용할 수 있습니다. 파일의 보안 설명자의 복사 동작을 결정합니다. `source`: 대상 파일의 보안 설명자가 원본 파일에서 복사됩니다. `override`: 대상 파일의 보안 설명자는 또는 `x-ms-file-permission-key` 헤더를 `x-ms-file-permission` 통해 결정됩니다.
`x-ms-file-permission`	가 로 `overridex-ms-file-permission-key` 지정되고 가 지정되지 않은 경우 `x-ms-file-permission-copy-mode` 필요합니다. 버전 2019-07-07 이상에 사용할 수 있습니다. 이 권한은 SDDL(보안 설명자 정의 언어)에 지정된 파일의 보안 설명자입니다. 사용 권한 크기가 8kibibytes(KiB) 이하인 경우 이 헤더를 사용할 수 있습니다. 그렇지 않으면 를 사용할 `x-ms-file-permission-key`수 있습니다. 지정된 경우 소유자, 그룹 및 DACL(임의 액세스 제어 목록)이 있어야 합니다. 또는 `x-ms-file-permission-key` 중 `x-ms-file-permission` 하나만 지정할 수 있습니다.
`x-ms-file-permission-key`	가 로 `overridex-ms-file-permission` 지정되고 가 지정되지 않은 경우 `x-ms-file-permission-copy-mode` 필요합니다. 버전 2019-07-07 이상에 사용할 수 있습니다. 이 헤더는 파일에 대해 설정할 권한의 키를 지정합니다. 작업을 사용하여 `Create Permission` 이 키를 만들 수 있습니다. 또는 `x-ms-file-permission-key` 중 `x-ms-file-permission` 하나만 지정할 수 있습니다.
`x-ms-file-copy-ignore-readonly`	선택 사항입니다. 버전 2019-07-07 이상에 사용할 수 있습니다. 이 부울 값은 기존 대상 파일의 `ReadOnly` 특성을 준수해야 하는지 여부를 지정합니다. `true`이 경우 복사 작업이 성공합니다. 그렇지 않으면 특성 집합이 있는 대상의 `ReadOnly` 이전 파일로 인해 복사 작업이 실패합니다.
`x-ms-file-attributes`	선택 사항입니다. 버전 2019-07-07 이상에 사용할 수 있습니다. 이 헤더는 대상 파일에 설정할 파일 시스템 특성을 지정합니다. 사용 가능한 특성 목록을 참조하세요. 값을 `source` 사용하여 원본 파일에서 대상 파일로 특성을 복사할 수 있습니다. 값을 사용하여 대상 파일의 `none` 모든 특성을 지울 수 있습니다.
`x-ms-file-creation-time`	선택 사항입니다. 버전 2019-07-07 이상에 사용할 수 있습니다. 이 헤더는 대상 파일에 설정할 생성 시간(UTC)에 대한 속성을 지정합니다. 값을 `source` 사용하여 원본 파일에서 대상 파일로 만든 시간을 복사할 수 있습니다.
`x-ms-file-last-write-time`	선택 사항입니다. 버전 2019-07-07 이상에 사용할 수 있습니다. 이 헤더는 대상 파일에 설정할 마지막 쓰기 시간의 속성을 UTC로 지정합니다. 값을 `source` 사용하여 원본 파일에서 대상 파일로 마지막 쓰기 시간을 복사할 수 있습니다.
`x-ms-file-copy-set-archive`	선택 사항입니다. 버전 2019-07-07 이상에 사용할 수 있습니다. 이 부울 값은 헤더 값에 `Archive` 관계없이 `x-ms-file-attributes` 특성을 설정할지 여부를 지정합니다.
`x-ms-client-request-id`	선택 사항입니다. 로깅이 구성될 때 로그에 기록되는 1KiB 문자 제한으로 클라이언트에서 생성된 불투명 값을 제공합니다. 이 헤더를 사용하여 클라이언트 쪽 활동과 서버가 수신하는 요청의 상관 관계를 지정하는 것이 좋습니다. 자세한 내용은 Azure Blob Storage 모니터링을 참조하세요.
`x-ms-file-change-time: { <DateTime> ¦ source }`	선택 사항입니다. 버전 2021-06-08 이상. ISO 8601 형식으로 서식이 지정된 파일의 UTC 변경 시간 속성입니다. 의 값을 `source` 사용하여 원본 파일에서 대상 파일로 변경 시간을 복사할 수 있습니다. 기본 타임스탬프는 요청의 시간입니다.
`x-ms-file-request-intent`	헤더가 OAuth 토큰을 지정하는 경우 `Authorization` 필수입니다. 허용되는 값은 입니다 `backup`. 이 헤더는 헤더를 `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` 사용하여 `Authorization` 권한이 부여된 ID에 할당된 RBAC 정책에 포함되는 경우 또는 `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` 를 부여하도록 지정합니다. 버전 2022-11-02 이상에 사용할 수 있습니다.
`x-ms-allow-trailing-dot: { <Boolean> }`	선택 사항입니다. 버전 2022-11-02 이상. 부울 값은 요청 URL에 있는 후행 점을 잘라내야 하는지 여부를 지정합니다. 자세한 내용은 공유, 디렉터리, 파일 및 메타데이터 이름 지정 및 참조를 참조하세요.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	선택 사항입니다. 버전 2022-11-02 이상. 부울 값은 원본 URL에 있는 후행 점을 잘라내야 하는지 여부를 지정합니다. 이 헤더는 복사 원본이 Azure 파일인 경우에만 지정해야 합니다. 이 헤더는 다른 복사 원본 형식에 대해 지원되지 않습니다. 자세한 내용은 공유, 디렉터리, 파일 및 메타데이터 이름 지정 및 참조를 참조하세요.

요청 본문

없음

응답

응답에는 HTTP 상태 코드 및 응답 헤더 집합이 포함되어 있습니다.

상태 코드

작업에 성공하면 상태 코드 202(수락됨)가 반환됩니다.

상태 코드에 대한 자세한 내용은 상태 및 오류 코드를 참조하세요.

응답 헤더

이 작업의 응답에는 다음과 같은 헤더가 포함됩니다. 응답 헤더에는 또한 추가 표준 HTTP 헤더가 포함됩니다. 모든 표준 헤더는 HTTP/1.1 프로토콜 사양을 준수합니다.

응답 헤더	Description
`ETag`	복사 작업이 완료되면 대상 파일의 값이 `ETag` 포함됩니다. 복사 작업이 완료되지 않은 경우 에는 작업 시작 시 생성된 빈 파일의 값이 포함 `ETag` 됩니다.
`Last-Modified`	대상 파일에 대한 복사 작업이 완료된 날짜/시간을 반환합니다.
`x-ms-request-id`	만들어진 요청을 고유하게 식별합니다. 이 헤더를 사용하여 요청 문제를 해결할 수 있습니다. 자세한 내용은 API 작업 문제 해결을 참조하세요.
`x-ms-version`	요청을 실행하는 데 사용되는 Azure Files 버전을 나타냅니다.
`Date`	서비스에서 응답을 보낸 시간을 나타내는 UTC 날짜/시간 값입니다.
`x-ms-copy-id: <id>`	이 복사 작업에 대한 문자열 식별자를 제공합니다. 또는 `Get File Properties` 와 함께 `Get File` 를 사용하여 이 복사 작업의 상태 검사 또는 를 `Abort Copy File` 전달하여 보류 중인 복사 작업을 취소합니다.
`x-ms-copy-status: <success ¦ pending>`	다음 값을 사용하여 복사 작업의 상태를 나타냅니다. - `success`: 복사 작업이 성공적으로 완료되었습니다. - `pending`: 복사 작업이 아직 진행 중입니다.
`x-ms-client-request-id`	요청 및 해당 응답 문제를 해결하는 데 사용할 수 있습니다. 이 헤더의 값은 요청에 있고 값 `x-ms-client-request-id` 이 최대 1,024자 표시 ASCII 문자인 경우 헤더의 값과 같습니다. 헤더가 `x-ms-client-request-id` 요청에 없는 경우 이 헤더는 응답에 존재하지 않습니다.

응답 본문

없음

샘플 응답

Response Status:  
HTTP/1.1 202 Accepted  
  
Response Headers:   
Last-Modified: <date>   
ETag: "0x8CEB669D794AFE2"  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2015-02-21  
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-copy-status: pending  
Date: <date>

권한 부여

이 작업은 계정 소유자 또는 대상 파일 또는 해당 공유에 쓸 수 있는 권한이 있는 공유 액세스 서명을 소유한 클라이언트에서 호출할 수 있습니다. 요청에 지정된 공유 액세스 서명은 대상 파일에만 적용됩니다.

요청 헤더 x-ms-copy-source에 대한 세부 정보에 설명된 대로 원본 파일 또는 Blob에 대한 액세스 권한은 별도로 부여됩니다.

다음 표에서는 작업의 대상 및 원본 개체에 Copy File 권한을 부여하는 방법을 설명합니다.

파일	공유 키 또는 공유 키 라이트를 사용한 권한 부여	공유 액세스 서명을 사용한 권한 부여	권한 부여가 필요하지 않은 공용 개체
대상 파일	예	예	적용할 수 없음
동일한 계정의 원본 파일	예	예	적용할 수 없음
다른 계정의 원본 파일	예	예	적용할 수 없음
동일한 계정 또는 다른 계정의 원본 Blob	예	예	예

파일 시스템 특성

attribute	Win32 파일 특성	정의
`ReadOnly`	`FILE_ATTRIBUTE_READONLY`	파일이 읽기 전용입니다. 애플리케이션은 파일을 읽을 수 있지만 파일을 읽거나 삭제할 수는 없습니다.
`Hidden`	`FILE_ATTRIBUTE_HIDDEN`	파일이 숨겨집니다. 일반 디렉터리 목록에는 포함되지 않습니다.
`System`	`FILE_ATTRIBUTE_SYSTEM`	운영 체제는 파일의 일부를 사용하거나 파일을 단독으로 사용합니다.
`None`	`FILE_ATTRIBUTE_NORMAL`	파일에 다른 특성이 설정되어 있지 않습니다. 이 특성은 단독으로 사용되는 경우에만 유효합니다.
`Archive`	`FILE_ATTRIBUTE_ARCHIVE`	파일은 보관 파일입니다. 애플리케이션은 일반적으로 이 특성을 사용하여 백업 또는 제거를 위해 파일을 표시합니다.
`Temporary`	`FILE_ATTRIBUTE_TEMPORARY`	파일이 임시 스토리지에 사용되고 있습니다.
`Offline`	`FILE_ATTRIBUTE_OFFLINE`	파일의 데이터를 즉시 사용할 수 없습니다. 이 파일 시스템 특성은 주로 Windows와의 호환성을 제공합니다. Azure Files 오프라인 스토리지 옵션을 지원하지 않습니다.
`NotContentIndexed`	`FILE_ATTRIBUTE_NOT_CONTENT_INDEXED`	콘텐츠 인덱싱 서비스는 파일을 인덱싱하지 않습니다.
`NoScrubData`	`FILE_ATTRIBUTE_NO_SCRUB_DATA`	백그라운드 데이터 무결성 스캐너는 사용자 데이터 스트림을 읽지 않습니다. 이 파일 시스템 특성은 주로 Windows와의 호환성을 제공합니다.

설명

작업은 Copy File 비동기적으로 완료할 수 있습니다. 응답 헤더가 반환하는 복사 ID를 x-ms-copy-id 사용하여 복사 작업의 상태 검사 취소할 수 있습니다. Azure Files 최선을 다해 파일을 복사합니다.

대상 파일이 있으면 덮어씁니다. 복사 작업이 진행되는 동안에는 대상 파일을 수정할 수 없습니다.

작업은 Copy File 항상 전체 원본 Blob 또는 파일을 복사합니다. 바이트 범위 또는 블록 세트 복사는 지원되지 않습니다.

작업의 원본 Copy File 은 공유 스냅샷 있는 파일일 수 있습니다. 작업의 대상 Copy File 은 공유 스냅샷 있는 파일이 될 수 없습니다.

복사 작업의 원본이 값을 제공하는 ETag 경우 작업이 진행 중인 동안 원본에 변경 내용이 있는 경우 실패합니다. 복사 작업이 진행 중인 동안 대상 파일을 변경하려는 시도가 상태 코드 409(충돌)로 실패합니다.

ETag 작업이 시작될 때 대상 파일의 값이 Copy File 변경됩니다. 복사 작업 중에 자주 변경됩니다.

속성 및 메타데이터 복사

Blob 또는 파일이 복사되면 다음 시스템 속성이 동일한 값으로 대상 파일에 복사됩니다.

Content-Type
Content-Encoding
Content-Language
Content-Length
Cache-Control
Content-MD5
Content-Disposition

대상 파일은 항상 원본 Blob 또는 파일과 같은 크기입니다. 대상 파일의 Content-Length 헤더 값은 원본 Blob 또는 파일의 해당 헤더 값과 일치합니다.

임대된 Blob 또는 파일을 파일에 복사

작업은 Copy File 원본 Blob 또는 파일에서만 읽으므로 원본 개체에 대한 임대는 작업에 영향을 주지 않습니다. 작업은 Copy File 작업이 시작될 때 원본 Blob 또는 파일의 값을 저장 ETag 합니다. ETag 복사 작업이 완료되기 전에 값이 변경되면 작업이 실패합니다. 복사 작업 중에 파일의 원본 Blob을 임대하여 변경 내용을 방지할 수 있습니다.

대상 파일에 활성 무한 임대가 있는 경우 작업 호출에서 해당 임대 ID를 Copy File 지정해야 합니다. 복사 작업이 보류 중인 동안 대상 파일의 임대 작업은 상태 코드 409(충돌)로 인해 실패합니다. 원본과 이름이 다른 대상 파일로 복사하거나 원본과 이름이 같은 대상 파일로 복사하는 경우 복사 작업 중에 대상 파일에 대한 무한 임대가 이러한 방식으로 잠깁니다. 클라이언트가 아직 존재하지 않는 파일에 임대 ID를 지정하는 경우 Azure Files 코드 412(사전 조건 실패)상태 반환합니다.

보류 중인 복사 작업

Copy File 작업이 비동기적으로 파일 복사를 완료할 수 있습니다. 다음 표를 사용하여 반환되는 상태 코드를 Copy File 기반으로 다음 단계를 결정합니다.

상태 코드	의미
202(수락됨), x-ms-copy-상태: 성공	복사 작업이 성공적으로 완료되었습니다.
202(수락됨), x-ms-copy-상태: 보류 중	복사 작업이 완료되지 않았습니다. 를 사용하여 `Get File Properties` 대상 Blob을 폴링하여 복사 작업이 완료되거나 실패할 때까지 검사 `x-ms-copy-status` 합니다.
4xx, 500 또는 503	복사 작업이 실패했습니다.

작업 중 및 작업 후에 Copy File 대상 파일의 속성에는 작업의 복사 ID Copy File 와 원본 Blob 또는 파일의 URL이 포함됩니다. 작업이 완료되면 Azure Files 대상 파일의 속성에 시간 및 결과 값(success, failed또는 aborted)을 씁니다. 작업에 결과가 있으면 failed 헤더에 x-ms-copy-status-description 오류 세부 정보 문자열이 포함됩니다.

보류 중인 Copy File 작업에는 2주 제한 시간이 있습니다. 2주 후에 완료되지 않았고 필드가 로 설정되고 x-ms-status-description 필드가 500(OperationCancelled)으로 x-ms-copy-status 설정된 failed 빈 파일을 남기는 복사 시도입니다. 복사 작업 중에 발생할 수 있는 일시적인 치명적이지 않은 오류는 작업의 진행을 방해할 수 있지만 실패하지는 않을 수 있습니다. 이러한 경우 x-ms-copy-status-description에 간헐적인 오류에 대한 설명이 제공됩니다.

복사 작업 중에 대상 파일을 수정하려는 시도는 상태 코드 409(충돌), "진행 중인 파일 복사"로 실패합니다.

작업을 호출 Abort Copy File 하면 헤더가 x-ms-copy-status:aborted 표시됩니다. 대상 파일에는 그대로 메타데이터와 파일 길이가 0바이트입니다. 에 대한 원래 호출을 반복하여 Copy File 작업을 다시 시도할 수 있습니다.

결제

작업의 대상 계정은 Copy File 작업을 시작하기 위해 하나의 트랜잭션에 대해 요금이 청구됩니다. 또한 대상 계정은 복사 작업의 상태 취소하거나 요청하기 위해 각 요청에 대해 하나의 트랜잭션을 발생합니다.

원본 파일 또는 Blob이 다른 계정에 있으면 원본 계정에 트랜잭션 비용이 발생합니다. 또한 원본 및 대상 계정이 다른 지역(예: 미국 북부 및 미국 남부)에 있는 경우 요청을 전송하는 데 사용하는 대역폭은 송신으로 원본 계정에 청구됩니다. 동일 지역 내에서 계정 간 송신은 무료입니다.

다음을 통해 공유