이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
기존 XML 프록시 번들을 작성하는 대신 YAML에서 Apigee API 프록시를 정의하고 Google Cloud CLI를 사용하여 배포할 수 있습니다. Apigee 기능 템플릿이라는 YAML 파일에서 프록시의 엔드포인트, 경로, 정책, 백엔드 타겟을 설명하면 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에 업로드하면 새 API 프록시 버전이 생성됩니다.
프록시를 가져온다고 해서 활성화되는 것은 아닙니다. 별도의 단계로 다른 API 프록시와 마찬가지로 버전을 환경에 배포합니다.
YAML template + feature files | gcloud 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 소스로 다시 돌아가는 왕복은 없습니다.