개요

OpenAPI 사양에서는 표준 형식을 사용하여 RESTful API를 설명합니다. JSON 또는 YAML 형식으로 작성된 OpenAPI 사양은 기계가 읽을 수 있을 뿐만 아니라 사람도 쉽게 읽고 이해할 수 있습니다.

사양은 기본 경로, 리소스 경로 및 동사, 작업, 헤더, 쿼리 파라미터, 응답 등 API의 요소를 설명합니다. 또한 OpenAPI 사양은 일반적으로 API 참고 리소스를 생성하는 데 사용됩니다.

이 실습에서는 소매 백엔드 서비스의 OpenAPI 사양을 살펴봅니다. 그런 다음 이 OpenAPI 사양을 사용하여 백엔드 API에 기능과 보안을 추가하는 데 사용될 API 프록시를 만듭니다.

목표

이 실습에서는 다음 작업을 수행하는 방법을 알아봅니다.

• OpenAPI 사양을 살펴보고 다양한 구성요소를 이해합니다.
• 프록시 마법사를 사용하여 OpenAPI 사양에서 API 프록시를 만듭니다.
• API 프록시를 추적합니다.

설정

각 실습에서는 정해진 기간 동안 새 Google Cloud 프로젝트와 리소스 집합이 무료로 제공됩니다.

1. 시크릿 창을 사용하여 Google Skills에 로그인합니다.

2. 실습 사용 가능 시간(예: 1:15:00)을 참고하여 해당 시간 내에 완료합니다. 일시중지 기능은 없습니다. 필요한 경우 다시 시작할 수 있지만 처음부터 시작해야 합니다.

3. 준비가 되면 실습 시작을 클릭합니다.

4. 실습 사용자 인증 정보(사용자 이름 및 비밀번호)를 기록해 두세요. Google Cloud Console에 로그인합니다.

5. Google Console 열기를 클릭합니다.

6. 다른 계정 사용을 클릭한 다음, 안내 메시지에 이 실습에 대한 사용자 인증 정보를 복사하여 붙여넣습니다. 다른 사용자 인증 정보를 사용하는 경우 오류가 발생하거나 요금이 부과됩니다.

7. 약관에 동의하고 리소스 복구 페이지를 건너뜁니다.

Google Cloud Shell 활성화하기

Google Cloud Shell은 다양한 개발 도구가 탑재된 가상 머신으로, 5GB의 영구 홈 디렉터리를 제공하며 Google Cloud에서 실행됩니다.

Google Cloud Shell을 사용하면 명령줄을 통해 Google Cloud 리소스에 액세스할 수 있습니다.

1. Cloud 콘솔의 오른쪽 상단 툴바에서 'Cloud Shell 열기' 버튼을 클릭합니다.

   

2. 계속을 클릭합니다.

환경을 프로비저닝하고 연결하는 데 몇 분 정도 소요됩니다. 연결되면 사용자가 미리 인증되어 프로젝트가 PROJECT_ID로 설정됩니다. 예:

gcloud는 Google Cloud의 명령줄 도구입니다. Cloud Shell에 사전 설치되어 있으며 명령줄 자동 완성을 지원합니다.

• 다음 명령어를 사용하여 사용 중인 계정 이름을 나열할 수 있습니다.

gcloud auth list

출력:

Credentialed accounts: - @.com (active)

출력 예시:

Credentialed accounts: - google1623327_student@qwiklabs.net

• 다음 명령어를 사용하여 프로젝트 ID를 나열할 수 있습니다.

gcloud config list project

출력:

[core] project =

출력 예시:

[core] project = qwiklabs-gcp-44776a13dea667a6 참고: gcloud 전체 문서는 gcloud CLI 개요 가이드를 참조하세요.

작업 1. 백엔드 서비스의 OpenAPI 사양 검토

이 작업에서는 API 프록시에서 사용할 백엔드 서비스를 위해 생성된 OpenAPI 사양을 살펴봅니다.

OpenAPI 사양 다운로드

• Cloud Shell에서 다음 curl 명령어를 사용하여 백엔드 서비스의 OpenAPI 사양을 다운로드합니다.

  curl https://storage.googleapis.com/cloud-training/developing-apis/specs/retail-backend.yaml?$(date +%s) --output ~/retail-backend.yaml

  이 curl 명령어는 retail-backend.yaml 파일을 다운로드하며, 홈 디렉터리에 있고 이름이 같은 파일에 저장합니다. 실습의 뒷부분에서 API 프록시를 만들 때 이 사양을 동일하게 사용합니다.

  참고: '?$(date +%s)'는 현재 날짜/시간 문자열 표현인 쿼리 파라미터를 URL에 추가합니다. 이 동적으로 변경되는 변수는 URL을 변경하고 이전 버전이 캐시된 경우에도 강제로 curl이 최신 버전의 파일을 가져오도록 합니다.

Cloud Shell 편집기에서 OpenAPI 사양 보기

1. Cloud Shell에서 편집기 열기를 클릭합니다.

   

2. 편집기에서 retail-backend.yaml 파일을 선택합니다.

   

사양 섹션 살펴보기

1. OpenAPI 사양을 검토합니다.

   이는 여러 과정 실습에서 사용될 백엔드 서비스의 OpenAPI 사양입니다. OpenAPI 사양의 섹션을 살펴보겠습니다.

   openapi 필드는 OpenAPI 사양의 버전을 지정합니다. 파일 상단의 버전 번호에서 알 수 있듯이 OpenAPI 버전 3 사양입니다.

   openapi: "3.0.0"

   info 객체는 API 자체에 대한 메타데이터를 제공합니다. 표시된 버전은 Retail Backend 사양의 버전입니다.

   info: version: 1.0.0 title: Retail Backend description: Retail backend database used for Developing APIs course contact: name: Google Cloud (Apigee) email: apigee@example.org url: https://cloud.google.com/apigee license: name: MIT url: https://opensource.org/licenses/MIT

   servers 배열에는 대상 서버의 연결 정보를 지정하는 서버 객체 목록이 포함되어 있습니다. 이 사양에는 API 프록시가 호출할 단일 백엔드 서비스가 포함되어 있습니다.

   servers: - url: "https://gcp-cs-training-01-test.apigee.net/training/db" description: Retail backend for Developing APIs course

   tags 배열은 아래에 표시된 작업에 사용되는 태그에 메타데이터를 추가합니다. 태그는 여러 작업에서 공유할 수 있으며, 태그를 사용하여 자세한 설명이나 외부 문서에 대한 링크를 제공할 수 있습니다.

   tags: - name: categories description: Product Categories - name: products description: Products - name: orders description: Orders - name: stores description: Stores

   paths 객체는 개별 엔드포인트와 그 작업에 대한 상대 경로를 보유합니다. 이러한 경로 중 하나인 /categories/{categoryId}는 단일 카테고리를 지정하는 데 사용됩니다. 여기에는 ID로 카테고리를 가져오도록 지정된 get 작업이 표시되어 있습니다. get 객체는 파라미터와 응답을 보여줍니다. PATCH /products/{productId}와 같이 요청 본문을 포함하는 작업의 경우 요청 본문도 지정됩니다.

   /categories/{categoryId}: get: summary: Get a specific category operationId: getCategoryById tags: - categories parameters: - name: categoryId in: path required: true description: category id schema: type: integer responses: '200': description: Selected category content: application/json: schema: $ref: "#/components/schemas/Category" '404': description: Category not found content: application/json: schema: $ref: "#/components/schemas/Error" default: description: unexpected error content: application/json: schema: $ref: "#/components/schemas/Error"

   components 객체에는 OpenAPI 사양의 여러 부분에 재사용할 수 있는 객체가 포함되어 있습니다. securitySchemes 구성요소 객체에는 작업에서 사용하는 다양한 유형의 보안 스키마 정의가 포함되어 있습니다. 이 사양은 PATCH /products/{productId} 작업에서 참조되는 단일 기본 인증 스키마를 정의합니다. schemas 구성요소 객체에는 입력 및 출력 데이터 유형이 포함되어 있습니다. 여기에 표시된 Category 객체는 GET /categories/{categoryId} 작업이 성공적으로 완료될 때 반환됩니다.

   components: securitySchemes: basicAuth: type: http description: basic auth scheme: basic schemas: Category: type: object description: product category required: - color - id - name properties: color: description: use this color for displaying this category type: string id: description: integer id (used for access) type: integer format: int32 minimum: 0 name: description: category name type: string

   사양 또는 OpenAPI 사양 문서를 자유롭게 살펴보세요.

2. 이 OpenAPI 사양에 대한 자세한 내용을 보려면 편집기에서 Gemini Code Assist 패널을 사용하세요. 프롬프트 섹션에서 컨텍스트 항목을 펼치고 현재 파일인 retail-backend.yaml 파일이 선택되어 있는지 확인합니다.

3. 프롬프트에 다음을 입력합니다.

   Explain the contents of this file.

4. 보내기()를 클릭합니다.

   Gemini가 백엔드 OpenAPI 사양의 내용을 설명하는 대답을 생성합니다. 정의된 섹션의 목적을 설명하는 개괄적인 요약과 주요 섹션이 포함되어 있습니다.

OpenAPI 사양을 머신에 다운로드

1. 터미널 열기를 클릭합니다.

2. Cloud Shell의 더보기 메뉴()를 선택한 다음 다운로드를 클릭합니다.

3. retail-backend.yaml을 입력한 다음 다운로드를 클릭합니다.

   그러면 파일이 로컬 머신에 다운로드됩니다.

작업 2. OpenAPI 사양을 사용하여 API 프록시 만들기

이 작업에서는 백엔드 서비스의 OpenAPI 사양을 사용하여 API 프록시를 만듭니다.

Apigee 콘솔 페이지 고정

1. Google Cloud 콘솔의 탐색 메뉴()에 있는 즐겨 찾는 제품 섹션에서 Apigee를 찾습니다.

   Apigee 콘솔 페이지가 열립니다.

2. Apigee가 표시되지 않는 경우 상단 검색창에서 Apigee를 검색하고 Apigee 서비스로 이동합니다.

3. 콘솔에 Apigee를 고정하려면 즐겨찾기 아이콘()을 클릭합니다.

   이제 Apigee 콘솔 페이지가 탐색 메뉴에서 즐겨 찾는 제품으로 표시됩니다.

프록시 마법사를 사용하여 프록시 만들기

1. 왼쪽 탐색 메뉴에서 프록시 개발 > API 프록시를 선택합니다.

2. 프록시 마법사를 시작하려면 + 만들기를 클릭합니다.

3. 프록시 템플릿에서 OpenAPI 사양 템플릿 > 리버스 프록시(가장 일반적)를 선택합니다.

4. OpenAPI 사양에서 찾아보기를 클릭하고 다운로드한 retail-backend.yaml 파일을 선택한 다음 열기를 클릭합니다.

5. 다음을 클릭합니다.

6. 프록시 세부정보에 다음을 지정합니다.

   속성	값
   프록시 이름	retail-v1
   기본 경로	/retail/v1
   설명	내 Retail API

   타겟은 OpenAPI 사양의 servers 배열에서 가져온 것입니다. 타겟을 변경하지 마세요.

   참고: 기본 경로에 '/retail-v1'이 아닌 '/retail/v1'을 사용하고 있는지 확인하세요.

7. 다음을 클릭합니다.

   OpenAPI 사양에서 발견된 작업이 나열됩니다.

8. 흐름의 헤더 행에서 모든 행 선택을 클릭합니다.

   이제 모든 흐름이 선택됩니다.

9. 다음을 클릭합니다.

10. 배포 환경에서 eval 환경을 선택한 다음 확인을 클릭합니다.

    참고: '서비스 계정' 필드는 비워 둡니다.

11. 만들기를 클릭합니다.

    프록시가 생성되고 배포를 위해 표시됩니다.

런타임 사용 가능 시점이 지연될 수 있음

Apigee 조직이 완전히 프로비저닝되려면 일반적으로 30분 이상 걸립니다. 대부분의 시간은 API 프록시를 실행하는 데 필요한 런타임 클러스터, 런타임 데이터베이스, 서비스를 프로비저닝하는 데 소요됩니다. 수명이 긴 Apigee 조직을 만들 때는 전체 프로비저닝 지연 현상이 문제가 되지 않습니다. 하지만 각 실습을 시작하기 전에 30분을 기다리는 일은 원치 않으실 것입니다.

실습에 참여하면 조직이 이미 완전히 프로비저닝된 경우가 있습니다. 실습을 시작할 때만 Apigee 조직의 프로비저닝이 시작되는 경우도 있습니다.

조직의 관리 영역 작업은 프로비저닝 프로세스가 완료된 후 몇 분이 지나야 수행할 수 있습니다. 이러한 실습을 사용하면 런타임이 완전히 프로비저닝될 때까지 기다리는 대신, 런타임이 제공되기 전에 프록시 수정과 같은 작업을 수행할 수 있습니다. 런타임을 사용할 수 있기 전에 환경에 프록시를 배포하면 런타임 프로비저닝이 완료되기 전에는 트래픽을 수신할 수 없습니다.

아래와 같이 배포된 프록시의 상태 아이콘 위로 마우스 포인터를 가져가면 상태를 보고하는 인스턴스가 없다고 표시될 수 있습니다. 이는 Apigee 조직의 런타임이 완전히 프로비저닝될 때까지는 정상적인 현상입니다.

Apigee 프록시 배포 알아보기

Apigee 환경에 API 프록시를 배포하는 프로세스에 대해 알아보려면 Google Cloud 콘솔에서 Gemini Cloud Assist를 사용하면 됩니다.

Gemini Cloud Assist 열기

1. Gemini Cloud Assist를 열려면 Google Cloud 콘솔에서 Gemini Cloud Assist 채팅 열기 또는 닫기()를 클릭합니다.

2. Cloud Assist 패널에 메시지가 표시되면 Gemini Cloud Assist 사용 설정을 클릭합니다.

3. 원하는 경우, 사용 설정해야 하는 필수 및 권장 API를 확인합니다.

4. Gemini Cloud Assist 무료 사용 설정을 선택합니다.

5. 채팅 시작을 클릭합니다.

Gemini에 프롬프트 입력하기

1. 프롬프트에 다음을 입력합니다.

   In Apigee X, explain the deployment process of an API proxy to an Apigee environment.

2. 보내기()를 클릭합니다.

   Gemini Cloud Assist가 생성한 대답을 확인합니다.

3. 선택사항: 관련 콘텐츠 표시를 클릭하여 관련 문서를 찾아봅니다.

배포 상태 확인

배포되어 트래픽을 수신할 준비가 된 프록시는 개요 탭에 녹색 상태로 표시됩니다.

프록시가 배포된 것으로 표시되지만 런타임이 아직 사용 가능하지 않고 환경이 아직 연결되지 않은 경우, 빨간색 경고 표시가 나타날 수 있습니다. 상태 아이콘 위로 마우스 포인터를 가져가면 현재 상태가 표시됩니다.

배포되어 녹색으로 표시되는 프록시는 API 트래픽을 처리할 수 있습니다. 런타임 포드가 없어 프록시가 배포되지 않은 경우 프로비저닝 상태를 확인할 수 있습니다.

프로비저닝 상태 확인

• 런타임 인스턴스가 설치되고 eval 환경이 연결되었는지 확인하려면 Cloud Shell에서 다음 명령어를 실행합니다.

  export PROJECT_ID=$(gcloud config list --format 'value(core.project)'); echo "PROJECT_ID=${PROJECT_ID}"; export INSTANCE_NAME=eval-instance; export ENV_NAME=eval; export PREV_INSTANCE_STATE=; echo "waiting for runtime instance ${INSTANCE_NAME} to be active"; while : ; do export INSTANCE_STATE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}" | jq "select(.state != null) | .state" --raw-output); [[ "${INSTANCE_STATE}" == "${PREV_INSTANCE_STATE}" ]] || (echo; echo "INSTANCE_STATE=${INSTANCE_STATE}"); export PREV_INSTANCE_STATE=${INSTANCE_STATE}; [[ "${INSTANCE_STATE}" != "ACTIVE" ]] || break; echo -n "."; sleep 5; done; echo; echo "instance created, waiting for environment ${ENV_NAME} to be attached to instance"; while : ; do export ATTACHMENT_DONE=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" -X GET "https://apigee.googleapis.com/v1/organizations/${PROJECT_ID}/instances/${INSTANCE_NAME}/attachments" | jq "select(.attachments != null) | .attachments[] | select(.environment == \"${ENV_NAME}\") | .environment" --join-output); [[ "${ATTACHMENT_DONE}" != "${ENV_NAME}" ]] || break; echo -n "."; sleep 5; done; echo "***ORG IS READY TO USE***"; 이 명령어는 Apigee API를 사용하여 런타임 인스턴스가 생성되고 eval 환경이 인스턴스에 연결된 시점을 확인합니다. 이 명령어를 Cloud Assist에 복사하면 Gemini가 명령어 작동 방식을 설명해 줍니다.

  스크립트에서 ORG IS READY TO USE를 반환하면 다음 단계를 진행해도 됩니다.

기다리는 동안 살펴볼 항목

• 웹 API 설계: 빠진 연결고리 — API 설계 원칙에 관한 eBook
• OpenAPI 사양

작업 3. API 프록시 탐색 및 추적

디버그 도구 시작

1. 개발 탭을 선택합니다.

   이 탭은 생성된 프록시를 수정하는 데 사용됩니다. OpenAPI 사양의 각 작업에 대해 조건부 흐름이 생성되었습니다. 이러한 조건부 흐름은 왼쪽의 탐색기에서 프록시 엔드포인트에 표시됩니다. 조건부 흐름을 클릭하면 비주얼 편집기 창에서 요청 및 응답 섹션이 선택됩니다. 아래에 표시된 default.xml 코드는 프록시 엔드포인트 흐름의 코드 표현입니다.

   

   이러한 조건부 흐름 중 다수는 이후 실습에서 업데이트할 예정입니다.

2. 디버그 탭을 선택합니다.

   디버그 도구는 프록시에서 처리되는 API 요청을 추적하는 데 사용됩니다.

3. 디버그 세션 시작을 클릭합니다.

4. 디버그 세션 시작 창의 환경 드롭다운에서 eval을 선택합니다.

   배포된 버전 번호도 드롭다운에 표시됩니다.

5. 시작을 클릭합니다.

   디버그 세션은 10분 동안 실행됩니다.

비공개 DNS를 사용하여 API 프록시 테스트

호스트 이름 eval.example.com을 사용하여 Apigee 조직의 eval 환경을 호출할 수 있습니다. 이 호스트 이름의 DNS 항목은 프로젝트 내에 생성되었으며 Apigee 런타임 인스턴스 IP 주소로 확인됩니다. 이 DNS 항목은 비공개 영역에 생성되었으므로 내부 네트워크에서만 표시됩니다.

Cloud Shell은 내부 네트워크에 상주하지 않으므로 Cloud Shell 명령어는 이 DNS 항목을 확인할 수 없습니다. 프로젝트 내의 가상 머신(VM)이 비공개 영역 DNS에 액세스할 수 있습니다. 이를 위해 apigeex-test-vm이라는 이름의 가상 머신이 자동으로 생성되었습니다. 이 머신에서 API 프록시를 호출할 수 있습니다.

curl 명령어를 사용하여 API 프록시에 API 요청을 보냅니다. curl의 -k 옵션은 TLS 인증서 확인을 건너뛰라고 지시합니다. 이 실습에서 Apigee 런타임은 자체 서명 인증서를 사용합니다. 프로덕션 환경에서는 신뢰할 수 있는 인증 기관(CA)에서 발행한 인증서를 사용해야 합니다.

1. Cloud Shell에서 새 탭을 열고 테스트 VM에 대한 SSH 연결을 엽니다.

   TEST_VM_ZONE=$(gcloud compute instances list --filter="name=('apigeex-test-vm')" --format "value(zone)") gcloud compute ssh apigeex-test-vm --zone=${TEST_VM_ZONE} --force-key-file-overwrite

   첫 번째 gcloud 명령어는 테스트 VM의 영역을 가져오고 두 번째 명령어는 VM에 대한 SSH 연결을 엽니다.

2. 메시지가 표시되면 Y를 입력하여 계속 진행합니다.

   Cloud Shell에서 묻는 질문마다 Enter 또는 Return을 클릭하여 기본 입력을 지정합니다.

   로그인한 ID가 프로젝트 소유자이므로 이 머신에 대한 SSH가 허용됩니다.

   이제 Cloud Shell 세션이 VM 내에서 실행됩니다.

API 프록시 호출

1. eval 환경에서 호스팅되는 프록시를 호출하려면 Cloud Shell SSH 세션에서 다음 명령어를 사용하여 API 프록시에 요청을 보냅니다.

   curl -i -k -X GET https://eval.example.com/retail/v1/categories

   이 요청에 대한 트랜잭션이 왼쪽의 트랜잭션 창에 표시됩니다. 트랜잭션을 선택하면 Apigee를 통한 요청 및 응답의 트레이스가 표시됩니다. 백엔드 URL이 올바르게 설정되고 요청 전송 URL이 올바르게 업데이트된 경우 200 상태 코드가 표시됩니다.

   참고: Apigee 디버그 세션 트래픽은 새 API 호출을 비동기식으로 폴링하여 검색되므로 API 요청이 완료된 시점과 디버그 도구에 표시되는 시점 사이에 지연이 발생할 수 있습니다.

2. 뒤로 및 다음 버튼을 클릭하여 트랜잭션 단계를 탐색합니다.

   요청은 GET /retail/v1/categories였습니다. 이 요청은 백엔드로 전송되었고, 백엔드는 카테고리가 포함된 JSON 배열로 응답했습니다.

수고하셨습니다

이 실습에서는 OpenAPI 사양에 대해 알아보고 OpenAPI 사양의 몇 가지 기능을 살펴보았습니다. 소매 백엔드 서비스의 OpenAPI 사양을 사용하여 API 프록시를 만들고 해당 프록시를 통해 호출을 추적했습니다.

실습 종료하기

실습을 완료하면 실습 종료를 클릭합니다. Google Skills에서 사용된 리소스를 자동으로 삭제하고 계정을 지웁니다.

실습 경험을 평가할 수 있습니다. 해당하는 별표 수를 선택하고 의견을 입력한 후 제출을 클릭합니다.

별점의 의미는 다음과 같습니다.

• 별표 1개 = 매우 불만족
• 별표 2개 = 불만족
• 별표 3개 = 중간
• 별표 4개 = 만족
• 별표 5개 = 매우 만족

의견을 제공하고 싶지 않다면 대화상자를 닫으면 됩니다.

의견이나 제안 또는 수정할 사항이 있다면 지원 탭을 사용하세요.

Copyright 2026 Google LLC All rights reserved. Google 및 Google 로고는 Google LLC의 상표입니다. 기타 모든 회사명 및 제품명은 해당 업체의 상표일 수 있습니다.