API 설계 및 수정

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

Apigee Edge 문서 보기

이 페이지의 안내에 따라 Cloud Code를 사용하여 API를 설계하고 수정하세요.

API 설계에 필요한 추가 역할

이 페이지에 설명된 일부 API 설계 단계와 테스트 단계를 수행하려면 아래에 나열된 역할이 필요합니다.

작업	필요한 역할
Gemini Code Assist를 사용하여 API 설계	Google Cloud를 위한 Gemini 사용자 서비스 사용량 소비자 Gemini Code Assist의 Google Cloud 프로젝트에서 IAM 역할 부여를 참조하세요.
API를 설계할 때 API 허브의 기존 API에서 엔터프라이즈 컨텍스트 사용	Cloud API Hub 뷰어
API 허브에 새 API 등록	Cloud API 허브 편집자 또는 관리자
Cloud Code에서 API 허브 API 수정	Cloud API 허브 편집자 또는 관리자
API를 테스트하도록 원격 모의 서버 설정 및 관리	Artifact Registry 관리자 Cloud Build 서비스 계정 Cloud Run 관리자 서비스 사용량 관리자 IAM 기본 및 사전 정의된 역할 참조를 확인하세요.

Gemini Code Assist로 API 설계

미리보기 — Gemini Code Assist

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

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

이 섹션의 기능을 사용하기 위한 설정 단계는 Gemini Code Assist 사용을 참조하세요.

참고: 현재 Gemini Code Assist는 새 객체를 기존 객체와 결합하는 API 설계를 지원합니다(엔터프라이즈 컨텍스트가 사용 설정된 경우). 새 객체를 만들지 않고 객체 재사용만 하는 시나리오는 지원하지 않습니다.

API 생성

API를 생성하려면 다음 단계를 수행합니다.

1. 왼쪽 탐색 메뉴에서 마법 지팡이를 클릭하여 Gemini Code Assist를 사용해 새로운 API 사양을 만듭니다. API 사양을 만들 때 전체 기능을 완전히 지원하지 않는 Gemini Code Assist 채팅 대신 이 방법을 사용하여 API 사양을 만들어야 합니다.
   
2. API 사양 만들기 입력 창에 새 API를 설명하는 프롬프트를 입력합니다.
   1. 원하는 경우 표시된 템플릿 칩에서 프롬프트 템플릿을 선택합니다. 프롬프트 템플릿은 작업을 시작하는 데 도움이 되는 프롬프트 프레임워크를 제공합니다.
   2. 프롬프트를 입력합니다. 효과적인 API 사양 프롬프트를 작성하는 방법을 참조하세요.
      
      
3. Gemini Code Assist는 API를 정의하는 OAS를 생성합니다.
4. 사양을 검토합니다.
   1. 코드 보기를 클릭하여 코드 편집기에서 사양을 검토합니다.
   2. API 렌더러 패널은 API 설명 및 기타 문서를 포함하여 개발자가 검토할 수 있도록 API 미리보기를 표시합니다.
   3. API 허브에 API가 이미 있는 경우 해당 엔터프라이즈 컨텍스트는 다른 API의 객체를 이 OAS에 재사용하는 데 사용되며 OUTPUT 패널에 나열됩니다.
      
   4. 의견을 보내주셔서 감사합니다. Swagger 패널에서 좋아요 또는 싫어요 아이콘을 클릭하여 생성된 사양에 대한 의견을 알려주세요.
      
   5. 미리보기 프롬프트를 수정하고 사양을 다시 생성하려면 프롬프트 위에서 프롬프트 기록 화살표를 클릭하여 이전 프롬프트 사이로 이동합니다.
      
5. 사양을 테스트합니다. 새 사양이 완료되면 모의 서버를 사용하여 테스트할 수 있습니다. 모의 서버를 사용하여 API 테스트를 참조하세요.
6. 저장을 클릭하여 새로운 API를 선택한 이름으로 저장합니다.
7. 이 사양에서 Apigee API 프록시를 만들려면 더보기 메뉴에서 API 프록시 만들기를 클릭합니다. 이 과정에서 프록시 번들이 생성됩니다. 프록시의 왼쪽 메뉴 목록에 새 프록시가 표시됩니다. Cloud Code에서 프록시를 만드는 방법에 대한 자세한 내용은 Cloud Code에 통합된 API 프록시 만들기 둘러보기를 참조하세요.
   

효과적인 API 사양 프롬프트를 작성하는 방법

생성된 API 사양의 정확성과 적합성은 모델에 제공된 프롬프트에 크게 좌우됩니다.

다음은 좋은 프롬프트의 예시입니다.

• 고객이 신용카드, 체크카드 등의 다양한 결제 수단을 사용하여 주문 금액을 결제할 수 있는 API를 만들어줘.
• API를 통해 커피 원두 구매 주문을 받고 싶어.
• 우리는 피자 회사이고 맞춤설정된 온라인 피자 배달 솔루션을 만들려고 해. 피자 주문을 접수할 수 있는 API를 만들어줘.
• 음식 배달 비즈니스용 API입니다. 고객은 피자, 버거 또는 샌드위치를 한 번에 주문할 수 있습니다. 이러한 각 음식 유형에는 고유한 스키마가 있습니다. 피자에는 토핑과 크기가 있습니다. 버거에는 토핑과 패티 유형이 있습니다. 샌드위치에는 빵 종류, 고기 종류, 야채, 치즈, 고객 요청사항이 있습니다.

이 예시에서는 덜 효과적인 프롬프트를 보여줍니다. 이렇게 구성된 프롬프트는 피하는 것이 좋습니다.

• 내 가게에 사용할 API를 만들어줘. 프롬프트에 포함된 정보가 너무 적어 모델이 완전하고 정확한 사양을 생성하기 어렵습니다.
• 주문 객체를 재사용하는 새로운 환불 API를 만들어줘. 새 API를 만들 때 Gemini Code Assist에서 어떤 객체를 재사용할지 지정할 필요가 없습니다. 재사용하기에 가장 적합한 객체를 Gemini Code Assist가 자동으로 감지합니다.

API 허브에 API 등록

API를 검토하고 완료한 후에는 이를 API 허브에 등록하여 개발자에게 제공할 수 있습니다.

1. API 허브에 등록을 클릭합니다.
2. 안내에 따라 API를 등록합니다. API 허브 등록 관련 정보와 제공해야 하는 정보에 대해서는 API 등록을 참조하세요.

Cloud Code에서 API 허브 API 업데이트

Cloud Code에서 API 허브 사양을 수정할 때 API 허브 사양의 새 버전을 저장할 수 있습니다.

사양을 새 버전으로 저장하려면 Swagger 패널에서 옵션 더보기... 버튼을 클릭하고 API 허브에 게시를 클릭합니다. 새 API 버전 ID를 제공합니다. Cloud Code의 API 허브 목록에 있는 해당 API의 버전 목록에 새 버전이 표시됩니다.

설정 파일을 사용하여 Gemini Code Assist 동작 제어

이 섹션에서는 설정 파일에서 Gemini Code Assist 사용 여부 및 제공 방식을 관리하는 방법을 설정합니다.

Gemini Code Assist 사용 중지 또는 사용 설정

Cloud Code에서 Apigee를 설정한 후(Cloud Code에서 Apigee 설정 참조) 설정 파일에 이 줄을 추가하여 모든 Gemini Code Assist 기능을 일시적으로 사용 중지할 수 있습니다.

"cloudcode.apigee.gemini.enable": false

줄을 삭제하거나 true(기본값)로 설정하여 Gemini Code Assist를 다시 사용 설정합니다.

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

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

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

다음과 같은 작업을 할 수 있습니다.

• 엔터프라이즈 컨텍스트에서 Swagger 패널에 포함된 수정사항(있는 경우) 수를 확인합니다.
• 출력 패널에 포함된 수정사항을 확인합니다.

새로운 사양 생성에서 엔터프라이즈 컨텍스트를 사용 중지하려면 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로 설정된 경우에만 적용됩니다.

API 수정

Cloud Code를 사용하여 API 허브 카탈로그에 포함된 기존 API를 수정하려면 다음 안내를 따르세요. Cloud Code에서 변경한 내용을 API 허브에 다시 저장할 수 있습니다.

이 안내는 Apigee용 Gemini Code Assist 부가기능을 사용하지 않는 사용자를 대상으로 합니다. API를 설계하고 수정할 때 Gemini Code Assist에서 사용할 수 있는 추가 기능에 대한 자세한 내용은 Gemini Code Assist로 API 설계를 참조하세요.

참고: 현재는 API 허브에 다시 저장된 API 변경사항을 새 버전으로 저장해야 합니다.

API 사양을 수정하는 방법은 다음과 같습니다.

1. Cloud Code에서 선택한 프로젝트가 수정할 API가 포함된 API 허브 카탈로그가 있는 프로젝트인지 확인합니다.
2. 왼쪽 탐색 메뉴에서 API 허브 트리를 펼칩니다.
3. 목록에서 수정할 API 및 버전을 선택합니다.
4. 수정 패널에서 사양을 수정합니다. Swagger 패널에서 API 작업을 볼 수도 있습니다.
5. 필요한 경우 모의 서버를 사용하여 API를 테스트합니다.
6. Swagger 패널의 더보기 버튼을 사용하여 변경사항을 새 버전으로 저장한 후 API 허브에 게시합니다. 메시지가 표시되면 버전을 확인하거나 업데이트하고 변경사항을 API 허브에 다시 저장합니다. Cloud Code의 API 허브 목록에 있는 해당 API의 버전 목록에 새 버전이 표시됩니다.

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

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

로컬 모의 서버 사용

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

참고: VS Code 원격 탐색기를 사용할 경우 로컬 모의 서버가 제대로 작동하지 않을 수 있습니다. 또한 간혹 로컬 모의 서버를 시작할 수 없습니다. 이 경우 드롭다운 목록에 제공되지 않습니다.

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

1. 서버 드롭다운에서 로컬 모의 서버(개발 서버)를 선택합니다.
   
2. 경로를 열고 사용해 보기를 클릭합니다.
   
3. 요청 매개변수를 입력하고 실행을 클릭합니다.
   
4. 프롬프트에서 curl을 사용하여 요청을 제출할 수도 있습니다. 서버 드롭다운에 있는 서버 주소와 포트를 사용합니다.

원격 모의 서버 사용

원격 모의 서버를 사용하면 로컬 모의 서버와 달리 조직 내 다른 사용자와 공유하거나 다른 사용자가 사용할 수 있는 영구 모의 서버 인스턴스를 생성하여 새 API를 프로덕션에 적용하기 전에 먼저 테스트할 수 있습니다. 원격 모의 서버는 API 허브에 등록된 API에서만 사용할 수 있습니다.

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

Google Cloud 원격 모의 서버를 배포하면 새로운 Cloud Run 서비스가 생성됩니다. Cloud Build를 사용하여 모의 서버를 위한 컨테이너 이미지를 빌드하고 Google 프로젝트의 Cloud Artifact Registry에 이를 업로드합니다. 사용자는 생성 후 발생하는 모든 비용을 지불하고 관리를 책임져야 합니다. 더 이상 필요하지 않게 될 경우 삭제할 책임 역시 사용자에게 있습니다. 자세한 내용은 Cloud Run이란 무엇인가요?, 서비스 관리, Artifact Registry 문서를 확인하세요.

중요: Google Cloud 원격 모의 서버를 만든 후에는 사용자가 사용 및 관리, 삭제(더 이상 필요하지 않은 경우)에 따른 모든 비용을 부담해야 합니다. 무료 등급 옵션에 관한 내용을 포함한 가격 책정 정보는 https://cloud.google.com/run/pricing을 확인하세요.

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

1. 더보기 메뉴에서 모의 서버 배포(Google Cloud)를 선택합니다.
2. 메시지가 표시되면, 아직 API 허브에 등록되지 않은 API를 등록합니다.
3. 원격 모의 서버의 세부정보(프로젝트 ID, 서버 이름, 리전)를 지정하고 만들기를 클릭하여 원격 모의 서버를 생성합니다.
   중요: 현재 사용자 인터페이스에서 가능하더라도 같은 이름으로 원격 모의 서버를 여러 개 만들지 마세요.
4. 원격 모의 서버를 생성하는 데 몇 분 정도 걸립니다. Google Cloud 출력 패널에서 진행 상황을 확인할 수 있습니다.
5. 원격 모의 서버 생성이 완료되면 Swagger 패널 서버 목록과 출력 패널에 원격 서버 URL이 표시됩니다.
6. 모의 서버를 사용하려면 경로를 열고 사용해 보기를 클릭합니다.
   
   
   요청 파라미터를 입력하고 실행을 클릭합니다.
   
   
   프롬프트에서 curl을 사용하여 요청을 제출할 수도 있습니다. 서버 드롭다운에 있는 서버 주소와 포트를 사용합니다.

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

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

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

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