범위 배치
Put Range 작업은 바이트 범위를 파일에 씁니다.
프로토콜 가용성
| 파일 공유 프로토콜 사용 | 사용 가능 |
|---|---|
| SMB |
|
| NFS |
|
요청
다음과 같이 Put Range 요청을 생성할 수 있습니다. HTTPS를 사용하는 것이 좋습니다.
| 메서드 | 요청 URI | HTTP 버전 |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
다음과 같이 요청 URI에 표시된 경로 구성 요소를 사용자 경로 구성 요소로 바꿉니다.
| 경로 구성 요소 | Description |
|---|---|
myaccount |
사용자 스토리지 계정의 이름입니다. |
myshare |
파일 공유 이름입니다. |
mydirectorypath |
선택 사항입니다. 부모 디렉터리 경로입니다. |
myfile |
파일 이름입니다. |
경로 명명 제한에 대한 자세한 내용은 이름 및 참조 공유, 디렉터리, 파일 및 메타데이터를 참조하세요.
URI 매개 변수
요청 URI에 다음과 같은 추가 매개 변수를 지정할 수 있습니다.
| 매개 변수 | Description |
|---|---|
timeout |
선택 사항입니다.
timeout 매개 변수는 초 단위로 표시됩니다. 자세한 내용은 파일 서비스 작업에 대한 시간 제한 설정을 참조하세요. |
요청 헤더
필수 및 선택적 요청 헤더는 다음 표에 설명되어 있습니다.
| 요청 헤더 | Description |
|---|---|
Authorization |
필수 사항입니다. 권한 부여 체계, 계정 이름 및 서명을 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요. |
Date 또는 x-ms-date |
필수 사항입니다. 요청에 대한 UTC(협정 세계시)를 지정합니다. 자세한 내용은 Azure Storage에 대한 요청 권한 부여를 참조하세요. |
x-ms-version |
모든 권한 있는 요청에 필요합니다. 이 요청에 사용할 작업의 버전을 지정합니다. 자세한 내용은 Azure Storage 서비스에 대한 버전 관리를 참조하세요. |
Range 또는 x-ms-range |
Range 또는 x-ms-range가 필요합니다.쓸 바이트 범위를 지정합니다. 시작 및 끝 범위를 모두 지정해야 합니다. 이 헤더는 HTTP/1.1 프로토콜 사양에 의해 정의됩니다. 업데이트 작업의 경우 범위 크기는 최대 4MiB일 수 있습니다. 지우기 작업의 경우 범위는 파일의 전체 크기 값까지 가능합니다. 파일 서비스는 및 x-ms-range 헤더에 대해 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(잘못된 요청)으로 인해 작업이 실패합니다.헤더가 Content-MD5 로 설정된 clear경우 헤더가 x-ms-write 허용되지 않습니다. 요청에 포함된 경우 파일 서비스는 상태 코드 400(잘못된 요청)을 반환합니다. |
x-ms-write: { update ¦ clear } |
필수 사항입니다. 다음 옵션 중 하나를 지정해야 합니다.
|
x-ms-lease-id: <ID> |
파일에 활성 임대가 있는 경우 필요합니다. 버전 2019-02-02 이상에 사용할 수 있습니다. |
x-ms-client-request-id |
선택 사항입니다. 로깅이 구성될 때 로그에 기록되는 1키비바이트(KiB) 문자 제한으로 클라이언트에서 생성된 불투명 값을 제공합니다. 이 헤더를 사용하여 클라이언트 쪽 활동과 서버가 수신하는 요청의 상관 관계를 지정하는 것이 좋습니다. 자세한 내용은 Azure Files 모니터링을 참조하세요. |
x-ms-file-last-write-time: { now ¦ preserve } |
선택 사항입니다. 버전 2021-06-08 이상. 다음 옵션 중 하나를 지정할 수 있습니다.
|
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에 있는 후행 점을 잘라내야 하는지 여부를 지정합니다. 자세한 내용은 공유, 디렉터리, 파일 및 메타데이터 이름 지정 및 참조를 참조하세요. |
요청 본문
업로드할 범위를 나타내는 데이터입니다.
샘플 요청: 바이트 범위 업데이트
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 프로토콜 사양을 준수합니다.
| 응답 헤더 | Description |
|---|---|
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 |
이 헤더는 요청 및 해당 응답 문제를 해결하는 데 사용할 수 있습니다. 이 헤더의 값 x-ms-client-request-id 은 요청에 있고 값에 표시되는 ASCII 문자가 1,024자 이하인 경우 헤더 값과 같습니다. 헤더가 x-ms-client-request-id 요청에 없는 경우 응답에 없습니다. |
x-ms-file-last-write-time |
버전 2021-06-08 이상. ISO 8601 형식의 파일에 대한 마지막 쓰기 시간입니다. 예: 2017-05-10T17:52:33.9551861Z. |
응답 본문
없음
샘플 응답
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 프로토콜을 사용하면 바이트 범위 잠금이 파일 영역에 대한 읽기 및 쓰기 액세스를 관리할 수 있습니다. 즉Put Range, 를 사용하여 x-ms-range작업에서 지정한 범위와 겹치는 잠금이 SMB 클라이언트에 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>
768-1024와 2048-2304의 정렬되지 않은 공간에 0이 기록되었습니다.
Put Range는 공유의 읽기 전용 복사본인 공유 스냅샷 지원되지 않습니다. 공유 스냅샷 이 작업을 수행하려는 시도가 400(InvalidQueryParameterValue)으로 실패합니다.