Azure Storage 버전 관리

  • 아티클

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

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

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

  • 없음

요청에서 서비스 버전 지정

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

  • 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 형식으로 지정해야 합니다. 예를 들면 다음과 같습니다.

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를 사용하여 요청할 때 권한 부여에 사용됩니다. , , , sr, sp, sig, tnepkstsespksrk및 와 erk 같은 si권한 부여 매개 변수는 모두 지정된 버전을 사용하여 해석됩니다.

, , , rsce및 와 같은 rsccREST 프로토콜 매개 변수는 매개 변수 헤더에 api-version 제공된 버전을 사용하여 적용됩니다.rsctrsclrscd 헤더를 api-version 지정하지 않으면 에 제공된 SignedVersion 서비스 버전이 사용됩니다.

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

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

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

예 1

다음 샘플 요청은 매개 변수 없이 를 사용하여 sv=2015-04-05목록 Blob을 api-version 호출합니다.

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

다음 샘플 요청은 매개 변수를 사용하여 및 를 sv=2015-04-05 사용하여 목록 Blob을 api-version 호출합니다.

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

추가 정보