API 버전 관리

이 페이지는 API의 버전 번호를 변경하기 위한 자세한 구성과 배포 절차를 설명합니다. 사용하는 절차는 API의 변경사항이 하위 호환되는지 여부에 따라 달라집니다.

추가 정보 및 권장사항에 대해서는 API 수명 주기 관리를 참조하세요.

하위 호환 변경사항

기존 클라이언트 코드와 하위 호환되는 API 변경사항이 있는 경우, 새 버전을 배포하기 전에 API의 부 버전 번호를 증가시키는 것이 좋습니다. Cloud Endpoints는 한 번에 API 부 버전을 한 개씩 실행하지만, Endpoints > 서비스의 그래프와 로그에는 해당 버전 번호가 표시됩니다. 배포하기 전에 부 버전 번호를 증가시키면 그래프와 로그에 라벨이 지정된 배포 기록이 제공됩니다.

부 버전 번호를 증가시키려면 다음 단계를 따르세요.

  1. openapi.yaml에서 info.version 필드의 부 버전 번호를 증가시킵니다. 예를 들어 현재 버전이 1.1인 경우 info.version을 1.2로 설정합니다.

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.2"
host: "echo-api.endpoints.example-project-12345.cloud.goog"

  2. Google Cloud CLI를 사용하여 API 구성을 배포합니다.

    gcloud endpoints services deploy openapi.yaml

  3. 이전 단계에서 반환된 구성 ID를 사용하여 API 백엔드를 배포합니다. 자세한 내용은 API 백엔드 배포를 참조하세요.

하위 호환되지 않는 변경사항

고객의 클라이언트 코드를 손상시키는 API 변경사항이 있는 경우, API의 주 버전 번호를 증가시키는 것이 좋습니다. Endpoints는 API 주 버전을 동시에 여러 개 실행할 수 있습니다. 두 버전의 API를 모두 제공하면 고객이 사용할 버전을 선택하고 새 버전으로 이전할 시기를 제어할 수 있습니다.

API의 기존 버전과 새 버전을 동시에 실행하려면 다음 단계를 따르세요.

  1. 제공해야 하는 버전마다 별도의 OpenAPI 구성 파일을 만듭니다. 이 절차에서는 예시 목적으로 openapi-v1.yaml 및 openapi-v2.yaml이라는 파일 이름을 사용합니다.

  2. openapi-v1.yaml의 내용을 openapi-v2.yaml로 복사합니다.

  3. openapi-v1.yaml에서 다음을 구성합니다.

    • info.version 필드를 기존 버전 번호로 설정합니다.
    • basePath 필드는 그대로 둡니다.

    예를 들면 다음과 같습니다.

    info:
  description: "A simple Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "1.1"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v1"

  4. openapi-v2.yaml에서 다음을 구성합니다.

    • 하위 호환이 불가능한 변경사항을 적용합니다.
    • info.version 필드를 새 버전 번호로 설정합니다.
    • 새로운 주 버전 번호를 포함하도록 basePath 필드를 설정합니다.
    • x-google-endpoints 섹션을 삭제합니다. 이 섹션은 DNS IP 주소 또는 allowCors 플래그를 지정하려는 경우에 필요합니다. 두 개의 yaml 구성 파일로 두 버전의 API를 배포할 때 하나의 파일만 x-google-endpoints를 가질 수 있지만 구성은 두 버전에 모두 적용됩니다.

    예를 들면 다음과 같습니다.

    info:
  description: "A simple Google Cloud Endpoints API example."
  title: "Endpoints Example"
  version: "2.0"
host: "echo-api.endpoints.example-project-12345.cloud.goog"
basePath: "/v2"

  5. Google Cloud CLI를 사용하여 두 API 구성 파일을 배포합니다.

    gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml

  6. 이전 단계에서 반환된 구성 ID를 사용하여 두 버전의 API를 모두 제공하는 단일 백엔드를 배포합니다. 자세한 내용은 API 백엔드 배포를 참조하세요.

다음 단계