OpenAPI 3.x를 사용하도록 Cloud Endpoints 수정

이 페이지에서는 Endpoints를 구성할 때 OpenAPI 3.x 사양을 사용하는 방법을 설명합니다.

시작하기 전에

  • OpenAPI 2.0 사양으로 구성된 기존 Endpoints 인스턴스가 있는지 확인합니다.
  • gcloud CLI 설치 자세한 내용은 Google Cloud CLI 설치를 참고하세요.

OpenAPI 3.x를 사용하도록 Endpoints 구성 수정

OpenAPI 3.x를 사용하도록 기존 OpenAPI 2.0 Endpoints 구성을 수정하려면 다음 단계를 완료하세요.

배포 기록 보기

배포 기록을 보려면 다음 안내를 따르세요.

  1. Google Cloud 콘솔에서 엔드포인트 > 서비스 페이지로 이동합니다.

    Endpoints 서비스 페이지로 이동

  2. 프로젝트 목록에서 프로젝트를 선택합니다.

  3. API가 2개 이상이면 목록에서 API를 선택합니다.

  4. 서비스 구성 배포 목록을 보려면 배포 기록 탭을 클릭합니다. 목록에는 다음 항목이 표시됩니다.

    • 구성 ID
    • 서비스 구성이 배포된 날짜
    • 서비스 구성 배포자

서비스 구성 보기

배포 기록 탭의 목록에서 가장 최근 배포를 선택합니다. 배포된 서비스 구성 파일의 내용이 표시됩니다.

OpenAPI 문서를 OpenAPI 3.x로 변환

OpenAPI 2.0 문서를 OpenAPI 3.x로 변환합니다. 이 변환을 OpenAPI 3.x로 지원하는 도구를 사용할 수 있습니다. 예를 들어 Swagger Editor는 변환 유틸리티를 제공합니다.

OpenAPI 3.x로 초기 변환한 후 OpenAPI 3.x에 맞게 문서를 수동으로 추가 변경하여 Endpoints 확장 프로그램 및 기능과의 호환성을 보장합니다.

다음 표에는 필요한 변경사항이 설명되어 있습니다.

기능 OpenAPI 2.0 OpenAPI 3.x 변경사항 설명
API 키 securityDefinitions securitySchemes API 키는 기본 OpenAPI API 키 지원을 사용합니다. 변환 도구는 일반적으로 이 작업을 자동으로 처리합니다. 수동으로 변경할 필요가 없습니다.
JWT 인증 x-google-audiences 등 x-google-auth OpenAPI 2.0 확장 프로그램에서는 securityDefinition 인스턴스에서 개별 확장 프로그램을 사용하여 OAuth 구성을 정의합니다. 변환 도구는 보안 스키마 인스턴스를 #/components/securitySchemes로 변환하고 확장 프로그램을 그대로 둡니다. 이러한 확장 프로그램을 x-google-auth의 하위 요소가 되도록 수동으로 수정하고 x-google- 접두사를 삭제합니다. 값은 동일하게 유지됩니다.
할당량 x-google-management, x-google-quota x-google-api-management, x-google-quota OpenAPI 2.0 확장 프로그램에서는 x-google-management에서 측정항목과 할당량을 정의하고 x-google-quota로 연결합니다. 변환 도구는 이러한 확장 프로그램을 그대로 둡니다. 측정항목 및 할당량 구성을 x-google-management에서 x-google-api-management로 수동으로 이동합니다. YAML 키를 사용하도록 구성을 변경하고 valueType, metricKind, unit를 삭제합니다. x-google-quota 인스턴스에서 metricCosts를 삭제합니다.
백엔드 x-google-backend x-google-api-management, x-google-backend OpenAPI 2.0 확장 프로그램에서 x-google-backend에 백엔드를 정의하면 정의된 위치에 구성이 적용됩니다. OpenAPI 3.x 확장 프로그램에서는 x-google-api-management에서 백엔드를 정의한 다음 x-google-backend로 적용합니다. 변환 도구는 이 확장 프로그램을 그대로 둡니다. 구성을 x-google-api-management로 수동으로 이동합니다. x-google-backend 인스턴스를 수정하여 해당 구성을 참조합니다.
엔드포인트 x-google-endpoints x-google-endpoint, servers OpenAPI 2.0 확장 프로그램에서 x-google-endpoints에 엔드포인트 구성을 정의합니다. OpenAPI 3.x 확장 프로그램에서는 x-google-endpoint를 사용하지만 루트가 아닌 servers의 확장 프로그램입니다. 변환 도구는 이 확장 프로그램을 그대로 둡니다. 이를 servers로 수동으로 이동하고 name 필드를 삭제합니다. 예를 들면 다음과 같습니다. 
# OpenAPI 2.0
x-google-endpoints:
- name: "my-api.apigateway.my-project.cloud.goog"
  allowCors: True
# OpenAPI 3.x
servers:
- url: https://my-api.apigateway.my-project.cloud.goog/
  x-google-endpoint:
    allowCors: True
API 이름 x-google-api-name x-google-api-management OpenAPI 2.0 확장 프로그램에서는 x-google-api-name에 API 이름을 정의합니다. OpenAPI 3.x 확장 프로그램에서는 x-google-api-management의 apiName 필드를 사용합니다. 이 구성을 x-google-api-management로 수동으로 이동합니다.
모든 트래픽 허용 x-google-allow 지원되지 않음 OpenAPI 문서에서 이를 삭제합니다. Endpoints는 OpenAPI 3.x에서 이를 지원하지 않습니다.

서비스 구성 다시 배포

OpenAPI 문서에서 뭔가를 변경할 때마다 Endpoints가 가장 최신 버전의 API 서비스 구성을 보유하도록 OpenAPI 문서를 다시 배포해야 합니다. rollout 옵션을 managed로 설정하고 ESP를 배포한 경우 ESP를 다시 배포하거나 시작할 필요가 없습니다. 이 옵션은 배포된 최신 서비스 구성을 사용하도록 ESP를 구성합니다. 이 옵션을 지정하면 새 서비스 구성을 배포하고 최대 5분 후 ESP가 변경사항을 감지하고 자동으로 사용하기 시작합니다. ESP에 사용할 특정 구성 ID 대신 이 옵션을 지정하는 것이 좋습니다.

OpenAPI 문서를 배포하려면 다음 안내를 따르세요.

  1. OpenAPI 문서가 있는 위치로 디렉터리를 변경합니다.

  2. 잘못된 프로젝트에 서비스가 만들어지지 않도록 다음 명령어로 반환되는 프로젝트 ID의 유효성을 검사합니다.

    gcloud config list project

    기본 프로젝트를 변경해야 하는 경우 다음 명령어를 실행하고 YOUR_PROJECT_ID를 서비스를 만들 Google Cloud 프로젝트 ID로 바꿉니다.

    gcloud config set project <var>YOUR_PROJECT_ID</var>

  3. 다음 명령어를 실행하고 YOUR_OPENAPI_DOCUMENT를 API를 설명하는 OpenAPI 문서의 이름으로 바꿉니다.

    gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>

이전 명령어를 처음으로 실행하면 Service Management가 OpenAPI 문서의 host 필드에 지정된 텍스트와 일치하는 이름으로 기본 프로젝트에 새로운 Endpoints 서비스를 만들고 서비스 구성을 업로드합니다.

서비스 생성 및 구성 시 Service Management는 터미널에 정보를 출력합니다. 성공적으로 완료되면 서비스 구성 ID와 서비스 이름이 표시된 다음과 같은 줄이 표시됩니다.

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

앞의 예시에서 2017-02-13r0은 서비스 구성 ID이고 echo-api.endpoints.example-project-12345.cloud.goog는 서비스 이름입니다.

배포가 성공적으로 완료되면 Google Cloud 콘솔의 Endpoints > 서비스 페이지에서 API를 볼 수 있습니다.

오류 메시지가 나타나면 Endpoints 구성 배포 문제해결을 참조하세요.

다음 단계