이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
기존 XML 프록시 번들을 작성하는 대신 YAML에서 Apigee API 프록시를 정의하고 Google Cloud CLI로 배포할 수 있습니다. YAML 파일(Apigee 기능 템플릿이라고 함)에서 프록시의 엔드포인트, 경로, 정책, 백엔드 대상을 설명하면 Apigee 에서 이를 표준 API 프록시 번들로 컴파일합니다.
결과는 일반적인 Apigee API 프록시 번들이므로 이 방식으로 빌드하는 프록시는 Apigee UI 또는 XML 번들에서 빌드하는 프록시와 동일한 정책 및 동작으로 동일한 Apigee 런타임에서 실행됩니다.
YAML을 사용하여 프록시를 정의하는 이유
기존 Apigee API 프록시 형식은 XML 파일의 ZIP 보관 파일입니다. YAML은 많은 개발자가 더 빠르게 읽고 쓰고 검토할 수 있으며 AI 지원 및 에이전트 도구와 잘 작동하는 대안을 제공합니다. Apigee 기능 템플릿은 다음과 같은 용도로 설계되었습니다.
- 간결한 선언적 형식을 선호하고 프록시 구성을 소스 제어에 보관하려는API 개발자 및 설계자
- 모델 백엔드 앞에 Apigee 게이트웨이를 배치하는 표준화된 방법을 원하는 AI 전문가
- 재사용 가능한 프록시 구성 부분을 패키징하고 여러 프록시에 일관되게 적용하려는플랫폼 및 DevOps팀
주요 개념
Apigee 기능 템플릿은 세 가지 문서 유형을 사용합니다. 각각은 type 필드로 식별되는 YAML 파일입니다.
| 문서 유형 | type 값 |
목적 |
|---|---|---|
| 템플릿 | template |
배포하는 진입점입니다. 템플릿은 하나 이상의 기능을 구성하고 프록시의 엔드포인트와 경로를 정의합니다. |
| 기능 | feature |
템플릿에 포함하는 재사용 가능한 구성 단위(예: 인증 확인, 비율 제한, 백엔드 대상)입니다. 기능에는 정책과 리소스가 포함됩니다. |
| 프록시 | proxy |
CLI가 기능을 사용하여 템플릿을 컴파일할 때 생성하는 완전히 확인된 프록시입니다. 일반적으로 CLI에서 생성하는 중간 출력이지만 프록시 파일을 직접 가져와 API 프록시 번들로 변환할 수도 있습니다. |
템플릿 과 기능 을 작성합니다. Apigee는 컴파일 중에 프록시 를 생성합니다.
작동 방식
템플릿을 가져오면 Google Cloud CLI가 로컬에서 다음 단계를 실행한 후 결과를 Apigee에 업로드합니다.
- 컴파일. CLI는 템플릿과 참조하는 기능 파일 을 읽고 병합하여 단일 프록시 정의를 생성합니다.
- 변환. CLI는 프록시 정의를 표준 Apigee API 프록시 번들 (Apigee에서 예상하는 XML 파일의 ZIP)로 변환합니다.
- 가져오기. CLI는 번들을 Apigee에 업로드하고 Apigee는 새 API 프록시 버전을 만듭니다.
프록시를 가져온다고 해서 프록시가 활성화되지는 않습니다. 별도의 단계로 다른 API 프록시와 마찬가지로 버전을 환경에 배포 합니다.
YAML template + feature files | gcloud beta apigee apis import --from-template v API proxy revision (created, not yet serving traffic) | gcloud apigee apis deploy v Deployed proxy (serving traffic in an environment)
단계별 안내는 YAML 템플릿에서 API 프록시 만들기를 참조하세요.
간단한 예시
다음 템플릿은 백엔드 대상을 추가하는 기능과 응답 메시지를 추가하는 기능이라는 두 가지 기능을 구성하는 프록시를 정의합니다.
gateway: apigee schemaVersion: 1.0.0 name: HelloWorld-v1 type: template description: API proxy for HelloWorld-v1 features: - proxy-apigeemock.yaml - response-helloworld.yaml
참조된 모든 기능 파일은 템플릿과 동일한 디렉터리에 있어야 합니다. 실행 가능한 전체 예시와 사용하는 기능 파일은 YAML 템플릿에서 API 프록시 만들기를 참조하세요.
취할 수 있는 조치
- YAML에서 프록시의 엔드포인트, 기본 경로, 경로, 흐름, 백엔드 대상을 정의합니다.
- 재사용 가능한 정책과 리소스를 기능으로 패키징하고 템플릿에서 구성합니다.
- Google Cloud 대상에 백엔드 인증을 추가합니다 (예: Vertex AI 백엔드의 Google 액세스 토큰).
- Google Cloud CLI를 사용하여 템플릿을 새 API 프록시 버전으로 가져온 후, 표준 배포 명령어로 배포합니다.
제한사항
템플릿과 기능을 작성할 때는 다음 사항에 유의하세요.
- 기능은 로컬 파일입니다. 템플릿은 동일한 디렉터리에 있는 기능 파일만 참조할 수 있습니다. URL 또는 공유 카탈로그에서 기능을 참조하는 것은 지원되지 않습니다.
- 매개변수 값은 기본값을 사용합니다. 기능은 매개변수를 정의할 수 있지만 매개변수 값은 기능에 정의된 기본값으로 확인됩니다. 가져오기 시 매개변수 값을 재정의하는 명령줄 플래그는 없습니다.
- JSONPath 매개변수는 지원되지 않습니다.
paths(JSONPath) 표현식을 사용하는 매개변수로 인해 컴파일이 실패합니다. - 테스트는 지원되지 않습니다.
tests섹션은 스키마에서 허용되지만 무시되며 생성된 번들에 포함되지 않습니다. - 스키마는 엄격합니다. 알 수 없는 필드로 인해 오류가 발생합니다.
gateway: apigee및schemaVersion: 1.0.0만 지원됩니다. - 문제 해결은 생성된 XML을 사용합니다. Apigee UI 및 런타임은 생성된 번들로 작동합니다. UI에서 YAML 소스로의 왕복은 없습니다.