Apigee Edge 문서입니다.
Apigee X 문서로 이동 정보
모든 애플리케이션 프로그래밍 모델에는 처리 흐름을 제어하는 방법이 포함되어 있습니다. API 프록시에서는 흐름으로 제어됩니다. 로직, 조건문, 오류 처리 등을 흐름에 추가하세요. 흐름을 사용하여 발생하는 작업 및 시기를 제어합니다.
흐름은 API 요청 처리 경로의 순차적 단계입니다. API 키를 확인하려는 목적 등으로 프록시 로직을 추가할 때 흐름에 의해 지정되는 시퀀스에 로직을 단계로 추가합니다. 로직을 실행할지 여부와 언제 실행할지 지정하는 조건을 정의할 때 조건을 흐름에 추가합니다.
다음 흐름 구성 예시에서는 수신 요청 경로가 /로 끝나고 요청의 HTTP 동사가 GET인 경우 VerifyAPIKey 정책이 실행되는 흐름을 정의합니다.
<Flow name="Get Food Carts">
<Description>Get Food Carts</Description>
<Request>
<Step>
<Name>Verify-API-Key</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>
흐름의 <Name> 요소에 있는 Verify-API-Key 값은 다음과 같이 XML이 있는 프록시 다른 곳에 구성된 정책을 포함합니다.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
<DisplayName>Verify API Key</DisplayName>
<Properties/>
<APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>
흐름 실행 시퀀스 설계
처리 경로를 따라 올바른 순서로 로직을 실행할 수 있도록 흐름을 구조화합니다.
로직을 추가할 위치를 결정할 때 먼저 프록시 엔드포인트 또는 대상 엔드포인트에 추가할지 여부를 선택합니다. API 프록시는 프록시의 클라이언트(프록시 엔드포인트)와 상호작용하는 코드 및 프록시의 백엔드 타겟과 상호작용하는 선택적 코드(대상 엔드포인트)를 분할합니다.
두 엔드포인트 모두 여기에 설명된 대로 흐름을 포함합니다.
| 엔드포인트 유형 | 설명 | 지원되는 흐름 |
|---|---|---|
| ProxyEndpoint | 클라이언트와 가장 가까운 API 프록시 흐름을 포함합니다. 클라이언트의 요청에서 먼저 조치를 취한 후 클라이언트에 대한 응답을 마지막으로 처리할 로직의 위치를 제공합니다. | PreFlow, 조건부 흐름, PostFlow, PostClientFlow |
| TargetEndpoint | 백엔드 리소스와 가장 가까운 API 프록시 흐름을 포함합니다. 요청을 준비하는 로직의 장소를 준비한 후 백엔드 리소스의 응답을 처리합니다. | PreFlow, Conditional Flow, PostFlow |
발생해야 하는 작업과 순서를 지정하는 XML을 사용하여 흐름을 구성합니다. 다음 그림은 프록시 엔드포인트와 대상 엔드포인트 내에서 흐름이 순차적으로 정렬되는 방법을 보여줍니다.
프록시 엔드포인트와 대상 엔드포인트에는 다음 시퀀스에 정렬할 수 있는 흐름이 포함됩니다.
| 위치 | 흐름 유형 | 설명 |
|---|---|---|
| 1 | PreFlow |
특정 코드가 다른 작업보다 먼저 실행되어야 하는 경우에 유용합니다. PreFlow가 대상 엔드포인트에 있으면 이는 프록시 엔드포인트의 PostFlow 이후에 실행됩니다. |
| 2 | Conditional Flow |
조건부 로직의 장소이며, PreFlow 이후 PostFlow 전에 실행됩니다.
세그먼트당 하나의 조건부 흐름만 실행되며 이는 조건이 true로 평가되는 첫 번째 흐름입니다. 즉, 다음의 일부로 하나의 조건부 흐름이 실행될 수 있습니다.
|
| 3 | PostFlow |
데이터를 로깅해야 하고 요청을 처리하는 동안 오류가 발생했다는 알림을 보내기 좋은 장소입니다. Conditional Flow 및 PreFlow 실행 후 실행됩니다. PostFlow가 프록시 엔드포인트에 있고 대상 엔드포인트가 있는 경우 프록시 엔드포인트 PostFlow는 대상 엔드포인트 PreFlow보다 먼저 실행됩니다. |
| 4 | PostClientFlow(프록시 흐름만 해당) | 응답이 클라이언트에 반환된 후 메시지를 로깅하는 흐름입니다. |
PreFlow를 통해 코드 먼저 실행
PreFlow는 다른 작업이 발생하기 전에 특정 코드가 실행되어야 경우에 유용합니다.
프록시 엔드포인트에서 PreFlow는 클라이언트를 인증하고 클라이언트의 트래픽을 제한하는 코드에 적합한 장소입니다. 백엔드 대상에게 요청 전송을 시작하는 대상 엔드포인트에서 PreFlow는 요청을 전송하기 위한 첫 번째 단계에 적합합니다.
예를 들어 일반적으로 할당량을 초과한 클라이언트에 대해 서비스를 제공하지는 않습니다. 이러한 요구사항을 지원하려면 PreFlow 세그먼트에 보안 및 할당량 정책을 넣어야 합니다. 이렇게 하면 나중에 조건부 흐름에서 실패하는 조건 평가에 대해 염려하지 않아도 됩니다. 이 흐름의 정책은 항상 다른 처리가 실행되기 전에 실행됩니다.
다음 예시에서 SpikeArrest 및 Quota 정책은 조건부 흐름에 처리가 전달되기 전에 실행됩니다.
<PreFlow name="MyPreFlow">
<Request>
<Step>
<Name>Spike-Arrest</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
</PreFlow>
조건부 흐름을 통해 코드 조건부 실행
PreFlow와 PostFlow 사이에서 조건부로 실행되는 흐름이 있을 수 있습니다. 이렇게 하면 여러 로직 시퀀스를 구성할 수 있지만 프록시 상태에 따라 실행이 하나만 발생합니다. PreFlow 또는 PostFlow에서 모든 로직을 실행할 수 있고 조건이 필요하지 않은 경우(즉, 엔드포인트를 통하는 경로 하나만 지원됨) 조건부 흐름은 선택사항입니다.
각 흐름은 다양한 상태 값을 테스트하는 조건을 지정합니다. 이렇게 하면 조건에 따라 효과적으로 실행을 분기시킬 수 있습니다. 예를 들어 요청하는 앱이 휴대기기에서 실행되는 경우에만 XML을 JSON으로 변환하고자 하는 경우가 있습니다.
여기서 할당량 제약조건은 URI 패턴이 /issue/**(마지막 슬래시 뒤에 URI의 어떠한 내용과 /issue/가 같이 따르는 패턴)인 요청이 GET 요청인 경우에만 적용됩니다.
<Flow name="MyFlow">
<Description/>
<Request>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Response/>
<Condition>(proxy.pathsuffix MatchesPath "/issue/**") and (request.verb = "GET")</Condition>
</Flow>
흐름 변수를 사용하여 조건을 지정합니다. 조건에서 변수의 사용에 대한 자세한 내용은 흐름 변수가 있는 조건을 참조하세요.
조건에서 패턴 일치를 사용하는 예시는 패턴 일치를 참조하세요.
PostFlow를 통해 핵심 로직 이후에 코드 실행
PostFlow는 엔드포인트의 핵심 로직 다음, 그리고 엔드포인트 처리가 완료되기 전에 작업을 수행하는 데 유용합니다. PostFlow는 조건부 흐름 및 PreFlow 후에 실행됩니다.
PostFlow는 일부 데이터를 로깅하고, 오류가 발생했다는 알림을 보내고, 응답 메시지 형식을 변환하는 등의 작업을 수행하기에 적합한 장소입니다.
다음 예시에서 SetResponseHeaders라는 AssignMessage 정책은 Apigee Edge가 응답을 클라이언트에 다시 전송하기 전에 응답 메시지의 헤더를 설정합니다.
<PostFlow>
<Response>
<Step>
<Name>SetResponseHeaders</Name>
</Step>
</Response>
</PostFlow>
PostClientFlow를 통해 클라이언트가 프록시 응답을 받은 후 코드 실행
PostClientFlow에는 다음 정책이 포함될 수 있습니다.
* FlowCallout 정책은 PostClientFlow에 있을 수 있는 기준을 충족하는 공유 흐름만 호출할 수 있습니다(즉, 호환 가능한 정책만 포함됨).
이 중 하나를 포함하면 PostClientFlow는 실행할 마지막 흐름이 되며, 응답 후의 실행은 클라이언트로 전송됩니다.
PostClientFlow는 최종 로깅에 적합합니다. 또한 응답 메시지의 시작 및 종료 타임스탬프를 로깅할 수 있습니다.
다음은 MessageLogging 정책이 연결된 PostClientFlow의 예시입니다.
...
<PostFlow name="PostFlow">
<Request/>
<Response/>
</PostFlow>
<PostClientFlow>
<Request/>
<Response>
<Step>
<Name>Message-Logging-1</Name>
</Step>
</Response>
</PostClientFlow>
...
동영상: 개발자를 위한 4분 동영상 (4MV4D) 시리즈의 MessageLogging 정책을 사용하여 PostClientFlow를 만드는 방법을 보여주는 이 짧은 동영상을 확인하세요.
자세한 내용은 다음을 참고하세요.
흐름에 로직 추가
프록시에 로직을 추가하는 경우 프록시의 흐름에 정책을 추가하여 추가합니다. 흐름이 순차적으로(이 주제에 설명된 대로 PreFlow, Flow, PostFlow) 실행되듯이 흐름의 콘텐츠도 순차적으로 실행됩니다.
다음 흐름 구성 예시에서는 자체 XML 파일의 다른 곳에 구성된 3개의 정책을 참조합니다. Verify-API-Key에서 참조되는 정책은 Remove-API-Key로 참조되는 정책보다 먼저 실행되며, 그런 다음 Quota으로 표시된 정책이 실행됩니다.
<Flow name="Get Food Cart Menus">
<Description>Get Food Cart Menus</Description>
<Request>
<Step>
<Name>Verify-API-Key</Name>
</Step>
<Step>
<Name>Remove-API-Key</Name>
</Step>
<Step>
<Name>Quota</Name>
</Step>
</Request>
<Condition>(proxy.pathsuffix MatchesPath "/") and (request.verb = "GET")</Condition>
</Flow>
Apigee Edge 콘솔은 이 정책 시퀀스를 아이콘의 행으로 표시하며 여기서 각 아이콘은 정책을 나타냅니다.
디버깅 흐름
Apigee Edge Trace 도구는 요청에 따라 API 프록시의 로직이 수행되는 방법을 시각적으로 제공합니다. 이 도구는 요청과 응답 간 처리를 보여줍니다. PreFlow, 조건부 흐름, PostFlow 간의 구분을 구체적으로 설명하지는 않습니다.
프록시 추적에 대한 자세한 내용은 Trace 도구 사용을 참조하세요.
흐름의 오류 처리
흐름을 포함하여 API 프록시의 다양한 위치에서 결함을 발생시킬 수 있습니다.
다음 예시는 대상 엔드포인트에서 PreFlow의 응답 스탠자입니다. 즉, 백엔드 대상으로부터 응답을 받으면 즉시 실행되는 코드입니다. 이 예시에서 대상의 응답이 200(성공)이 아니면 오류가 발생합니다.
<PreFlow name="PreFlow">
<Response>
<Step>
<Name>RaiseFault</Name>
<Condition>(response.status.code GreaterThan "200")</Condition>
</Step>
</Response>
</PreFlow>
오류 처리에 대한 자세한 내용은 오류 처리를 참조하세요.