다음을 통해 공유

Azure Storage에 대한 버전 관리

  • 아티클

Azure Storage는 여러 버전을 지원합니다. 스토리지 서비스에 대해 요청을 수행하려면 요청이 익명이 아닌 한 해당 작업에 사용할 버전을 지정해야 합니다.

현재 버전의 Azure Storage 서비스는 2024-11-04이며 가능한 경우 사용하는 것이 좋습니다. 지원되는 다른 모든 버전 목록 및 각 버전 사용에 대한 자세한 내용은 이전 Azure Storage 서비스 버전참조하세요.

2024-11-04 서비스 버전에는 다음 기능이 포함되어 있습니다.

  • 파일 서비스의 모든 데이터 평면 API에 대한 토큰 기반 인증을 지원합니다. 자세한 내용은 Microsoft Entra ID권한 부여를 참조하세요.
  • 프리미엄 파일 공유 계정에 대한 유료 버스팅 지원. 이 기능은 공유 만들기 사용하도록 설정하고 공유 속성 API를 설정할 수 있습니다.
  • 파일 서비스에서 파일 권한을 가져오고 설정할 때 이진 형식을 지원합니다. 자세한 내용은 권한 만들기 및 권한 가져오기 참조하세요.

요청에서 서비스 버전 지정

요청에 사용할 스토리지 서비스 버전을 지정하는 방법은 해당 요청의 권한 부여 방식과 관련이 있습니다. 다음 섹션에서는 권한 부여 옵션 및 서비스 버전을 각각에 대해 지정하는 방법에 대해 설명합니다.

  • Microsoft EntraOAuth 2.0 토큰을 사용하는 요청: Microsoft Entra ID를 사용하여 요청에 권한을 부여하려면 2017-11-09 이상의 서비스 버전으로 요청에 헤더를 전달합니다. 자세한 내용은 Microsoft Entra ID권한 부여에서 OAuth 토큰 스토리지 호출 작업을 참조하세요.

  • 공유 키 또는 공유 키 라이트사용하는 요청: 공유 키 또는 공유 키 라이트를 사용하여 요청에 권한을 부여하려면 요청에 헤더를 전달합니다. 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 형식으로 지정해야 합니다. 예를 들어:

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 속성 설정 작업을 사용하여 기본 버전을 설정한 경우 지정된 기본 버전이 요청의 버전으로 사용됩니다.

공유 액세스 서명을 사용하여 요청 권한 부여

버전 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, rscd, rsce, rscl및 rsct 같은 REST 프로토콜 매개 변수는 api-version 매개 변수 헤더에 제공된 버전을 사용하여 적용됩니다. api-version 헤더를 지정하지 않으면 SignedVersion 제공된 서비스 버전이 사용됩니다.

api-version 매개 변수는 서비스 SAS만들기에 설명된 대로 권한 부여 헤더의 문자열 간 로그인에 포함되지 않습니다.

다음 표에서는 SignedVersion 매개 변수가 버전 2014-02-14 이상으로 설정된 경우 서비스에서 권한 부여 및 REST 프로토콜 호출에 사용하는 버전 관리 체계에 대해 설명합니다.

api-version 매개 변수의 값 권한 부여에 사용되는 버전 프로토콜 동작에 사용되는 버전
지정되지 않음 sv 매개 변수에 지정된 버전 sv 매개 변수에 지정된 버전
XXXX-XX-XX 형식의 유효한 스토리지 서비스 버전 sv 매개 변수에 지정된 버전 유효한 스토리지 서비스 버전 XXXX-XX-XX

예제 1

다음 샘플 요청은 매개 변수 없이 Blob 나열을 호출합니다.

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를 사용하여 작업을 실행합니다.

예제 2

다음 샘플 요청은 매개 변수를 사용하여 Blob 호출합니다.

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를 사용하여 작업을 실행합니다.

메모

.NET Storage 클라이언트 라이브러리는 항상 REST 프로토콜 버전(api-version 매개 변수)을 기반으로 하는 버전으로 설정합니다.

익명 액세스를 통한 요청

익명 액세스를 통해 만들어진 요청은 수행한 스토리지 계정 유형에 따라 다르게 처리됩니다.

범용 스토리지 계정의 경우

범용 스토리지 계정에 대한 익명 요청이 x-ms-version 헤더를 지정하지 않고 Blob Service 속성 설정사용하여 서비스의 기본 버전을 설정하지 않은 경우 서비스는 가능한 가장 빠른 버전을 사용하여 요청을 처리합니다. 그러나 버전 2009-09-19 이상을 사용하여 수행된 컨테이너 ACL 설정 작업으로 컨테이너를 공개한 경우 요청은 버전 2009-09-19를 사용하여 처리됩니다.

Blob Storage 계정의 경우

Blob Storage 계정에 대한 익명 요청이 x-ms-version 헤더를 지정하지 않고 Blob Service 속성 설정사용하여 서비스의 기본 버전을 설정하지 않은 경우 서비스는 가능한 가장 빠른 버전을 사용하여 요청을 처리합니다. Blob Storage 계정의 경우 가능한 가장 빠른 버전은 2014-02-14입니다.

알려진 문제

이 섹션에서는 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 버전을 사용하여 문제가 해결되었는지 확인하는 것이 좋습니다. 문제가 지속되거나 권장 사항이 가능하지 않은 경우 지원 티켓 열어 추가 옵션을 논의하세요.

참고 항목

  • 스토리지 서비스 REST
  • 버전 관리 모범 사례
  • .NET 클라이언트 라이브러리 버전 대한 프로토콜 버전 지원