Cloud Endpoints 빠른 시작

이 빠른 시작은 Endpoints가 관리하는 샘플 API를 배포하는 과정을 설명합니다. 샘플 코드에는 다음이 포함됩니다.

  • 3자리 IATA 코드로 공항 이름을 찾기 위해 쿼리할 수 있는 REST API
  • API 구성을 Endpoints에 업로드하는 스크립트
  • 샘플 API를 호스팅하기 위해 App Engine 가변형 환경 백엔드를 배포하는 스크립트

샘플 API로 요청을 보내면 Google Cloud Console에서 Endpoints 활동 그래프와 Google Cloud의 작업 제품군 로그를 볼 수 있습니다. 이러한 도구로 API를 모니터링하고 사용 현황을 파악할 수 있습니다.

이 빠른 시작은 구성 단계를 간소화하는 스크립트를 사용하여 진행 중인 활동 그래프와 로그를 신속하게 확인할 수 있게 합니다. 샘플 API를 구성 및 배포하는 방법을 알아보려면 API 프레임워크 중 하나에 대한 가이드를 선택하세요.

시작하기 전에

  1. Google 계정으로 로그인합니다.

    아직 계정이 없으면 새 계정을 등록하세요.

  2. Cloud Console의 프로젝트 선택기 페이지에서 Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기 페이지로 이동

  3. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

Cloud Shell 시작

  1. Cloud Console에서 샘플 API에 사용할 프로젝트에 있는지 확인합니다.

  2. Cloud Shell을 엽니다.

    Cloud Shell 열기

    Cloud Console 하단의 새로운 프레임에서 Cloud Shell 세션이 열리고 명령줄 프롬프트가 표시됩니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

    Cloud Shell 세션

  3. 기존 프로젝트를 사용하는 경우 설치된 gcloud 구성요소가 모두 최신 버전인지 확인합니다.

    gcloud components update
    

샘플 코드 가져오기

  1. Cloud Shell에서 다음 명령어를 입력하여 샘플 API 및 스크립트를 가져옵니다.

    git clone https://github.com/GoogleCloudPlatform/endpoints-quickstart
    
  2. 샘플 코드가 있는 디렉토리로 변경합니다.

    cd endpoints-quickstart
    

Endpoints 구성 배포

Endpoints에 REST API를 게시하려면 API를 기술하는 OpenAPI 구성 파일이 필요합니다. 샘플 API에는 openapi.yaml이라는 사전 구성된 OpenAPI 파일이 함께 제공됩니다.

Endpoints는 Google Cloud의 인프라 서비스인 Service Management를 사용하여 API와 서비스를 만들고 관리합니다. Endpoints를 사용하여 API를 관리하려면 API의 OpenAPI 구성 파일을 Service Management에 배포합니다.

Endpoints 구성을 배포하려면 다음 안내를 따르세요.

  1. Cloud Shell에서 endpoints-quickstart 디렉터리로 이동하여 다음을 입력합니다.

    cd scripts
    
  2. 샘플에 포함되어 있는 다음 스크립트를 실행합니다.

    ./deploy_api.sh
    

Endpoints는 OpenAPI 구성 파일의 host 필드를 사용하여 서비스를 식별합니다. deploy_api.sh 스크립트는 Google Cloud 프로젝트의 ID를 host 필드에 구성된 이름의 일부로 설정합니다. 자체 서비스의 OpenAPI 구성 파일을 준비하는 경우에는 이 작업을 직접 수행해야 합니다.

그런 다음 이 스크립트는 gcloud endpoints services deploy openapi.yaml 명령어를 사용하여 OpenAPI 구성을 Service Management에 배포합니다.

Service Management는 서비스를 만들고 구성하면서 Cloud Console에 정보를 출력합니다. openapi.yaml 경로에 API 키가 필요하지 않다는 경고는 무시해도 됩니다. 성공적으로 완료되면 서비스 구성 ID와 서비스 이름을 보여주는 다음과 같은 줄이 표시됩니다.

    Service Configuration [2017-02-13-r2] uploaded for service [airports-api.endpoints.example-project.cloud.goog]

필수 서비스 사용 설정

Endpoints를 사용하려면 최소한 다음 Google 서비스를 사용 설정해야 합니다.

이름 제목
servicemanagement.googleapis.com Service Management API
servicecontrol.googleapis.com Service Control API
endpoints.googleapis.com Google Cloud Endpoints

대부분의 경우 Endpoints 구성을 배포하면 이러한 필수 서비스를 사용 설정할 수 있습니다.

다음 명령어를 사용하여 필수 서비스가 사용 설정되어 있는지 확인합니다.

gcloud services list

필수 서비스가 나열되지 않으면 서비스를 사용 설정하세요.

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com
gcloud services enable endpoints.googleapis.com

Endpoints 서비스도 사용 설정해야 합니다.

gcloud services enable YOUR-PROJECT-ID.appspot.com

gcloud 명령어에 대한 자세한 내용은 gcloud 서비스를 참조하세요.

API 백엔드 배포

지금까지 OpenAPI 구성을 Service Management에 배포했지만 아직 API 백엔드를 제공할 코드를 배포하지 않았습니다. 샘플에 포함된 deploy_app.sh 스크립트는 API 백엔드를 호스팅할 App Engine 가변형 환경을 만든 후 API를 App Engine에 배포합니다.

API 백엔드를 배포하려면 다음 안내를 따르세요.

  • Cloud Shell에서 endpoints-quickstart/scripts 디렉터리로 이동하여 다음 스크립트를 실행합니다.

    ./deploy_app.sh
    

이 스크립트는 gcloud app create --region="$REGION" 명령어를 실행하여 us-central 리전에 App Engine 가변형 환경을 만듭니다.

App Engine 가변형 환경 백엔드를 만드는 데 몇 분 정도 걸립니다. 애플리케이션이 생성되면 다음과 같이 출력됩니다.

Success! The app is now created.

그런 다음 이 스크립트는 gcloud app deploy 명령어를 실행하여 샘플 API를 App Engine에 배포합니다.

출력은 다음과 같습니다.

Deploying ../app/app_template.yaml...You are about to deploy the following services:

API를 App Engine에 배포하는 데 몇 분 정도 걸립니다. API가 App Engine에 성공적으로 배포되면 다음과 같이 출력됩니다.

Deployed service [default] to [https://example-project.appspot.com]

API에 요청 보내기

  • 샘플 API를 배포한 후 Cloud Shell에서 다음 스크립트를 실행하여 요청을 보낼 수 있습니다.

    ./query_api.sh
    

이 스크립트는 API에 요청을 보내는 데 사용하는 curl 명령어를 되돌린 후 결과를 표시합니다. 출력은 다음과 같습니다.

curl "https://example-project.appspot.com/airportName?iataCode=SFO"
San Francisco International Airport

API는 SEA, JFK 등의 유효한 IATA 공항 코드로 설정된 쿼리 매개변수 하나(iataCode)를 필요로 합니다. 예를 들면 다음과 같습니다.

./query_api.sh JFK

참고: App Engine이 요청에 성공적으로 응답하는 데 몇 분 정도 걸릴 수 있습니다. 요청을 보내고 HTTP 502, 503 또는 기타 서버 오류가 수신된 경우에는 1분 정도 기다린 후 다시 요청을 시도하세요.

이제 Endpoints에 API를 배포하고 테스트를 마쳤습니다.

API 활동 추적

Endpoints를 사용하여 API를 배포한 후 Cloud Console에서 중요한 작업 측정항목을 모니터링하고 Cloud Logging으로 사용자와 사용 현황을 파악할 수 있습니다.

  1. Cloud Shell에서 트래픽 생성 스크립트를 실행하여 그래프와 로그를 채웁니다.

    ./generate_traffic.sh
    
  2. Cloud Console에서 API의 활동 그래프를 봅니다.

    Endpoints 서비스 페이지로 이동

    요청이 그래프에 반영되는 데 잠시 시간이 걸릴 수 있습니다. 데이터가 표시되기를 기다리는 동안 다음을 확인해 보세요.

    • 권한 측면 패널이 열려 있지 않으면 +권한을 클릭합니다. 권한 패널을 사용하면 API에 액세스하는 사람과 액세스 수준을 제어할 수 있습니다.

    • 배포 기록을 클릭합니다. 이 탭에는 배포 시간과 변경사항을 배포한 사용자를 포함한 API 배포 기록이 표시됩니다.

    • 개요를 클릭합니다. 들어오는 트래픽이 표시됩니다. 트래픽 생성 스크립트가 1분 동안 실행된 후 총 지연 시간 그래프에 세 개의 선(50, 95, 98 백분위수)이 표시됩니다. 이 데이터는 응답 시간을 예측합니다.

  3. 그래프 아래의 표로 스크롤하고 링크에서 GET/airportName로그 보기를 클릭합니다. 로그 뷰어 페이지에 API의 요청 로그가 표시됩니다.

  4. Cloud Shell을 엽니다.

    Cloud Shell 열기

  5. 스크립트를 중지하려면 Ctrl+C를 입력합니다.

API에 할당량 추가

Endpoints로 할당량을 설정하여 애플리케이션이 API를 호출하는 속도를 제어할 수 있습니다. 할당량을 설정하면 단일 클라이언트에서 API를 과도하게 사용하지 못하도록 할 수 있습니다.

  1. Cloud Shell에서 할당량이 설정된 Endpoints 구성을 배포합니다.

    ./deploy_api.sh ../openapi_with_ratelimit.yaml
    

    업데이트된 Endpoints 구성은 배포 후 1분 이내에 활성화됩니다.

  2. Cloud Console에서 사용자 인증 정보 페이지로 이동합니다.

    사용자 인증 정보 페이지로 이동

  3. 사용자 인증 정보 만들기를 클릭하고 API 키를 클릭합니다. 새 API 키가 화면에 표시됩니다.

  4. 복사 를 클릭합니다.

  5. Cloud Shell에 다음을 입력합니다. YOUR_API_KEY를 방금 만든 API 키로 바꿉니다.

    export API_KEY=YOUR_API_KEY
    
  6. 방금 생성한 API 키를 사용하여 API에 요청을 보냅니다.

    ./query_api_with_key.sh $API_KEY
    

    출력은 다음과 비슷합니다.

    curl -H 'x-api-key: AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB' "https://example-project.appspot.com/airportName?iataCode=SFO"
    San Francisco International Airport
    
  7. 이제 API의 분당 요청 수가 5개로 제한됩니다. 다음 명령어를 실행하여 트래픽을 API로 보내고 할당량 한도를 트리거합니다.

    ./generate_traffic_with_key.sh $API_KEY
    
  8. 5~10초 동안 스크립트를 실행한 후 Ctrl-C를 입력하여 스크립트를 중지합니다.

  9. 인증된 다른 요청을 API에 보냅니다.

    ./query_api_with_key.sh $API_KEY
    

    출력은 다음과 비슷합니다.

    {
     "code": 8,
     "message": "Insufficient tokens for quota 'airport_requests' and limit 'limit-on-airport-requests' of service 'example-project.appspot.com' for consumer     'api_key:AIzeSyDbdQdaSdhPMdiAuddd_FALbY7JevoMzAB'.",
     "details": [
      {
       "@type": "type.googleapis.com/google.rpc.DebugInfo",
       "stackEntries": [],
       "detail": "internal"
      }
     ]
    }
    

다른 응답을 받으면 generate_traffic_with_key.sh 스크립트를 다시 실행한 후 다시 시도합니다.

수고하셨습니다. API의 비율 제한을 성공적으로 설정했습니다. API 메서드마다 한도를 다르게 설정하고, 여러 종류의 할당량을 만들고, 어떤 소비자가 어느 API를 사용하는지 추적할 수도 있습니다.

자세한 내용은 할당량 정보를 참조하세요.

API의 개발자 포털 만들기

Cloud Endpoints 포털을 사용하여 샘플 API와 상호작용하는 데 사용할 수 있는 웹사이트인 개발자 포털을 만들 수 있습니다. 자세한 내용은 Cloud Endpoints 포털 개요를 참조하세요.

삭제

이 빠른 시작에서 사용한 리소스의 비용이 Google Cloud 계정에 청구되지 않도록 하려면 다음 단계를 따르세요.

Cloud 프로젝트를 삭제하면 프로젝트 내에서 사용되는 모든 리소스에 대한 결제를 중지하여 비용 청구를 방지할 수 있습니다.

  1. Cloud Console에서 리소스 관리 페이지로 이동합니다.

    리소스 관리 페이지로 이동

  2. 프로젝트 목록에서 삭제할 프로젝트를 선택하고 삭제 를 클릭합니다.
  3. 대화상자에서 프로젝트 ID를 입력한 다음 종료를 클릭하여 프로젝트를 삭제합니다.

다음 단계