Cloud Endpoints에서 관리되는 API 배포

Cloud Endpoints에서 관리되는 API 배포

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

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

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

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

• OpenAPI용 Cloud Endpoints: 가이드
• gRPC용 Cloud Endpoints: 가이드
• Cloud Endpoints Frameworks: 가이드

시작하기 전에

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

Cloud Shell 시작

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

2. Cloud Shell을 엽니다.

   Cloud Shell 열기

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

   

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

   gcloud components update
   

참고: Linux 또는 MacOS 머신에서 로컬 셸을 사용하여 빠른 시작을 진행하려는 경우에는 Google Cloud CLI를 다운로드하고 Cloud Shell 대신 로컬 명령줄 인터페이스를 사용하여 빠른 시작의 안내를 따르세요.

샘플 코드 가져오기

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

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

필수 서비스 사용 설정

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

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

대부분의 경우 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를 배포하고 테스트를 마쳤습니다.

참고: 이 튜토리얼에서 마음에 든 부분을 알려주시려면 이 페이지의 하단에서 의견을 제출해주세요. 여러분의 의견은 이 튜토리얼을 개선하는 데 도움이 됩니다.
오류가 발생하면 google-cloud-endpoints Google 그룹에 가입하여 어떤 문제가 있었는지 알려주세요. 다른 Endpoints 사용자와 이 그룹을 모니터링하는 Google 엔지니어가 답변해 드립니다.

API 활동 추적

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

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

   ./generate_traffic.sh
   

   참고: 이 스크립트는 요청을 루프로 생성하다가 5분 후 자동으로 타임아웃됩니다. 스크립트를 더 빨리 끝내려면 Cloud Shell에서 Control+C를 입력합니다.

2. Google Cloud 콘솔에서 API의 활동 그래프를 봅니다.

   Endpoints 서비스 페이지로 이동

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

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

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

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

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

4. Cloud Shell을 엽니다.

   Cloud Shell 열기

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

API에 할당량 추가

베타

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제공 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

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

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

   ./deploy_api.sh ../openapi_with_ratelimit.yaml
   

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

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

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

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초 동안 스크립트를 실행한 후 Control+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 계정에 청구되지 않도록 하려면 다음 단계를 수행합니다.

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

주의: 프로젝트를 삭제하면 다음과 같은 효과가 발생합니다.
• 프로젝트의 모든 항목이 삭제됩니다. 이 문서의 태스크에 기존 프로젝트를 사용한 경우 프로젝트를 삭제하면 프로젝트에서 수행한 다른 작업도 삭제됩니다.
• 커스텀 프로젝트 ID가 손실됩니다. 이 프로젝트를 만들 때 앞으로 사용할 커스텀 프로젝트 ID를 만들었을 수 있습니다. appspot.com URL과 같이 프로젝트 ID를 사용하는 URL을 보존하려면 전체 프로젝트를 삭제하는 대신 프로젝트 내에서 선택한 리소스만 삭제합니다.
1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

다음 단계

• Endpoints 개요:

  • Endpoints 정보
  • Endpoints: 아키텍처 개요

• Endpoints에서 지원하는 다양한 API 프레임워크에 대해 알아보기:

  • OpenAPI 사양
  • gRPC API용 Endpoints
  • Endpoints Frameworks 정보

• 샘플 API를 구성 및 배포하는 방법을 알아보려면 API 프레임워크 중 하나에 대한 튜토리얼을 선택하세요.

  • OpenAPI용 Endpoints: 가이드
  • gRPC용 Endpoints: 가이드
  • Endpoints Frameworks: 가이드