이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.
Apigee Edge 문서 보기
이 페이지에서는 Apigee 기능 템플릿의 YAML 형식(template, feature, proxy 문서 유형 및 모든 필드)을 설명합니다. 개념적 소개는 YAML로 프록시 구성을 참고하세요. 자세한 내용은 YAML 템플릿에서 API 프록시 만들기를 참고하세요.
규칙
- 필드 이름은 camelCase를 사용합니다. 예를 들어
schemaVersion,basePath,displayName,faultRules,defaultFaultRule,httpTargetConnection입니다. - 스키마가 엄격합니다. 알 수 없는 필드로 인해 파일을 가져올 때 오류가 발생합니다.
- 필수 입력란 파일이 파싱될 때
gateway및schemaVersion만 검증됩니다. 다음 표에서 예로 표시된 다른 필드는 실제로 작동하는 API 프록시를 생성하는 데 필요합니다.
일반 최상위 필드
모든 template, feature, proxy 문서는 다음 필드로 시작합니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
gateway |
타겟 게이트웨이입니다. apigee이어야 합니다. |
해당 사항 없음 | 예 |
schemaVersion |
문서의 스키마 버전입니다. 1.0.0이어야 합니다. |
해당 사항 없음 | 예 |
name |
문서 이름입니다. 템플릿 또는 프록시의 경우 번들에 작성된 API 프록시 이름입니다. | 해당 사항 없음 | 예 |
type |
문서 유형: template, feature 또는 proxy |
해당 사항 없음 | 예 |
description |
사람이 읽을 수 있는 설명입니다. | 해당 사항 없음 | 아니요 |
priority |
컴파일 중에 기능이 적용되는 순서를 제어하는 정수입니다. 번호가 낮은 규칙부터 적용됩니다. | 100 |
아니요 |
문서 유형: 템플릿
템플릿은 가져오는 진입점입니다. 기능을 구성하고 프록시의 엔드포인트와 경로를 정의합니다. 템플릿에는 정책이나 리소스가 포함되지 않습니다. 이러한 항목은 템플릿이 참조하는 기능에서 가져옵니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
features |
프록시에 구성할 기능 파일 이름 목록입니다. 각 이름은 템플릿과 동일한 디렉터리의 파일로 확인되어야 합니다. | [] |
아니요 |
parameters |
특성에 기본값을 제공하는 매개변수 값의 목록입니다. | [] |
아니요 |
endpoints |
기본 경로와 경로를 정의하는 엔드포인트 목록입니다. | [] |
아니요 |
targets |
백엔드 연결을 정의하는 타겟 목록입니다. | [] |
아니요 |
문서 유형: 기능
기능은 템플릿에 포함하는 재사용 가능한 구성 단위입니다. 기능은 정책과 리소스를 보유하며 컴파일된 프록시에 흐름, 엔드포인트, 타겟을 제공할 수 있습니다. 일반 최상위 필드 외에도 기능에는 다음 필드가 있습니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
displayName |
사람이 읽을 수 있는 표시 이름입니다. | 해당 사항 없음 | 아니요 |
uid |
기능의 정책과 리소스에 네임스페이스를 지정하는 데 사용되는 고유 식별자입니다. 설정하지 않으면 name이 사용됩니다. |
해당 사항 없음 | 아니요 |
documentation |
기능에 관한 문서가 확장되었습니다. | 해당 사항 없음 | 아니요 |
categories |
자유 형식 카테고리 라벨 목록입니다. | [] |
아니요 |
parameters |
기능에서 정의하는 매개변수 목록입니다. | [] |
아니요 |
defaultEndpoint |
흐름과 기본 오류 규칙이 컴파일된 프록시의 모든 엔드포인트로 병합되는 프록시 엔드포인트 기능의 정책을 요청 또는 응답 흐름에 연결하는 데 사용합니다. | 해당 사항 없음 | 아니요 |
defaultTarget |
기본 백엔드 연결로 사용되는 프록시 타겟 | 해당 사항 없음 | 아니요 |
endpoints |
프록시에 추가할 프록시 엔드포인트 목록입니다. 기존 엔드포인트와 이름이 동일한 엔드포인트로 대체됩니다. | [] |
아니요 |
targets |
프록시에 추가할 프록시 타겟 목록입니다. 기존 타겟과 이름이 동일한 타겟으로 대체됩니다. | [] |
아니요 |
policies |
기능에서 제공하는 정책 목록입니다. 정책 이름에는 컴파일 중에 기능의 uid (또는 name)이 자동으로 접두사로 추가됩니다. |
[] |
아니요 |
resources |
기능에서 제공하는 리소스 목록입니다(예: JavaScript 또는 속성 파일). | [] |
아니요 |
문서 유형: 프록시
프록시는 CLI가 기능이 있는 템플릿을 컴파일할 때 생성하는 완전히 해결된 문서입니다. 일반적으로 이 유형을 직접 작성하지는 않습니다. API 프록시 번들이 되는 모양이므로 여기에서 설명합니다.
프록시는 endpoints 및 targets (defaultEndpoint 또는 defaultTarget 아님)를 사용하고 항상 완전하고 배포 가능한 프록시를 나타낸다는 점을 제외하고 기능과 동일한 필드를 갖습니다. type은 proxy입니다.
중첩된 객체
parameter
매개변수는 기능에 값을 제공합니다. 매개변수의 값은 default로 확인됩니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
name |
매개변수 이름입니다. 기능 콘텐츠에서 {name}로 참조됩니다. |
해당 사항 없음 | 예 |
displayName |
사람이 읽을 수 있는 이름입니다. | 해당 사항 없음 | 아니요 |
description |
매개변수에 대한 설명입니다. | 해당 사항 없음 | 아니요 |
default |
기본값입니다. 기능의 문자열에서 {name}로 대체되었습니다. |
해당 사항 없음 | 아니요 |
examples |
예시 값 목록입니다. | [] |
아니요 |
maps |
값 대체 맵입니다. 확인된 값이 맵의 키인 경우 매핑된 값으로 대체됩니다. | 해당 사항 없음 | 아니요 |
paths |
JSONPath 표현식 목록입니다. 이 출시 버전에서 지원되지 않음: 사용하면 오류가 발생합니다. | 해당 사항 없음 | 아니요 |
endpoint
템플릿의 endpoints 목록에서 사용됩니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
name |
엔드포인트 이름입니다. | 해당 사항 없음 | 예 |
basePath |
클라이언트가 프록시를 호출하는 데 사용하는 기본 경로입니다(예: /v1/gemini). |
해당 사항 없음 | 아니요 |
routes |
요청을 타겟에 매핑하는 경로 목록입니다. | [] |
아니요 |
proxyEndpoint
기능의 defaultEndpoint 및 endpoints, 컴파일된 프록시에 사용됩니다. 흐름 처리로 엔드포인트를 확장합니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
flows |
흐름 목록입니다. PreFlow 또는 PostFlow라는 이름의 흐름은 해당 Apigee 흐름에 매핑됩니다. 다른 이름은 일반 흐름 컨테이너에 배치됩니다. |
[] |
아니요 |
postClientFlow |
응답이 클라이언트로 전송된 후 실행되는 단일 흐름 | 해당 사항 없음 | 아니요 |
faultRules |
오류 규칙으로 사용되는 흐름 목록입니다. | [] |
아니요 |
defaultFaultRule |
일치하는 다른 오류 규칙이 없을 때 실행되는 오류 규칙입니다. | 해당 사항 없음 | 아니요 |
경로
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
name |
경로 이름입니다. | 해당 사항 없음 | 예 |
target |
라우팅할 대상 엔드포인트의 이름입니다. | 해당 사항 없음 | 아니요 |
condition |
이 경로가 적용되려면 참이어야 하는 조건입니다. | 해당 사항 없음 | 아니요 |
몰입
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
name |
흐름 이름입니다. 표준 요청/응답 흐름에는 PreFlow 또는 PostFlow을 사용합니다. |
해당 사항 없음 | 예 |
mode |
Request 또는 Response. 단계가 요청에서 실행되는지 아니면 응답에서 실행되는지 결정합니다. |
Request |
아니요 |
condition |
흐름이 실행되려면 참이어야 하는 조건입니다. | 해당 사항 없음 | 아니요 |
steps |
단계 (정책 호출)의 순서가 지정된 목록입니다. | [] |
아니요 |
단계
단계는 흐름 내에서 정책을 실행합니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
name |
실행할 정책의 이름입니다. 기능 내에서는 정책의 로컬 이름을 사용합니다. 컴파일러가 네임스페이스 이름으로 다시 작성합니다. | 해당 사항 없음 | 예 |
condition |
단계가 실행되려면 참이어야 하는 조건입니다. | 해당 사항 없음 | 아니요 |
faultRule
하나의 추가 필드로 흐름을 확장합니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
alwaysEnforce |
true인 경우 기본 오류 규칙이 항상 적용됩니다. |
false |
아니요 |
대상
템플릿의 targets 목록에서 사용됩니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
name |
타겟 이름입니다. 경로의 target에 의해 참조됩니다. |
해당 사항 없음 | 예 |
url |
백엔드 URL입니다. | 해당 사항 없음 | 아니요 |
auth |
Google Cloud 백엔드의 인증 스킴입니다(예: GoogleAccessToken 또는 GoogleIDToken). |
해당 사항 없음 | 아니요 |
scopes |
요청할 OAuth 범위 목록입니다. auth이 설정된 경우에 적용됩니다. |
[] |
아니요 |
aud |
토큰의 대상입니다. auth이 설정된 경우에 적용됩니다. |
해당 사항 없음 | 아니요 |
proxyTarget
기능의 defaultTarget 및 targets, 컴파일된 프록시에서 사용됩니다. 흐름 처리 및 원시 연결 재정의로 타겟을 확장합니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
flows |
타겟 요청 또는 응답에서 실행되는 흐름 목록입니다. | [] |
아니요 |
faultRules |
오류 규칙으로 사용되는 흐름 목록입니다. | [] |
아니요 |
defaultFaultRule |
오류 규칙 | 해당 사항 없음 | 아니요 |
httpTargetConnection |
고급 구성을 위한 HTTPTargetConnection 요소의 원시 표현입니다. 설정된 경우 url, auth, scopes, aud보다 우선합니다. |
해당 사항 없음 | 아니요 |
localTargetConnection |
LocalTargetConnection 요소의 원시 표현입니다.
설정된 경우 HTTP 연결보다 우선합니다. |
해당 사항 없음 | 아니요 |
정책
정책은 기능에 정의되어 있습니다. 이 구성은 정책 콘텐츠 규칙에 설명된 속성/텍스트 규칙을 사용하여 content 아래에 작성됩니다.
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
name |
정책 이름입니다. | 해당 사항 없음 | 예 |
type |
Apigee 정책 유형입니다(예: VerifyAPIKey, SpikeArrest, Javascript). content의 단일 최상위 키와 일치해야 합니다. |
해당 사항 없음 | 예 |
content |
하나의 키가 type인 단일 키 사전입니다. 중첩된 값은 아래 규칙을 사용하여 정책의 XML을 설명합니다. |
{} |
예 |
정책 콘텐츠 규칙
Apigee 정책은 XML입니다. YAML에서 다음 규칙을 사용하여 content의 XML을 나타냅니다.
content사전에는 키가 정확히 하나 있으며, 이 키는 정책의type와 일치해야 합니다.- 요소 속성은
metadata키 아래에 있습니다. - 요소 텍스트는
_text키 아래에 있습니다. 예를 들어<Foo bar="baz">qux</Foo>은Foo: {metadata: {bar: "baz"}, _text: "qux"}이 됩니다. 요소에 텍스트만 있고 속성이 없는 경우 텍스트를 값으로 직접 작성할 수 있습니다. - 하위 요소는 태그 이름 아래에 중첩됩니다. 반복되는 태그는 목록이 됩니다.
예를 들어 다음 기능 정책은
policies: - name: VA-VerifyAPIKey type: VerifyAPIKey content: VerifyAPIKey: metadata: name: VA-VerifyAPIKey enabled: "true" continueOnError: "false" DisplayName: VA-VerifyAPIKey APIKey: metadata: ref: request.header.x-api-key
다음 정책 XML로 컴파일됩니다.
<VerifyAPIKey continueOnError="false" enabled="true" name="verify-api-key-VA-VerifyAPIKey"> <APIKey ref="request.header.x-api-key"></APIKey> <DisplayName>VA-VerifyAPIKey</DisplayName> </VerifyAPIKey>
리소스
리소스는 기능이 번들에 제공하는 파일입니다(예: JavaScript 파일 또는 속성 파일).
| 이름 | 설명 | 기본값 | 필수 여부 |
|---|---|---|---|
name |
파일 이름(예: hello-world.js) 컴파일 중에 리소스 이름에 기능의 uid (또는 name)이 접두사로 붙습니다. |
해당 사항 없음 | 예 |
type |
번들의 하위 디렉터리를 결정하는 리소스 유형입니다(예: jsc(JavaScript) 또는 properties). |
해당 사항 없음 | 예 |
content |
원시 파일 콘텐츠입니다. | 해당 사항 없음 | 아니요 |
이 출시에서 지원되지 않는 필드
- 매개변수의
paths(JSONPath) 이 값을 사용하면 컴파일이 실패합니다. tests을 클릭합니다. 이 필드는 허용되지만 무시되며 생성된 번들에 포함되지 않습니다.
한도
생성된 API 프록시 번들은 압축되지 않은 상태에서 10MiB 또는 256개 파일을 초과해서는 안 됩니다.