Endpoints 구성 배포

OpenAPI 문서에서 Cloud Endpoints를 구성한 후에는 API 관리에 필요한 정보가 Cloud Endpoints에 포함되도록 이를 배포합니다. Endpoints 구성을 배포하려면 gcloud endpoints services deploy 명령어를 사용합니다. 이 명령어는 Endpoints와 기타 서비스에서 API 및 서비스를 생성하고 관리하기 위해 사용되는 Google의 기반 서비스 플랫폼인 서비스 인프라를 사용합니다. 이 페이지에서는 Endpoints에 OpenAPI 문서를 배포하는 방법을 설명합니다.

기본 요건

이 페이지에서는 먼저 사용자가 다음 작업을 완료했다고 가정합니다.

배포용 Google Cloud CLI 준비

gcloud 명령줄 도구를 사용해 구성을 배포할 수 있습니다. 명령어에 대한 자세한 내용은 gcloud 참조를 참조하세요.

배포를 준비하려면 다음 안내를 따르세요.

  1. gcloud CLI를 설치하고 초기화합니다.
  2. gcloud CLI를 업데이트합니다. 
    gcloud components update
  3. gcloud CLI가 데이터와 서비스에 액세스할 수 있는 권한이 있는지 확인합니다. 
    gcloud auth login

    새 브라우저 탭이 열리고 계정을 선택하라는 메시지가 나타납니다.

  4. 기본 프로젝트를 설정합니다. [YOUR-PROJECT-ID]를 GCP 프로젝트 ID로 바꿉니다. 
    gcloud config set project [YOUR-PROJECT-ID]
  5. API 백엔드를 Kubernetes 또는 Kubernetes Engine에 배포하려면 다음 명령어를 실행하여 애플리케이션 기본 사용자 인증 정보로 사용할 새로운 사용자 인증 정보를 가져옵니다. 사용자 인증 정보는 kubectl를 승인하는 데 필요합니다. 
    gcloud auth application-default login
    새 브라우저 탭이 열리고 계정을 선택하라는 메시지가 나타납니다.

openapi.json 구문 확인

OpenAPI 문서 파일은 YAML 형식 또는 JSON 형식일 수 있습니다. JSON 형식인 경우 파일을 배포하기 전에 구문을 확인하는 것이 좋습니다. openapi.json이 올바른 형식의 JSON 파일인지 확인하려면 vim과 같은 JSON 유효성 검사 텍스트 편집기에서 해당 파일을 열거나 온라인 JSON 린터 서비스 또는 Python을 사용합니다. 예를 들면 다음과 같습니다.

python -m json.tool openapi.json

읽기 쉽도록 JSON 파일을 예쁘게 인쇄합니다.

python -m json.tool input.json > output.json

input.json을 openapi.json 파일의 경로로 바꿉니다. output.json은 예쁘게 인쇄된 JSON 파일입니다.

OpenAPI 문서 유효성 검사

현재 모든 OpenAPI 구문이 Cloud Endpoints에서 지원되지는 않습니다. 배포하기 전에 OpenAPI 문서의 유효성을 검사할 수 있습니다.

OpenAPI 문서의 유효성을 검사하려면 다음 안내를 따르세요.

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

  2. 서비스를 만들 Google Cloud 프로젝트를 확인합니다. 커스텀 도메인 이름(예: myapi.example.com)을 사용하는 경우 잘못된 프로젝트에 서비스가 만들어지지 않도록 다음 명령어로 반환되는 프로젝트 ID의 유효성을 검사합니다.

    gcloud config list project

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

    gcloud config set project [YOUR_PROJECT_ID]

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

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT] --validate-only

그러면 gcloud 명령어는 Service Management API를 호출하여 OpenAPI 문서의 host 필드에 지정된 이름으로 관리형 서비스를 만듭니다. --validate-only 플래그를 지정해도 서비스가 만들어지지만 구성은 배포되지 않습니다. 서비스를 만들지 않고 OpenAPI 문서의 유효성을 검사할 수 있는 방법은 없습니다. 서비스를 삭제할 수 있지만 Service Management에서는 약 30일 동안 같은 이름의 서비스를 만들 수 없습니다.

OpenAPI 문서 배포

API를 배포할 준비가 되면 Service Management를 사용하여 API 구성을 업로드하고 관리형 서비스를 만들거나 업데이트하는 Google Cloud CLI를 실행합니다.

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

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

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

    gcloud config list project

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

    gcloud config set project [YOUR_PROJECT_ID]

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

    gcloud endpoints services deploy [YOUR_OPENAPI_DOCUMENT]

이전 명령어를 처음으로 실행하면 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 Console의 Endpoints > 서비스 페이지에서 API를 볼 수 있습니다.

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

재배포

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

초기 Endpoints 구성 배포 후에는 사용자, 서비스 계정 또는 그룹에 Endpoints 구성을 다시 배포할 수 있도록 허용하는 역할을 부여할 수 있습니다. 자세한 내용은 API에 대한 액세스 권한 부여 및 취소를 참조하세요.

다음 단계