Azure Storage는 여러 버전을 지원합니다. 스토리지 서비스에 대해 요청을 수행하려면 요청이 익명이 아닌 한 해당 작업에 사용할 버전을 지정해야 합니다.
2025년 7월 14일 현재 완전히 배포된 최신 버전의 Azure Storage 서비스는 입니다 2025-05-05.
2025-07-05 또한 다음 표에 표시된 것처럼 광범위하게 배포됩니다. 모든 버전은 GA 품질입니다.
테이블에 지역에서 x-ms-version 사용하도록 설정된 것으로 표시되면 이전의 x-ms-versions 모든 항목도 사용하도록 설정됩니다. 스토리지 계정의 지역에 완전히 배포되지 않은 서비스 버전을 사용하려고 하면 x-ms-version 불일치 오류가 발생할 수 있습니다.
x-ms-version |
Region Availability | SDK Support |
|---|---|---|
2025-07-05 |
asiaeast asiasoutheast australiac australiac2 australiaeast australiasoutheast austriae belgiumc brazilse brazilsouth canadacentral canadaeast chilec denmarke europenorth europewest francec frances germanyn germanywc indiacentral indiasouth indiawest indonesiac israelc israelnw italyn japaneast japanwest jioinc jioinw koreacentral koreasouth malaysias malaysiaw mexicoc newzealandn norwaye norwayw polandc qatarc southafrican southafricaw spainc swedenc swedens switzerlandn switzerlandw taiwann taiwannw uaec uaen uksouth ukwest uscentral uscentraleuap useast useast2 useast2euap useast3 usnorth ussouth ussouth2 ussoutheast ussoutheast3 ussoutheast5 ussouthwest uswest uswest2 uswest3 uswestcentral |
GA |
2025-11-05 |
asiaeast australiac australiac2 australiaeast australiasoutheast austriae belgiumc brazilse brazilsouth canadacentral canadaeast chilec denmarke europenorth francec frances germanywc indiacentral indiasouth indiawest indonesiac israelc israelnw italyn japaneast japanwest jioinc jioinw koreacentral koreasouth malaysias malaysiaw mexicoc newzealandn norwaye norwayw polandc qatarc southafrican southafricaw spainc swedenc swedens switzerlandn switzerlandw taiwann taiwannw uaec uaen ukwest useast3 usnorth ussouth2 ussoutheast ussoutheast3 ussoutheast5 ussouthwest uswest uswest2 uswest3 uswestcentral |
Beta |
Azure Storage 데이터 평면 SDK에서 사용하는 기본값은 x-ms-version 다음 표의 변경 로그에서 찾을 수 있습니다.
데이터 평면 스토리지 SDK는 해당 릴리스의 기본값 x-ms-version 이 모든 지역에서 전체 롤아웃될 때까지 다른 공식 패키지 피드에 GA 릴리스를 수행하지 않습니다. 따라서 공식 패키지 관리자의 최신 GA SDK 릴리스는 모든 지역에서 안전하게 사용할 수 있습니다.
Azure Storage 서비스의 최신 버전은 2025-11-05이며 가능한 경우 사용하는 것이 좋습니다. 지원되는 다른 모든 버전 목록 및 각 버전 사용에 대한 자세한 내용은 이전 Azure Storage 서비스 버전 참조하세요.
2025-11-05 서비스 버전에는 다음과 같은 기능이 포함되어 있습니다.
- 다음 API는 이제 및
x-ms-copy-source-status-code를 반환합니다x-ms-copy-source-error-code. 자세한 내용은 상태 및 오류 코드를 참조하십시오.
요청에서 서비스 버전 지정
요청에 사용할 스토리지 서비스 버전을 지정하는 방법은 해당 요청의 권한 부여 방식과 관련이 있습니다. 다음 섹션에서는 권한 부여 옵션 및 서비스 버전을 각각에 대해 지정하는 방법에 대해 설명합니다.
Microsoft Entra OAuth 2.0 토큰을 사용하는요청: Microsoft Entra ID를 사용하여 요청에 권한을 부여하려면 2017-11-09 이상의 서비스 버전으로 요청에
x-ms-version헤더를 전달합니다. 자세한 내용은 Microsoft Entra ID 권한 부여에서 OAuth 토큰 스토리지 호출 작업을 참조하세요.공유 키 또는 공유 키 라이트 사용하는요청: 공유 키 또는 공유 키 라이트를 사용하여 요청에 권한을 부여하려면 요청에
x-ms-version헤더를 전달합니다. Azure Blob Storage를 사용하는 경우 Blob Service 속성 설정을 호출하여 모든 요청에 대한 기본 버전을 지정할 수 있습니다.SAS(공유 액세스 서명) 사용하는요청: 공유 액세스 서명에 두 가지 버전 관리 옵션을 지정할 수 있습니다. 선택적
api-version헤더는 API 작업을 실행하는 데 사용할 서비스 버전을 나타냅니다. 필요한SignedVersion (sv)매개 변수는 SAS로 이루어진 요청에 권한을 부여하는 데 사용할 서비스 버전을 지정합니다.api-version헤더를 지정하지 않으면SignedVersion (sv)매개 변수 값은 API 작업을 실행하는 데 사용할 버전도 나타냅니다.익명 액세스를 사용하는 요청: Blob Storage에 대해 익명 액세스를 사용하는 경우 버전이 전달되지 않습니다. 요청에 사용할 버전을 결정하는 추론은 다음 섹션에서 설명합니다.
Microsoft Entra ID, 공유 키 또는 공유 키 라이트를 사용하여 요청 권한 부여
Microsoft Entra ID, 공유 키 또는 공유 키 라이트를 사용하여 요청에 권한을 부여하려면 요청에 x-ms-version 헤더를 지정합니다.
x-ms-version 요청 헤더 값은 YYYY-MM-DD 형식으로 지정해야 합니다. For example:
Request Headers:
x-ms-version: 2020-04-08
다음 규칙은 요청을 처리하는 데 사용할 버전을 결정하기 위해 이러한 요청을 평가하는 방법을 설명합니다.
요청에 유효한
x-ms-version헤더가 있는 경우 스토리지 서비스는 지정된 버전을 사용합니다. 공유 액세스 서명을 사용하지 않는 Azure Table Storage 및 Azure Queue Storage에 대한 모든 요청은x-ms-version헤더를 지정해야 합니다. 공유 액세스 서명을 사용하지 않는 Blob Storage에 대한 모든 요청은 다음 단락에 설명된 대로 기본 버전이 설정되지 않은 한 헤더를 지정해야x-ms-version합니다.Blob Storage에 대한 요청에 헤더가
x-ms-version포함되지 않았지만 계정 소유자가 Blob Service Properties 설정 작업을 사용하여 기본 버전을 설정하는 경우 지정된 기본 버전이 요청의 버전으로 사용됩니다.
공유 액세스 서명을 사용하여 요청 권한 부여
버전 2014-02-14 이상을 사용하여 생성된 SAS(공유 액세스 서명)는 두 가지 버전 관리 옵션을 지원합니다.
api-version쿼리 매개 변수는 SAS를 사용하여 만들어진 요청을 처리하는 데 사용할 REST 프로토콜 버전을 정의합니다.SignedVersion (sv)쿼리 매개 변수는 권한 부여에 사용할 SAS 버전을 정의합니다.
SignedVersion 쿼리 매개 변수는 클라이언트가 SAS를 사용하여 요청할 때 권한 부여에 사용됩니다.
si, sr, sp, sig, st, se, tn, spk, srk, epk및 erk 같은 권한 부여 매개 변수는 모두 지정된 버전을 사용하여 해석됩니다.
, rscc, rscdrsce, 및 rscl 와 같은 rsctREST 프로토콜 매개 변수는 매개 변수 헤더에 api-version 제공된 버전을 사용하여 적용됩니다.
api-version 헤더를 지정하지 않으면 제공된 SignedVersion 서비스 버전이 사용됩니다.
api-version 매개 변수는 서비스 SAS만들기에 설명된 대로 권한 부여 헤더의 문자열 간 로그인에 포함되지 않습니다.
다음 표에서는 SignedVersion 매개 변수가 버전 2014-02-14 이상으로 설정된 경우 서비스에서 권한 부여 및 REST 프로토콜 호출에 사용하는 버전 관리 체계에 대해 설명합니다.
| Value of api-version parameter | 권한 부여에 사용되는 버전 | 프로토콜 동작에 사용되는 버전 |
|---|---|---|
| Not specified |
sv 매개 변수에 지정된 버전 |
sv 매개 변수에 지정된 버전 |
XXXX-XX-XX 형식의 유효한 스토리지 서비스 버전 |
sv 매개 변수에 지정된 버전 |
유효한 스토리지 서비스 버전 XXXX-XX-XX |
Example 1
The following sample request calls List Blobs with sv=2015-04-05, and without the api-version parameter.
https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d
이 경우 서비스는 버전 2015-04-05를 사용하여 요청을 인증하고 권한을 부여하며 버전 2015-04-05를 사용하여 작업을 실행합니다.
Example 2
The following sample request calls List Blobs with sv=2015-04-05 and with the api-version parameter.
https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d&api-version=2012-02-12
여기서 서비스는 버전 2015-04-05를 사용하여 요청에 권한을 부여하고 버전 2012-02-12를 사용하여 작업을 실행합니다.
Note
.NET Storage 클라이언트 라이브러리는 항상 REST 프로토콜 버전(매개 변수에서 api-version )을 기본 버전으로 설정합니다.
익명 액세스를 통한 요청
익명 액세스를 통해 만들어진 요청은 수행한 스토리지 계정 유형에 따라 다르게 처리됩니다.
범용 스토리지 계정
범용 스토리지 계정에 대한 익명 요청이 헤더를 지정하지 x-ms-version 않고 Blob 서비스 속성 설정을 사용하여 서비스의 기본 버전을 설정하지 않은 경우 서비스는 가능한 가장 빠른 버전을 사용하여 요청을 처리합니다. 버전 2009-09-19 이상을 사용하여 컨테이너 ACL 설정 작업을 사용하여 컨테이너를 공개한 경우 요청은 버전 2009-09-19를 사용하여 처리됩니다.
Blob Storage 계정의 경우
Blob Storage 계정에 대한 익명 요청이 헤더를 지정하지 x-ms-version 않고 Blob Service 속성 설정을 사용하여 서비스의 기본 버전을 설정하지 않은 경우 서비스는 가능한 가장 빠른 버전을 사용하여 요청을 처리합니다. Blob Storage 계정의 경우 가능한 가장 빠른 버전은 2014-02-14입니다.
Known issues
이 섹션에서는 Azure Storage REST API에 대해 알려진 문제를 자세히 설명합니다.
InvalidHeaderValue 오류 메시지
드문 시나리오에서 직접 REST API를 호출하는 애플리케이션은 InvalidHeaderValue 오류 메시지를 받을 수 있습니다. 이 오류는 다음 샘플과 유사합니다.
HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>
이전 REST API 버전을 사용하여 문제를 해결하는 것이 좋습니다. 문제가 지속되거나 권장 사항이 실현 가능하지 않은 경우 지원 티켓을 열어 추가 옵션에 대해 논의하세요.
See also
- 스토리지 서비스 REST
- 버전 관리 모범 사례
- .NET 클라이언트 라이브러리 버전 대한 프로토콜 버전 지원