배치 범위
Put Range 작업은 파일에 바이트 범위를 씁니다. 이 작업은 NFS 프로토콜이 설정된 파일 공유에 대해 버전 2025-05-05 이상에서 지원됩니다.
프로토콜 가용성
| 파일 공유 프로토콜 사용 | 이용할 수 있는 |
|---|---|
| SMB |
|
| NFS |
|
요청
Put Range 요청은 다음과 같이 생성됩니다. HTTPS를 사용하는 것이 좋습니다.
| 메서드 | 요청 URI | HTTP 버전 |
|---|---|---|
| 놓다 | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
요청 URI에 표시된 경로 구성 요소를 다음과 같이 사용자 고유의 경로 구성 요소로 바꿉니다.
| 경로 구성 요소 | 묘사 |
|---|---|
myaccount |
스토리지 계정의 이름입니다. |
myshare |
파일 공유의 이름입니다. |
mydirectorypath |
선택적. 부모 디렉터리의 경로입니다. |
myfile |
파일의 이름입니다. |
경로 명명 제한에 대한 자세한 내용은 이름 및 참조 공유, 디렉터리, 파일 및 메타데이터참조하세요.
URI 매개 변수
요청 URI에 다음과 같은 추가 매개 변수를 지정할 수 있습니다.
| 매개 변수 | 묘사 |
|---|---|
timeout |
선택적.
timeout 매개 변수는 초 단위로 표현됩니다. 자세한 내용은 파일 서비스 작업 대한 시간 제한 설정참조하세요. |
요청 헤더
필수 및 선택적 요청 헤더는 다음 표에 설명되어 있습니다.
일반적인 요청 헤더
| 요청 헤더 | 묘사 |
|---|---|
Authorization |
필수. 권한 부여 체계, 계정 이름 및 서명을 지정합니다. 자세한 내용은 Azure Storage대한 요청 권한 부여를 참조하세요. |
Date 또는 x-ms-date |
필수. 요청에 대한 UTC(협정 세계시)를 지정합니다. 자세한 내용은 Azure Storage대한 요청 권한 부여를 참조하세요. |
x-ms-version |
모든 권한 있는 요청에 필요합니다. 이 요청에 사용할 작업의 버전을 지정합니다. 이 작업은 NFS 프로토콜이 설정된 파일 공유에 대해 버전 2025-05-05 이상에서 지원됩니다. 자세한 내용은 Azure Storage 서비스 대한버전 관리를 참조하세요. |
Range 또는 x-ms-range |
Range 또는 x-ms-range 필요합니다.쓸 바이트 범위를 지정합니다. 범위의 시작과 끝을 모두 지정해야 합니다. 이 헤더는 HTTP/1.1 프로토콜 사양의해 정의됩니다. 업데이트 작업의 경우 범위의 크기는 최대 4MiB일 수 있습니다. 명확한 작업의 경우 범위는 파일의 전체 크기 값까지 지정할 수 있습니다. 파일 서비스는 Range 및 x-ms-range 헤더에 대해 단일 바이트 범위만 허용하며 바이트 범위는 bytes=startByte-endByte형식으로 지정해야 합니다.Range 및 x-ms-range 모두 지정된 경우 서비스는 x-ms-range값을 사용합니다. 자세한 내용은 파일 서비스 작업대한 범위 헤더 지정을 참조하세요. |
Content-Length |
필수. 요청 본문에서 전송되는 바이트 수를 지정합니다.
x-ms-write 헤더가 clear설정되면 이 헤더의 값을 0설정해야 합니다. |
Content-MD5 |
선택적. 콘텐츠의 MD5 해시입니다. 이 해시는 전송 중에 데이터의 무결성을 확인하는 데 사용됩니다.
Content-MD5 헤더를 지정하면 Azure Files는 도착한 콘텐츠의 해시와 전송된 헤더 값을 비교합니다. 두 해시가 일치하지 않으면 오류 코드 400(잘못된 요청)으로 인해 작업이 실패합니다.x-ms-write 헤더를 clear설정하면 Content-MD5 헤더가 허용되지 않습니다. 요청에 포함된 경우 파일 서비스는 상태 코드 400(잘못된 요청)을 반환합니다. |
x-ms-write: { update ¦ clear } |
필수. 다음 옵션 중 하나를 지정해야 합니다.
|
x-ms-lease-id:<ID> |
파일에 활성 임대가 있는 경우 필요합니다. 버전 2019-02-02 이상에서 사용할 수 있습니다. 파일이 파일 임대를 지원하지 않는 NFS 프로토콜이 설정된 파일 공유에 있는 경우 이 헤더는 무시됩니다. |
x-ms-client-request-id |
선택적. 로깅이 구성될 때 로그에 기록되는 1kibibyte(KiB) 문자 제한으로 클라이언트에서 생성된 불투명 값을 제공합니다. 이 헤더를 사용하여 클라이언트 쪽 활동과 서버가 수신하는 요청의 상관 관계를 지정하는 것이 좋습니다. 자세한 내용은 Azure Files모니터링을 참조하세요. |
x-ms-file-last-write-time: { now ¦ preserve } |
선택적. 버전 2021-06-08 이상. 다음 옵션 중 하나를 지정할 수 있습니다.
|
x-ms-file-request-intent |
Authorization 헤더가 OAuth 토큰을 지정하는 경우 필수입니다. 허용되는 값은 backup. 이 헤더는 Authorization 헤더를 사용하여 권한이 부여된 ID에 할당된 RBAC 정책에 포함된 경우 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 또는 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 부여하도록 지정합니다. 버전 2022-11-02 이상에서 사용할 수 있습니다. |
x-ms-allow-trailing-dot: { <Boolean> } |
선택적. 버전 2022-11-02 이상. 부울 값은 요청 URL에 있는 후행 점이 잘려야 하는지 여부를 지정합니다. 대상이 NFS 프로토콜을 사용하도록 설정된 파일 공유에 있는 경우 이 헤더는 무시됩니다. 이 헤더는 기본적으로 후행 점을 지원합니다. 자세한 내용은 공유, 디렉터리, 파일 및 메타데이터 명명 및 참조를 참조하세요. |
SMB 전용 요청 헤더
없음.
NFS만 요청 헤더
없음.
요청 본문
업로드할 범위를 나타내는 데이터입니다.
샘플 요청: 바이트 범위 업데이트
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: update
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65535
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
샘플 요청: 바이트 범위 지우기
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=1024-2048
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
응답
응답에는 HTTP 상태 코드와 응답 헤더 집합이 포함됩니다.
상태 코드
작업이 성공하면 상태 코드 201(생성됨)이 반환됩니다. 상태 코드에 대한 자세한 내용은 상태 및 오류 코드참조하세요.
응답 헤더
이 작업에 대한 응답에는 다음 표의 헤더가 포함됩니다. 응답에는 추가 표준 HTTP 헤더도 포함될 수 있습니다. 모든 표준 헤더는 HTTP/1.1 프로토콜 사양준수합니다.
일반적인 응답 헤더
| 응답 헤더 | 묘사 |
|---|---|
ETag |
ETag에는 파일의 버전을 나타내는 값이 포함되어 있습니다. 값은 따옴표로 묶입니다. |
Last-Modified |
디렉터리가 마지막으로 수정된 날짜와 시간을 반환합니다. 날짜 형식은 RFC 1123을 따릅니다. 자세한 내용은 헤더날짜/시간 값을 나타냅니다. 공유 또는 해당 속성 또는 메타데이터를 수정하는 모든 작업은 마지막으로 수정된 시간을 업데이트합니다. 파일에 대한 작업은 공유의 마지막으로 수정된 시간에 영향을 주지 않습니다. |
Content-MD5 |
클라이언트가 메시지 콘텐츠 무결성을 확인할 수 있도록 이 헤더가 반환됩니다. 이 헤더의 값은 파일 서비스에 의해 계산됩니다. 반드시 요청 헤더에 지정된 값과 동일하지는 않습니다. |
x-ms-request-id |
만들어진 요청을 고유하게 식별하며 요청 문제를 해결하는 데 사용할 수 있습니다. 자세한 내용은 API 작업문제 해결을 참조하세요. |
x-ms-version |
요청을 실행하는 데 사용된 파일 서비스 버전을 나타냅니다. |
Date |
서비스에서 생성되는 UTC 날짜/시간 값으로, 응답이 시작된 시간을 나타냅니다. |
x-ms-request-server-encrypted: { true ¦ false } |
버전 2017-04-17 이상. 지정된 알고리즘을 사용하여 요청 내용이 성공적으로 암호화되면 이 헤더의 값이 true 설정됩니다. 그렇지 않으면 값이 false설정됩니다. |
x-ms-client-request-id |
이 헤더를 사용하여 요청 및 해당 응답 문제를 해결할 수 있습니다. 이 헤더의 값은 요청에 있고 값에 표시되는 ASCII 문자가 1,024자 이하인 경우 x-ms-client-request-id 헤더의 값과 같습니다.
x-ms-client-request-id 헤더가 요청에 없으면 응답에 표시되지 않습니다. |
x-ms-file-last-write-time |
버전 2021-06-08 이상. ISO 8601 형식의 파일에 대한 마지막 쓰기 시간입니다. 예: 2017-05-10T17:52:33.9551861Z. |
SMB 전용 응답 헤더
없음.
NFS만 응답 헤더
없음.
응답 본문
없음.
샘플 응답
Response Status:
HTTP/1.1 201 Created
Response Headers:
Transfer-Encoding: chunked
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==
Date:Mon, 27 Jan 2014 22:33:35 GMT
ETag: "0x8CB171BA9E94B0B"
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT
x-ms-version: 2014-02-14
Content-Length: 0
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
권한 부여
계정 소유자만 이 작업을 호출할 수 있습니다.
발언
Put Range 작업은 파일에 바이트 범위를 씁니다. 이 작업은 기존 파일에서만 호출할 수 있습니다. 새 파일을 만들기 위해 호출할 수 없습니다. 현재 존재하지 않는 파일 이름으로 Put Range 호출하면 상태 코드 404(찾을 수 없음)가 반환됩니다.
새 파일을 만들려면 파일 만들기 호출합니다. 파일 크기는 최대 4TiB일 수 있습니다.
Put Range 작업을 완료하려면 MiB당 10분이 허용됩니다. 작업이 평균 MiB당 10분 이상 걸리는 경우 시간이 초과됩니다.
파일에 활성 임대가 있는 경우 클라이언트는 범위를 작성하기 위해 요청에 유효한 임대 ID를 지정해야 합니다.
범위 업데이트 작업
Update 옵션을 사용하여 Put Range 호출하면 지정된 파일에 대한 현재 위치 쓰기가 수행됩니다. 지정된 범위의 모든 콘텐츠를 업데이트로 덮어씁니다. 업데이트 작업에 대한 Put Range 함께 제출되는 각 범위의 크기는 최대 4MiB일 수 있습니다. 4MiB보다 큰 범위를 업로드하려고 하면 서비스에서 상태 코드 413(요청 엔터티가 너무 큼)을 반환합니다.
범위 지우기 작업
Clear 옵션을 사용하여 Put Range 호출하면 지정된 범위가 512바이트로 정렬되는 한 스토리지의 공간이 해제됩니다. 지워진 범위는 더 이상 파일의 일부로 추적되지 않으며 목록 범위 응답에서 반환되지 않습니다. 지정된 범위가 512 바이트 정렬되지 않은 경우 작업은 512 바이트 정렬되지 않은 범위의 시작 또는 끝에 0을 쓰고 512 바이트 정렬된 범위 내의 나머지 범위를 해제합니다.
지워지지 않은 모든 범위는 목록 범위 응답에 반환됩니다. 예를 들어 다음 "샘플 정렬되지 않은 지우기 범위" 섹션을 참조하세요.
파일 임대
임대 파일 호출하여 무한 기간 동안 다른 쓰기에 대해 파일에 대한 단독 쓰기 잠금을 가져올 수 있습니다.
SMB 클라이언트 바이트 범위 잠금
SMB 프로토콜을 사용하면 바이트 범위 잠금이 파일 영역에 대한 읽기 및 쓰기 액세스를 관리할 수 있습니다. 즉, SMB 클라이언트에 x-ms-range사용하여 Put Range 작업에서 지정한 범위와 겹치는 잠금이 있는 경우 SMB 프로토콜이 설정된 파일 공유에 있는 파일의 Put Range 실패합니다. 자세한 내용은 파일 잠금 관리를 참조하세요.
NFS 클라이언트 바이트 범위 잠금
NFS 프로토콜 POSIX 바이트 범위 잠금은 기본적으로 권고되므로 NFS 클라이언트가 보유하는 충돌하는 바이트 범위 잠금이 있더라도 NFS 프로토콜이 설정된 파일 공유에 있는 파일의 Put Range 실패하지 않습니다.
SMB 클라이언트 디렉터리 변경 알림
SMB 프로토콜은 애플리케이션이 파일 시스템에서 변경이 발생하는 시기를 감지할 수 있도록 하는 FindFirstChangeNotification API 함수를 지원합니다. 파일 또는 디렉터리가 추가, 변경 또는 삭제되는 시기와 파일의 크기, 특성 또는 보안 설명자가 변경되는 시기를 감지할 수 있습니다. 이 API를 사용하는 SMB 클라이언트는 Azure Files REST API를 통해 파일 또는 디렉터리 변경이 발생할 때 알림을 받지 않습니다. 그러나 다른 SMB 클라이언트로 인한 변경 내용은 알림을 전파합니다.
샘플 정렬되지 않은 지우기 범위
파일 만들기 파일을 만들고 다음과 같이 Put Range사용하여 단일 범위를 작성한다고 가정합니다.
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
x-ms-write: updte
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT
x-ms-version: 2014-02-14
x-ms-range: bytes=0-65536
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
Content-Length: 65536
파일에서 목록 범위 작업을 수행하면 다음 응답 본문이 반환됩니다.
<?xml version="1.0" ecoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>65536</End>
</Range>
</Ranges>
이제 정렬되지 않은 명확한 범위 바이트 범위 작업이 수행되었다고 가정합니다.
Request Syntax:
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1
Request Headers:
Range: bytes=768-2304
x-ms-write: clear
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT
x-ms-version: 2014-02-14
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=
파일에 대한 후속 목록 범위 작업은 다음 응답 본문을 반환합니다.
<?xml version="1.0" encoding="utf-8"?>
<Ranges>
<Range>
<Start>0</Start>
<End>1024</End>
</Range>
<Range>
<Start>2048</Start>
<End>65535</End>
</Range>
</Ranges>
0은 768-1024 및 2048-2304에서 정렬되지 않은 공간에 기록되었습니다.
공유의 읽기 전용 복사본인 공유 스냅샷에서는 Put Range 지원되지 않습니다. 공유 스냅샷에서 이 작업을 수행하려고 하면 400(InvalidQueryParameterValue)이 실패합니다.