Cloud Endpoints Frameworks 버전 2.0으로 이전

이전에는 Cloud Endpoints Frameworks를 Endpoints라고 불렀습니다. 두 버전을 구분하기 위해 이 페이지에서는 새 버전을 Endpoints Frameworks 버전 2.0으로, 이전 버전을 Endpoints 버전 1.0이라고 지칭합니다. 이 페이지에서는 Cloud Endpoints 버전 1.0을 Endpoints Frameworks 버전 2.0으로 이전하는 방법을 설명합니다. 이전을 위해 라이브러리와 애플리케이션 구성을 변경해야 하지만 코드를 변경할 필요는 없습니다.

장점

Endpoints 버전 2.0에는 다음과 같은 여러 가지 장점이 있습니다.

  • 요청 지연 시간 감소
  • App Engine 기능(예: 커스텀 도메인)과의 통합 향상
  • 새로운 API 관리 기능

Endpoints Frameworks 버전 2.0은 API 인터페이스에 영향을 미치지 않습니다. 기존 클라이언트는 이전 후에도 클라이언트 측 코드 변경 없이 계속 작동합니다.

기능 개요

이전 버전인 Endpoints 버전 1.0과 호환되는 기능은 다음과 같습니다.

  • 모든 Google 클라이언트 라이브러리에서 사용되는 JSON-REST 프로토콜
  • 검색 서비스
  • 모든 기존 인증 기능(OAuth2/OpenID Connect)
  • 생성된 클라이언트에 대한 클라이언트 라이브러리 지원
  • CORS(Google 자바스크립트 클라이언트 라이브러리를 사용하지 않는 자바스크립트 호출자용)
  • API 탐색기

트래픽 분할은 제공되지 않습니다.

현재 제외된 기능

제공되지 않는 기능은 다음과 같습니다. 이 중에서 필요한 기능이 있으면 기능 요청을 제출하세요.

  • 기존 iOS 클라이언트에 필요한 JSON-RPC 프로토콜. Endpoints 프레임워크 버전 2.0 API의 iOS 클라이언트를 만들려면 REST API용 Google API Objective-C 클라이언트 라이브러리를 사용하는 것이 좋습니다.
  • 자동 ETag
  • 자동 kind 필드
  • IDE 통합
  • fields 부분 응답
  • 자동 PATCH API 메서드 생성

Endpoints 버전 1.0에서 이전

버전 1.0에서 이전하려면 다음 단계를 따르세요.

  1. 애플리케이션 기본 디렉터리에 /lib라는 하위 폴더를 만듭니다.

  2. 애플리케이션의 기본 디렉토리에서 라이브러리를 설치합니다.

     pip install -t lib google-endpoints --ignore-installed
    
  3. libraries 섹션 아래의 애플리케이션의 app.yaml 파일에서 - name: endpointsversion 1.0 항목을 삭제합니다. 예:

    libraries:
    - name: endpoints   #Remove
      version: 1.0      #Remove
    
  4. app.yaml 파일의 libraries 섹션에 다음을 추가합니다.

    libraries:
    - name: pycrypto
      version: 2.6
    - name: ssl
      version: 2.7.11
    

    Endpoints Frameworks에는 이러한 버전의 pycryptossl 라이브러리가 필요합니다.

  5. app.yaml 파일의 handlers 섹션에서 url 지시문을 - url: /_ah/spi/.*에서 - url: /_ah/api/.*로 변경합니다.

  6. 애플리케이션의 루트 디렉터리에서 appengine_config.py라는 파일을 만들거나 수정하여 다음을 포함합니다.

    from google.appengine.ext import vendor
    
    vendor.add('lib')
    
  7. API 버전 문자열을 확인합니다. @endpoints.api(version='v1', ...) 데코레이터에 지정된 버전 문자열이 API 경로에 표시됩니다. SemVer 표준과 호환되는 버전 문자열을 지정하면 API를 배포할 때 API 경로에 주 버전 번호만 표시됩니다. 예를 들어 이름이 echo이고 버전은 2.1.0인 API의 경로는 /echo/v2와 같습니다. echo API를 버전 2.2.0으로 업데이트하고 이전 버전과 호환되는 변경 사항을 배포하면 경로는 /echo/v2로 유지됩니다. 따라서 클라이언트의 기존 경로를 유지하면서 이전 버전과 호환되는 변경을 수행하면 API 버전 번호를 업데이트할 수 있습니다. 하지만 echo API를 버전 3.0.0으로 업데이트하는 경우 브레이킹 체인지를 배포하는 것이기 때문에 경로가 /echo/v3으로 변경됩니다.

  8. Endpoints Frameworks 애플리케이션을 다시 배포합니다.

새 배포 확인

새 프레임워크가 트래픽을 제공하는지 확인하는 방법은 다음과 같습니다.

  1. 새 배포에 요청을 보냅니다.
  2. 프로젝트의 Stackdriver Logging 페이지를 방문합니다.

    로그 뷰어 페이지로 이동

  3. 요청에 표시되는 경로가 /_ah/api로 시작되면 Endpoints Frameworks 버전 2.0이 API를 제공하고 있는 것입니다. 경로가 /_ah/spi로 시작되는 요청은 로그에 표시되지 않아야 합니다. 이러한 요청은 Endpoints 버전 1.0 프록시에서 여전히 요청을 처리하고 있음을 나타냅니다.

API 관리 추가

Endpoints Frameworks 버전 2.0은 다음을 포함한 API 관리 기능을 추가합니다.

  • API 키 관리
  • API 공유
  • 사용자 인증
  • API 측정항목
  • API 로그

시작하려면 Python용 Endpoints Frameworks 시작하기 페이지로 이동하세요.

문제해결

이 섹션에서는 Endpoints 프레임워크 버전 2.0으로 마이그레이션할 때 일반적으로 나타나는 불안정한 동작과 추천 해결 방법을 설명합니다.

API에서 404 오류를 반환하되 API 탐색기에는 API 목록이 올바르게 표시됨

Endpoints Frameworks 버전 2.0으로 이전할 때는 이전 버전 1.0 Endpoints 구성을 삭제해야 합니다. 애플리케이션 구성에 이전 구성이 남아 있으면 Endpoints 서비스가 앱을 계속 버전 1.0 앱으로 취급합니다. 이러한 경우 /_ah/spi로 전송된 요청이 App Engine 로그에 나타날 수 있으며, 이로 인해 클라이언트에 HTTP 404 오류가 전송됩니다.

  1. app.yaml 파일에 다음 줄이 있으면 삭제합니다.

    handlers:
    - url: /_ah/spi/.*
      script: ...
    
  2. app.yaml 파일의 handlers 섹션에 다음과 같이 정확한 경로가 있는지 확인합니다.

    handlers:
    # The endpoints handler must be mapped to /_ah/api.
    - url: /_ah/api/.*
      script: ...
    

오류 메시지: ImportError: cannot import name locked_file

이 문제는 종속 항목에 App Engine과 호환되지 않는 oauth2client 라이브러리 버전이 포함된 경우 발생합니다. 알려진 문제를 참조하세요.