Compute API 마이크로버전 편집하기

==개요==
[[분류: nova]]
;Microversions
;마이크로버전
https://docs.openstack.org/api-guide/compute/microversions.html
----
API v2.1은 API에 대한 작고 문서화된 변경사항인 마이크로버전을 지원합니다. 사용자는 마이크로버전을 통해 자신의 클라우드에서 지원되는 최신 API 마이크로버전을 확인할 수 있습니다. 최신 마이크로버전을 지원하도록 클라우드를 업그레이드하더라도, 이전 마이크로버전을 사용하는 사용자들의 호환성을 유지하기 위해 모든 이전 마이크로버전도 계속 지원됩니다. 사용자는 마이크로버전을 통해 새로운 기능을 쉽게 발견할 수 있으며, 이를 통해 현재 클라우드의 모든 장점과 개선점을 누릴 수 있습니다.

마이크로버전을 통해 해결할 수 있는 여러 사례가 있습니다:

* '''새 클라우드와 구버전 클라이언트'''
:구버전 클라이언트를 사용하여 새로운 클라우드와 통신하기 전에, 구버전 클라이언트는 최소 마이크로버전을 확인하여 클라우드가 구버전 API와 호환되는지 검증할 수 있습니다. 이를 통해 하위 호환되지 않는 API 변경으로 인해 구버전 클라이언트가 중단되는 것을 방지할 수 있습니다.
:현재 마이크로버전의 최소 버전은 2.1이며, 이는 레거시 v2 API와 호환되는 마이크로버전입니다. 즉, 레거시 v2 API 사용자는 클라우드가 새로운 버전으로 업그레이드되더라도 구버전 클라이언트 소프트웨어가 중단될 걱정을 할 필요가 없습니다. 또한 클라우드 운영자는 클라우드를 새로운 버전으로 업그레이드하더라도 이러한 변경을 예상하지 못하는 구버전 클라이언트를 사용하는 사용자가 중단되는 것을 걱정할 필요가 없습니다.

* '''클라우드 간 사용가능한 기능 발견'''
새로운 기능은 마이크로버전을 통해 발견할 수 있습니다. 사용자 클라이언트는 먼저 마이크로버전을 확인하고, 클라우드가 지원하는 경우에만 새로운 기능을 활성화합니다. 이를 통해 사용자 클라이언트는 서로 다른 마이크로버전을 배포한 클라우드와 동시에 작업할 수 있습니다.

==버전 발견==
버전 API는 최소 및 최대 마이크로버전을 반환합니다. 이러한 값은 클라이언트가 API에서 지원하는 마이크로버전을 확인하는 데 사용됩니다.

모든 엔드포인트에 대한 버전 정보를 요청하려면 <code>/</code> 경로로 요청을 보내면 됩니다. 응답은 다음과 같이 표시됩니다:

<syntaxhighlight lang='json'>
{
  "versions": [
      {
          "id": "v2.0",
          "links": [
              {
                  "href": "http://openstack.example.com/v2/",
                  "rel": "self"
              }
          ],
          "status": "SUPPORTED",
          "version": "",
          "min_version": "",
          "updated": "2011-01-21T11:33:21Z"
      },
      {
          "id": "v2.1",
          "links": [
              {
                  "href": "http://openstack.example.com/v2.1/",
                  "rel": "self"
              }
          ],
          "status": "CURRENT",
          "version": "2.14",
          "min_version": "2.1",
          "updated": "2013-07-23T11:33:21Z"
      }
  ]
}
</syntaxhighlight>

<code>version</code>은 최대 마이크로버전을 나타내고, <code>min_version</code>은 최소 마이크로버전을 나타냅니다. 값이 빈 문자열인 경우, 해당 엔드포인트는 마이크로버전을 지원하지 않으며, 이는 레거시 v2 API 엔드포인트를 의미합니다. 예를 들어, 위의 샘플에서 <code>http://openstack.example.com/v2/</code> 엔드포인트가 해당됩니다. <code>http://openstack.example.com/v2.1/</code> 엔드포인트는 마이크로버전을 지원하며, 최대 마이크로버전은 <code>2.14</code>이고 최소 마이크로버전은 <code>2.1</code>입니다. 클라이언트는 해당 엔드포인트에 접근하기 위해 최소 마이크로버전과 최대 마이크로버전 사이(포함)의 마이크로버전을 지정해야 합니다.

기본 버전 URL (예: <code>http://openstack.example.com/v2.1/</code>)에서 GET 요청을 수행하여 특정 엔드포인트 버전 정보를 얻을 수도 있습니다. 버전 API에 대한 자세한 정보는 "[[Compute API 버전|버전]]"을 참조하십시오.

==클라이언트 상호작용==
클라이언트는 다음 HTTP 헤더를 사용하여 원하는 API의 마이크로버전을 지정합니다:

<syntaxhighlight lang='text'>
X-OpenStack-Nova-API-Version: 2.4
</syntaxhighlight>

마이크로버전 <code>2.27</code>부터는 마이크로버전을 지정하기 위해 다음 헤더를 사용하는 것도 올바릅니다:

<syntaxhighlight lang='text'>
OpenStack-API-Version: compute 2.27
</syntaxhighlight>

{{NOTE}}
이 새로운 형식에 대한 자세한 내용은 [[OpenStack 마이크로버전 사양|마이크로버전 사양]]을 참조하십시오.
{{/NOTE}}

이것은 개념적으로 "Accept" 헤더처럼 작동합니다. 의미론적으로 이는 다음을 의미합니다:
* <code>X-OpenStack-Nova-API-Version</code> 또는 <code>OpenStack-API-Version</code>(<code>compute</code> 지정) 중 어느 것도 제공되지 않으면 지원되는 최소 마이크로버전이 지정된 것처럼 작동합니다.
* 두 헤더가 모두 제공되면 <code>OpenStack-API-Version</code>이 우선됩니다.
* <code>X-OpenStack-Nova-API-Version</code> 또는 <code>OpenStack-API-Version</code>이 제공되면 해당 마이크로버전의 API로 응답합니다. 지원되는 마이크로버전 범위를 벗어나면 406 Not Acceptable을 반환합니다.
* <code>X-OpenStack-Nova-API-Version</code> 또는 <code>OpenStack-API-Version</code> 값이 latest(특수 키워드)인 경우 최대값이 지정된 것처럼 작동합니다.

{{WARNING}}
<code>latest</code> 값은 주로 통합 테스트를 위해 사용되며 마이크로버전이 semver를 따르지 않기 때문에 클라이언트 코드에서 의존하는 것은 위험할 수 있습니다. 클라이언트는 항상 특정 마이크로버전을 요구해야 하지만, 자신이 이해할 수 있는 마이크로버전 범위로 제한해야 합니다.
{{/WARNING}}

이는 마이크로버전에 대한 지식이 없는 오래된 클라이언트도 마이크로버전 지원이 있는 OpenStack 설치와 함께 작동할 수 있음을 의미합니다.

마이크로버전 <code>2.27</code> 이전에는 응답에 항상 두 개의 추가 헤더가 반환됩니다:

<syntaxhighlight lang='text'>
X-OpenStack-Nova-API-Version: microversion_number
Vary: X-OpenStack-Nova-API-Version
</syntaxhighlight>

첫 번째 헤더는 실행된 API의 마이크로버전 번호를 지정합니다.

<code>Vary</code> 헤더는 응답이 본문과 쿼리 매개변수뿐만 아니라 마이크로버전에도 의존함을 캐싱 프록시에게 힌트로 사용됩니다. 자세한 내용은 [[RFC 2616]] 섹션 14.44를 참조하십시오.

마이크로버전 <code>2.27</code>부터는 응답에 두 개의 추가 헤더가 추가됩니다:

<syntaxhighlight lang='text'>
OpenStack-API-Version: compute microversion_number
Vary: OpenStack-API-Version
</syntaxhighlight>

==같이 보기==
* [[Compute API 버전]]