버전 관리

이 주제에서는 Google API에서 사용하는 버전 관리 전략을 설명합니다. 일반적으로 이러한 전략은 모든 Google 관리 서비스에 적용됩니다.

API에 대한 이전 버전과 호환되지 않는(또는 '브레이킹') 변경이 필요한 경우가 있습니다. 이러한 종류의 변경사항으로 원래 기능에 대한 종속 항목이 있는 코드에 문제가 발생하거나 코드가 중단될 수 있습니다.

Google API는 브레이킹 체인지를 방지하기 위해 버전 관리 스키마를 사용합니다. 또한 Google API는 알파 및 베타 버전 구성요소와 같은 일부 안정성 수준에서만 사용할 수 있는 기능을 제공합니다.

안내

모든 Google API 인터페이스는 주 버전 번호를 제공해야 합니다. 주 버전 번호는 protobuf 패키지 끝에서 인코딩되고 REST API의 URI 경로 첫 번째 부분으로 포함됩니다. API가 필드 제거 또는 이름 변경과 같은 브레이킹 체인지를 도입한 경우 기존 사용자 코드가 갑작스럽게 중단되지 않도록 API 버전 번호를 증가해야 합니다.

API의 새 주 버전은 동일한 API의 이전 주 버전에 종속되지 않아야 합니다. API는 호출자가 API와 관련된 종속 항목과 안정성 위험을 이해한다는 가정 하에 다른 API에 종속될 수 있습니다. 이 시나리오에서 안정적인 API 버전은 다른 API의 공개 버전에만 종속되어야 합니다.

동일한 API의 여러 버전은 합당한 전환 기간 동안 단일 클라이언트 애플리케이션 내에서 동시에 작동할 수 있어야 합니다. 이 기간 동안 클라이언트는 새 버전으로 원활하게 전환할 수 있습니다. 이전 버전은 합당한 지원 중단 기간을 거친 후에 종료되어야 합니다.

알파 또는 베타 버전 안정성이 있는 출시 버전의 경우 API는 다음 전략 중 하나를 사용하여 protobuf 패키지와 URI 경로의 주 버전 번호 다음에 안정성 수준을 추가해야 합니다.

채널 기반 버전 관리(권장)
출시 기반 버전 관리
공개 상태 기반 버전 관리

채널 기반 버전 관리

공개 버전 채널은 안정성 수준이 지정된 장기 출시 버전으로, 현재 위치 업데이트를 수신합니다. 주 버전의 안정성 수준당 채널은 1개입니다. 이 전략에는 알파 버전, 베타 버전, 공개 버전 등 최대 3개의 채널이 있습니다.

알파 및 베타 채널에서는 버전에 안정성 수준이 추가되어야 하지만 공개 버전 채널에서는 안정성 수준이 추가되지 않아야 합니다. 예를 들어 v1는 공개 버전 채널에 허용될 수 있지만 v1beta 또는 v1alpha는 허용되지 않습니다. 마찬가지로 각 베타 및 알파 채널에 v1beta 또는 v1alpha가 허용될 수 있지만 v1은 허용될 수 없습니다. 이러한 각 채널은 새로운 기능을 수신하고 '현재 위치' 업데이트를 수행합니다.

베타 채널 기능은 공개 버전 채널 기능의 상위 집합이어야 하고 알파 채널 기능은 베타 채널 기능의 상위 집합이어야 합니다.

지원 중단된 API 기능

API 요소(필드, 메시지, RPC)는 더 이상 사용되어서는 안 된다는 것을 나타내도록 모든 채널에 지원 중단됨으로 표시될 수 있습니다.

// Represents a scroll. Books are preferred over scrolls.
message Scroll {
  option deprecated = true;

  // ...
}

지원 중단된 API 기능은 알파 버전에서 베타 버전으로 또는 베타 버전에서 공개 버전으로 전환되면 안 됩니다. 즉, 기능이 모든 채널에서 '사전 지원 중단'되지 않아야 합니다.

베타 채널 기능은 충분한 기간 동안(180일 권장) 지원 중단된 후에 삭제될 수 있습니다. 알파 채널에만 있는 기능의 경우 지원 중단은 선택사항이며 기능은 예고없이 삭제될 수 있습니다. 기능이 삭제되기 전에 API의 알파 채널에서 지원 중단된 경우 API는 동일한 주석을 적용해야 하며 원하는 기간을 사용할 수 있습니다.

출시 기반 버전 관리

개별 출시 버전은 기능이 공개 버전 채널에 통합되기 전에 제한된 기간 동안 사용할 수 있는 알파 또는 베타 출시 버전이며 공개 버전 채널에 통합되면 개별 출시 버전이 종료됩니다. 출시 기반 버전 관리 전략을 사용할 경우 API에는 각 안정성 수준에서 개별 출시 버전이 여러 개 있을 수 있습니다.

알파 및 베타 출시 버전에서는 버전에 증가하는 출시 버전 번호와 안정성 수준이 추가되어야 합니다. 예를 들면 v1beta1 또는 v1alpha5입니다. API는 문서(예: 주석)에 이러한 버전을 시간순으로 명시해야 합니다.

각 알파 또는 베타 출시 버전은 하위 호환성을 유지하도록 업데이트될 수 있습니다. 베타 출시 버전의 경우 출시 버전 번호를 증가하고 변경사항이 포함된 새 출시 버전을 게시하여 이전 버전과 호환되지 않는 업데이트를 수행해야 합니다. 예를 들어 현재 버전이 v1beta1이면 다음에 v1beta2가 출시됩니다.

알파 및 베타 출시 버전은 기능이 공개 버전 채널에 공개되면 종료되어야 합니다. 알파 출시 버전은 언제든지 종료될 수 있지만 베타 출시 버전은 사용자에게 합당한 전환 기간(180일 권장)을 제공해야 합니다.

공개 상태 기반 버전 관리

API 공개 상태는 Google API 인프라에서 제공하는 고급 기능입니다. 이를 통해 API 작성자는 하나의 내부 API 표면에서 여러 개의 외부 API 뷰를 노출할 수 있으며, 각 뷰는 다음과 같은 API 공개 상태 라벨과 연결됩니다.

import "google/api/visibility.proto";

message Resource {
  string name = 1;

  // Preview. Do not use this feature for production.
  string display_name = 2
    [(google.api.field_visibility).restriction = "PREVIEW"];
}

공개 상태 라벨은 API 요소에 태그를 지정하는 데 사용될 수 있는 대소문자를 구분하는 문자열입니다. 규칙에 따라 공개 상태 라벨은 항상 대문자를 사용해야 합니다. 암시적 PUBLIC 라벨은 위의 예시와 같이 명시적인 공개 라벨이 적용되지 않는 한 모든 API 요소에 적용됩니다.

각 공개 상태 라벨은 허용 목록입니다. API 작성자는 라벨과 연결된 API 기능을 사용할 수 있도록 공개 상태 라벨을 API 소비자에게 부여해야 합니다. 즉, API 공개 상태 라벨은 ACL API 버전과 같습니다.

쉼표로 구분된 문자열(예: "PREVIEW,TRUSTED_TESTER")을 사용하여 요소에 여러 공개 라벨을 적용할 수 있습니다. 여러 공개 상태 라벨을 사용하면 클라이언트는 공개 상태 라벨(논리적 OR) 중 하나만 필요합니다.

API 요청 하나에 공개 상태 라벨 하나만 사용할 수 있습니다. 기본적으로 API 소비자에게 부여된 공개 상태 라벨이 사용됩니다. 클라이언트는 다음과 같이 명시적 공개 상태 라벨이 있는 요청을 전송할 수 있습니다.

GET /v1/projects/my-project/topics HTTP/1.1
Host: pubsub.googleapis.com
Authorization: Bearer y29....
X-Goog-Visibilities: PREVIEW

API 작성자는 INTERNAL 및 PREVIEW와 같은 API 버전 관리에 API 공개 상태를 사용할 수 있습니다. 새 API 기능은 INTERNAL 라벨로 시작한 다음 PREVIEW 라벨로 이동합니다. 기능이 안정화되고 일반 안정화 버전이 되면 API 정의에서 모든 API 공개 상태 라벨이 삭제됩니다.

일반적으로 API 공개 상태는 단계적 변경사항에 대한 API 버전 관리보다 구현하기 쉽지만 정교한 API 인프라 지원에 따라 다릅니다. Google Cloud API에서 미리보기 기능에 API 공개 상태를 사용하는 경우가 많습니다.

proto3 사용

호환성