API 설계 및 수정

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

이 페이지에서는 Cloud Code의 Apigee에서 API를 설계 및 수정하고 Gemini Code Assist를 활용하여 API 사양 생성, 수정, 관리를 가속화하는 방법을 안내합니다.

시작하기 전에

이 가이드의 기능을 사용하기 전에 다음을 완료하세요.

Apigee로 Gemini Code Assist 사용을 포함하여 VS Code용 Cloud Code에서 Apigee API 관리 설정의 설정 단계를 완료했는지 확인합니다.
각 태스크에 대하여 Apigee에서 Gemini Code Assist를 사용하는 데 필요한 역할에 나열된 필수 역할이 사용자 계정에 있는지 확인합니다.

효과적인 API 사양 프롬프트 작성

API 사양을 만들고 수정할 때 Apigee에서 Gemini Code Assist에 프롬프트를 표시합니다. 생성된 API 사양의 정확성과 적합성은 모델에 제공된 프롬프트에 크게 좌우됩니다.

효과적인 API 사양 생성 및 수정 프롬프트를 작성하려면 다음 안내를 따르세요.

Gemini Code Assist 채팅을 사용할 때는 프롬프트 시작 부분에 항상 Apigee 핸들(@Apigee)을 사용하여 API 사양을 만들거나 수정하세요. Apigee 핸들을 사용하면 이 가이드에 설명된 강력하고 기능이 풍부한 API 사양 개발 기능이 포함된 Apigee 도구에 액세스할 수 있습니다.
자연어 사용: 사람에게 사양을 만들도록 시키는 것처럼 프롬프트를 작성합니다.
구체적으로 설명: 치과 예약 API에 여러 예약 유형과 여러 치과 위치가 포함되어야 하는 등 가능한 경우 정확한 요구사항을 제공합니다.
객체 이름을 지정하지 않고 엔터프라이즈 컨텍스트 활용: Gemini Code Assist는 API 허브 카탈로그의 기존 스키마, 메타데이터, 보안 정의를 지능적으로 감지하고 재사용합니다. 정확한 객체 이름을 지정할 필요는 없지만 프롬프트에 Use API Hub 또는 Leverage Enterprise Context와 같은 문구를 포함하여 이 기능을 힌트로 제공할 수 있습니다.
후속 프롬프트를 사용하여 API 반복: '이 API에서 위치 항목을 삭제해'와 같은 프롬프트를 사용하여 API를 변경할 수 있습니다.

다음은 API 사양을 만들고 수정할 때 효과가 좋지 않은 프롬프트와 효과가 좋은 프롬프트의 예시입니다.

효과가 좋지 않은 프롬프트	프롬프트 설명	효과가 좋은 프롬프트
"내 가게에 사용할 API를 만들어줘."	프롬프트에 포함된 정보가 너무 적어 모델이 완전하고 정확한 사양을 생성하기 어렵습니다.	"고객이 제품의 재고를 확인하고 장바구니에 상품을 추가할 수 있도록 내 매장의 API를 만들어 줘." "고객이 신용카드, 체크카드 등의 다양한 결제 수단을 사용하여 주문 금액을 결제할 수 있는 API를 만들어줘."
"주문 객체를 재사용하는 새 환불 API를 만들어줘."	API를 만들 때 Gemini Code Assist에서 어떤 객체를 재사용할지 지정하지 마세요. 재사용하기에 가장 적합한 객체를 Gemini Code Assist가 자동으로 감지합니다.	"고객이 이전 주문에 대한 환불을 요청할 수 있는 새로운 환불 API를 만들어줘."
"배송 서비스용 API를 만들어줘."	생성된 API가 너무 일반적입니다.	"우리는 피자 레스토랑이고 맞춤설정된 온라인 피자 배달 솔루션을 만들려고 해. 피자 크기와 토핑이 있는 피자 주문을 수락하는 API를 만들어줘." "음식 배달 비즈니스용 API를 부탁해. 고객은 피자, 버거 또는 샌드위치를 한 번에 주문할 수 있어. 이러한 각 음식 유형에는 고유한 스키마가 있어. 피자에는 토핑과 크기가 있어. 버거에는 토핑과 패티 유형이 있어. 샌드위치에는 빵 종류, 고기 종류, 야채, 치즈, 그리고 맞춤 요청사항이 있어."

Gemini Code Assist로 API 설계

Cloud Code에서 Gemini Code Assist를 사용하여 OpenAPI 사양(OAS), 버전 3.0 API를 설계할 수 있습니다. 설계된 API는 새 API를 생성할 때 엔터프라이즈 컨텍스트를 포함할 수 있으며, API 허브를 사용하는 프로젝트에서만 제공됩니다.

이 섹션의 기능을 사용하기 위한 설정 단계는 시작하기 전에를 참고하세요.

Gemini Code Assist로 새 API를 생성하려면 다음 단계를 따르세요.

다음 방법 중 하나를 사용하여 API 사양 생성 프롬프트에 액세스합니다.
- Gemini Code Assist: 채팅: 채팅 창에 Apigee 핸들(@Apigee)을 입력하고 Apigee 도구를 선택합니다.
- Cloud Code의 Apigee에서: Apigee 행에서 마법 지팡이를 클릭합니다. 그러면 Gemini Code Assist: Chat이 로드됩니다. @Apigee로 Apigee 도구를 호출하여 사양 생성을 시작합니다.
Apigee 도구 옵션에서 API 사양 만들기를 선택합니다.
새 API에 대한 설명을 포함하여 프롬프트를 완성합니다. 효과적인 API 사양 프롬프트 작성을 참고하세요. (@Apigee 핸들 위에 복사하여 붙여넣지 마세요. 대신 핸들 뒤에 텍스트를 입력하거나 붙여넣어 프롬프트를 완성합니다.)
프롬프트를 제출합니다.
Gemini Code Assist는 API를 정의하는 OAS를 생성합니다. (이 프로세스는 최대 1분 정도 걸릴 수 있습니다.) API 허브에 다른 API가 포함된 경우 새 OAS는 카탈로그의 객체와 컨텍스트를 통합할 수 있습니다. 상황별 채팅 요약은 생성된 API와 사용된 소스에 대한 정보를 제공합니다.
생성된 사양을 검토합니다. 새 API의 YAML 코드 사양과 Swagger 패널이 탭에 자동으로 표시됩니다.
새 사양이 완료되면 모의 서버를 사용하여 테스트할 수 있습니다. 모의 서버를 사용하여 API 테스트를 참조하세요.
새 API를 API 허브 카탈로그에 저장하려면 API 허브에 API 게시를 참고하세요.
이 사양에서 Apigee API 프록시 번들을 만들려면 API 프록시 번들로 저장을 참고하세요.

API 수정

로컬에 저장했거나 API 허브 카탈로그에 저장한 API를 수정할 수 있습니다. Cloud Code에서 변경한 내용을 API 허브에 저장하거나 Apigee API 프록시 번들로 저장할 수 있습니다.

API 허브에서 API 사양 수정

API 허브 카탈로그에 저장된 API 사양을 수정하려면 다음 단계를 따르세요.

Cloud Code에서 선택한 프로젝트가 수정할 API가 포함된 API 허브 카탈로그가 있는 프로젝트인지 확인합니다.
왼쪽 탐색 메뉴의 Apigee 섹션에서 API 허브 트리를 펼칩니다.
목록에서 수정할 API 및 버전을 선택합니다.
Swagger 패널에서 API 작업을 확인합니다. Swagger 패널에서 코드 보기를 클릭하여 편집 탭에서 YAML 파일을 엽니다.

로컬에 저장된 API 사양 수정

로컬에 저장된 API 사양을 수정하려면 Cloud Code에서 API 사양 파일을 엽니다. 사양을 수동으로 업데이트하거나 Gemini Code Assist 채팅을 사용하여 사양을 반복할 수 있습니다.

Gemini Code Assist 채팅을 사용하여 API 사양 반복

Gemini Code Assist 채팅을 사용하여 기존 API 사양을 변경할 수 있습니다.

API 허브의 API 사양 또는 로컬 API 사양 파일에 대한 안내에 따라 사양 파일을 Cloud Code에 로드합니다.
사양이 포함된 YAML 파일이 편집기에서 현재 활성 탭인지 확인합니다.
Gemini Code Assist 채팅 창에서 Apigee 핸들 @Apigee를 입력하고 Apigee 도구를 선택합니다.
사양 업데이트 프롬프트를 입력합니다. 자세한 내용은 효과적인 API 사양 프롬프트 작성을 참고하세요.
필요한 경우 모의 서버를 사용하여 API를 테스트합니다.
새 API를 API 허브 카탈로그에 저장하려면 API 허브에 API 게시를 참고하세요.
이 사양에서 Apigee API 프록시 번들을 만들려면 API 프록시 번들로 저장을 참고하세요.

API 허브에 API 게시

API 허브를 사용하는 경우 API를 다른 개발자에게 등록하여 API를 제공할 수 있습니다.

새 API 사양 또는 수정된 API 사양의 Swagger 패널에서 API 허브에 게시를 클릭합니다.
양식에 API의 메타데이터를 제공하여 API 허브 카탈로그 내 API의 검색 가능성 및 구성을 개선합니다. 대부분의 필드는 API 사양에서 자동으로 채워지지만 값을 변경할 수 있습니다. API 허브에 등록하는 방법과 제공해야 하는 정보는 API 등록을 참고하세요.
- API 표시 이름(필수): 다른 개발자에게 표시되는 API의 이름입니다.
- API 설명(선택사항): 내부/개발자 참조용 API에 대한 설명입니다.
- API 소유자 이름(선택사항): API 소유자의 이름입니다.
- API 소유자 이메일(선택사항): 소유자의 이메일 주소입니다.
- API 버전(필수): API 버전입니다.
- 수명 주기 단계(선택사항): 목록에서 단계를 선택합니다.
게시를 클릭하여 API를 API 허브에 게시합니다.
잠시 후 Cloud Code의 Apigee 섹션에 있는 API 허브 트리에 변경사항이 표시됩니다.

모의 서버를 사용하여 API 테스트

로컬 모의 서버 또는 Google Cloud기반 원격 모의 서버를 사용하여 API를 테스트할 수 있습니다. 로컬 모의 서버는 기본으로 설치 및 제공되지만, Google Cloud 모의 서버는 직접 설정하고 관리해야 합니다.

로컬 모의 서버 사용

로컬 모의 서버는 이 API에 대한 요청을 수락하고 응답을 에뮬레이션합니다. 현재 사용자의 현재 세션 중에만 사용할 수 있습니다. 그러나 원격 모의 서버와는 달리 설정이나 관리가 필요 없고 비용도 발생하지 않습니다.

또한 로컬 모의 서버는 다음을 충족해야 합니다.

Cloud Shell 편집기 또는 Cloud Workstations를 사용할 때는 작업하지 마세요.
VS Code 원격 탐색기를 사용할 때 제대로 작동하지 않을 수 있습니다.

로컬 모의 서버를 사용하는 방법은 다음과 같습니다.

(아직 선택하지 않은 경우) 서버 드롭다운에서 로컬 모의 서버를 선택합니다.
Swagger 패널에서 경로를 열고 사용해 보기를 클릭합니다.
요청 매개변수를 입력하고 실행을 클릭합니다.

원격 모의 서버 사용

원격 모의 서버는 로컬 모의 서버와 달리 조직 내 다른 사용자와 공유하거나 새 API를 테스트하는 데 사용할 수 있는 영구 모의 서버 인스턴스를 만드는 기능을 제공합니다. 원격 모의 서버는 API 허브에 등록된 API에서만 사용할 수 있습니다.

모의 서버를 배포한 후에는 API를 변경해도 원격 모의 서버가 자동으로 업데이트되지 않으므로, API 생성을 완료할 때까지 기다렸다가 모의 서버를 추가합니다.

Google Cloud 원격 모의 서버를 배포하면 새 Cloud Run 서비스가 생성됩니다. Cloud Build를 사용하여 모의 서버를 위한 컨테이너 이미지를 빌드하고 Google 프로젝트의 Cloud Artifact Registry에 이를 업로드합니다. 자세한 내용은 Cloud Run이란 무엇인가요?, 서비스 관리, Artifact Registry 참고 문서를 확인하세요.

기본 서비스 계정을 사용하거나 Cloud Run 애플리케이션을 배포할 더 제한된 서비스 계정을 제공할 수 있습니다. 자세한 내용은 VS Code용 Cloud Code에서 Cloud API 및 Cloud 클라이언트 라이브러리 관리를 참고하세요.

원격 모의 서버를 배포하려면 다음 단계를 따르세요.

Swagger 패널에서 모의 서버 배포를 선택합니다.
메시지가 표시되면, 아직 API 허브에 등록되지 않은 API를 등록합니다.
서버 이름, 보안 서버, 서비스 계정(기본 서비스 계정을 사용하려면 비워둠), 서버 URL을 API 사양에 추가할지 여부 등 원격 모의 서버의 세부정보를 지정합니다. 만들기를 클릭하여 원격 모의 서버를 만듭니다.
중요: 현재 사용자 인터페이스에서 가능하더라도 같은 이름으로 원격 모의 서버를 여러 개 만들지 마세요.
원격 모의 서버를 생성하는 데 몇 분 정도 걸립니다. Cloud Code 출력 패널과 VS Code 오른쪽 하단에 표시되는 알림 팝업에서 진행 상황을 확인할 수 있습니다.
원격 모의 서버 생성 절차가 완료되면 Swagger 패널 서버 목록과 출력 패널에 원격 서버 URL이 표시됩니다.
모의 서버를 사용하려면 경로를 열고 사용해 보기를 클릭합니다.

요청 파라미터를 입력하고 실행을 클릭합니다.

프롬프트에서 curl을 사용하여 요청을 제출할 수도 있습니다. 서버 드롭다운에 있는 서버 주소와 포트를 사용합니다.

모의 서버에 대한 액세스 권한을 다른 사용자와 공유하려면 다음 안내를 따르세요.

다른 사용자에게 배포된 서비스의 호출자 역할을 부여합니다. 개발자 인증을 참조하세요.
사용자가 모의 서버에 요청을 보낼 경우 비공개 서비스 테스트의 안내를 따릅니다.

배포된 원격 모의 서버를 관리하려면 다음 단계를 따르세요.

Apigee API 허브로 이동
API를 찾아 API의 모든 배포를 확인합니다. 여기에는 원격 모의 서버가 포함됩니다.
리소스 URL을 사용하여 배포로 이동하고 모의 서버에서 중지, 삭제, 기타 작업을 수행하여 배포를 관리합니다.

API를 API 프록시 번들로 저장

API를 Apigee API 프록시 번들로 저장하여 Apigee 로컬 개발 환경에서 작업할 수 있습니다. Cloud Code에서 API 프록시 작업에 대한 자세한 내용은 API 프록시 개발을 참조하세요.

Swagger 패널에서 API 프록시 번들 만들기를 클릭합니다.
프롬프트 필드에서 API 프록시 이름을 지정하고 계속 진행합니다.
API 프록시가 로컬 작업공간의 Apigee 왼쪽 메뉴에 apiproxies 아래에 표시됩니다.

사양 생성에 엔터프라이즈 컨텍스트 제어

OAS 생성에는 조직의 다른 API에서 가져온 스키마, 메타데이터, 보안 정의가 포함될 수 있습니다. 이 프로세스는 객체 이름과 설명을 사용하여 유사한 API를 찾습니다. API 허브 API의 배포 상태는 고려되지 않습니다.

엔터프라이즈 컨텍스트는 기본적으로 사용 설정되어 있습니다.

새로운 사양 생성에서 엔터프라이즈 컨텍스트를 사용 중지하려면 settings.json 파일에서 "cloudcode.apigee.gemini.enable": true 뒤에 다음 줄을 추가합니다.

"cloudcode.apigee.gemini.options": {
         "enterpriseContext": {
           "enabled": false,
           "includeMetadata": false,
           "includeSchema": false,
           "includeSecurity": false
         }
     }

각 항목의 의미:

enabled는 엔터프라이즈 컨텍스트가 전반적으로 사용 설정되는지 여부를 지정합니다. 엔터프라이즈 컨텍스트를 사용 중지하려면 false로 설정합니다.
includeMetadata는 메타데이터 컨텍스트 포함 여부를 제어합니다. 이 설정은 API 허브의 다른 API에 있는 메타데이터를 포함하거나 제외합니다. includeMetadata는 enabled가 true로 설정된 경우에만 적용됩니다.
includeSchema는 스키마 컨텍스트 포함 여부를 제어합니다. 이 설정은 API 허브의 다른 API에 있는 스키마 정보를 포함하거나 제외합니다. includeSchema는 enabled가 true로 설정된 경우에만 적용됩니다.
includeSecurity는 보안 관련 컨텍스트 포함 여부를 제어합니다. 이 설정은 API 허브의 다른 API에 있는 보안 정보를 포함하거나 제외합니다. includeSecurity는 enabled가 true로 설정된 경우에만 적용됩니다.