FlowCallout 정책

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

Apigee Edge 문서 보기

FlowCallout 정책을 사용하여 API 프록시 또는 다른 공유 흐름에서 공유 흐름을 호출합니다.

공유 흐름에서는 여러 위치에서 런타임 시 재사용할 수 있는 일련의 단계를 만듭니다. 이 단계는 API 프록시 내에서 정책으로 구현됩니다. FlowCallout 정책을 사용하면 API 프록시 및 기타 공유 흐름에서 공유 흐름을 호출할 수 있습니다. 전통적인 프로그래밍 언어의 함수 호출처럼 작동합니다.

• 예를 들어 API 키 확인, OAuth 토큰 검증, 정규 표현식 보호 조치와 같은 보안 기능을 사용하는 공유 흐름을 빌드했다고 가정해 보세요. 이 공유 흐름은 인바운드 요청을 확인하는 방법의 규칙을 나타냅니다. FlowCallout 정책을 사용하면 여러 API 프록시에서 공유 흐름을 호출할 수 있습니다.
• 공유 흐름 내에서 FlowCallout 정책을 구현하여 하나의 공유 흐름을 다른 공유 흐름에서 호출할 수 있습니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

참고: 공유 흐름에 대한 자세한 내용은 재사용 가능한 공유 흐름을 참조하세요. 또한 외부 API 프록시 코드에서 공유 흐름을 호출하여 환경에 배포된 모든 API 프록시에 대한 요청 사전 처리 또는 응답 후 처리를 적용할 수 있습니다. 자세한 내용은 흐름 후크를 사용하여 공유 흐름 연결을 참조하세요.

샘플

공유 흐름에서 API 키 확인

이 예시에서 공유 흐름은 일반적인 보안 관련 작업을 수행하는 데 사용됩니다. 여기서 공유 흐름은 API 키의 유효성을 검사합니다. API 프록시 및 기타 공유 흐름은 FlowCallout 정책을 사용하여 이 공유 흐름을 호출할 수 있습니다.

다음 공유 흐름 정의에는 API 프록시의 FlowCallout 정책에서 공유 흐름이 호출될 때 실행되는 Verify-API-Key 정책이 포함되어 있습니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<SharedFlow name="default">
    <Step>
        <Name>Verify-API-Key</Name>
    </Step>
</SharedFlow>

앞의 공유 흐름의 VerifyAPIKey 정책은 키 값을 검색하고 확인합니다.

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

API 프록시에 사용되는 다음 FlowCallout 정책은 앞의 공유 흐름을 호출하여 API 키를 확인합니다. 여기에 표시되지 않는 verify-apikey-shared 공유 흐름 번들은 APIProxy 번들이 프록시를 구성하는 방식으로 공유 흐름을 구성합니다.

<FlowCallout async="false" continueOnError="false" enabled="true" name="Auth-Flow-Callout">
    <DisplayName>Auth Flow Callout</DisplayName>
    <SharedFlowBundle>verify-apikey-shared</SharedFlowBundle>
</FlowCallout>

공유 흐름에 매개변수 전달

이 예시에서는 FlowCallout 정책의 매개변수를 공유 흐름에 전달하는 방법을 보여줍니다. 여기에서는 FlowCallout 정책은 일반적인 문자열 처리 함수를 수행하도록 설계된 공유 흐름을 호출합니다. 공유 흐름에는 입력을 연결하거나 입력을 소문자로 고치거나 또는 둘 모두에 해당하는 자바스크립트가 포함됩니다. FlowCallout 정책은 문자열 입력, 출력, 입력으로 수행하는 작업을 지정하는 매개변수를 정의합니다.

1. String-Handler FlowCallout 정책은 공유 흐름을 호출하고 공유 흐름의 출력을 저장할 변수 사용할 공유 흐름 작업, 사용할 입력 (여기서는, 문자열 리터럴이지만 흐름 변수일 수도 있음)을 지정하는 매개변수를 지정합니다. Parameter 요소는 런타임을 만들기 위한 변수 이름과 값을 지정합니다. 공유 흐름에서 이러한 변수를 검색하여 자체 코드에 사용할 수 있습니다.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
     <DisplayName>String Handler</DisplayName>
     <Parameters>
       <Parameter name="input">Gladys Kravitz</Parameter>
       <Parameter name="operations">concatenate tolowercase</Parameter>
       <Parameter name="outputVariable">string.handler.output</Parameter>
     </Parameters>
     <SharedFlowBundle>StringHandler</SharedFlowBundle>
   </FlowCallout>

2. 다음 default 공유 흐름에는 공유 흐름이 FlowCallout 정책에서 호출될 때 실행되는 SharedStringFunctions 자바스크립트 정책이 포함되어 있습니다.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <SharedFlow name="default">
     <Step>
       <Name>SharedStringFunctions</Name>
     </Step>
   </SharedFlow>

3. 공유 흐름에서 다음 SharedStringFunctions 자바스크립트 정책은 실행할 코드가 포함된 SharedStringFunctions.js 자바스크립트 파일을 지정합니다.

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="SharedStringFunctions">
     <DisplayName>SharedStringFunctions</DisplayName> <Properties/>
     <ResourceURL>jsc://SharedStringFunctions.js</ResourceURL>
   </Javascript>

4. 다음 자바스크립트 SharedStringFunctions.js은 SharedStringFunctions 자바스크립트 정책에서 실행됩니다. 이 스크립트는 FlowCallout 정책 Parameter 요소에서 생성된 변수에서 값을 검색합니다.

   // Input value from the calling API proxy.
   var handledString = context.getVariable("input");
   // Variable to use for output from this script.
   var outputVariable = context.getVariable("outputVariable");
   // A space-separated list of things to do to the input string.
   // Convert to lower case to handle unintentional capitals in configuration.
   var operation = context.getVariable("operations").toLowerCase();
   
   // If "lowercase" was given as an operation, convert the input to lowercase.
   if (operation.includes("tolowercase")) {
       handledString = handledString.toLowerCase();
   }
   
   // If "concatenate" was given as an operation, concatenate the input.
   if (operation.includes("concatenate")) {
       handledString = handledString.replace(/\s+/g, '');
   }
   // Assign the resulting string to the output variable specified by
   // the calling API proxy.
   context.setVariable(outputVariable, handledString);

5. 실행은 자바스크립트 정책에서 공유 흐름으로, 그런 다음 원래 API 프록시의 FlowCallout 정책으로 다시 이동합니다.

요소 참조

이 정책에 구성할 수 있는 요소와 속성은 다음과 같습니다.

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <SharedFlowBundle>thereferencedsharedflowbundle</SharedFlowBundle>
</FlowCallout>

<FlowCallout> 속성

<FlowCallout async="false" continueOnError="false" enabled="true" name="Flow-Callout-1">

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

속성	설명	기본값	Presence
name	정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.	해당 사항 없음	필수
continueOnError	정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조: 오류 규칙은 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 오류 처리	false	선택사항
enabled	정책을 시행하려면 true로 설정합니다. 정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	true	선택사항
async	이 속성은 지원이 중단되었습니다.	false	지원 중단됨

<DisplayName> 요소

name 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

<DisplayName>Policy Display Name</DisplayName>

기본값	해당 사항 없음 이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
Presence	선택사항
유형	문자열

<SharedFlowBundle> 요소

호출할 공유 흐름의 이름을 지정합니다. 이 요소의 값은 대상 <SharedFlowBundle> 요소의 이름 속성 값과 동일해야 합니다.

<SharedFlowBundle/>

가장 간단한 예시에서 이 요소의 값으로 호출되는 공유 흐름의 이름을 지정합니다. 즉, 이 요소의 값은 공유 흐름의 name 속성 값과 동일해야 합니다.

<SharedFlowBundle>Shared-Flow-Name</SharedFlowBundle>

기본값	해당 사항 없음
Presence	필수
유형	해당 사항 없음

속성

없음.

<Parameter> 요소

이 정책으로 호출한 공유 흐름에 변수로 전달할 매개변수 및 값(또는 값 소스)을 지정합니다.

매개변수를 사용하여 정책에서 호출하는 공유 흐름에 전달해야 하는 값 (또는 값을 포함하는 변수)을 지정할 수 있습니다. 이는 함수 호출에서 매개변수를 지정하는 것과 개념적으로 유사합니다. 함수 매개변수와 마찬가지로 FlowCallout 매개변수의 값은 공유 흐름 호출의 컨텍스트에 따라 다를 수 있습니다.

FlowCallout 매개변수는 공유 흐름이 실행되는 동안에만 표시됩니다.

구문

이 요소는 다음 구문 양식 중 하나와 함께 사용할 수 있습니다. 리터럴 값을 사용할 경우 지정한 값의 형식은 이를 사용하는 코드에 따라 다릅니다.

<!- A literal value in an attribute. --/>
<Parameter name="parameter-name" value='parameter-value' />
<!- A reference to a variable in an attribute. --/>
<Parameter name="parameter-name" ref='source-variable-name' />
<!- A literal value in the element content. --/>
<Parameter name="parameter-name">parameter-value</Parameter>
<!- An reference to an attribute in the element content. --/>
<Parameter name="parameter-name">{source-variable-name}</Parameter>

예

이 String-Handler FlowCallout 정책은 공유 흐름의 출력을 저장할 위치와 사용할 입력을 지정하는 매개변수를 전달합니다. Parameter 요소는 런타임을 만들기 위한 변수의 이름과 값을 지정합니다. 공유 흐름에서 이러한 변수를 검색하여 자체 코드에 사용할 수 있습니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<FlowCallout async="false" continueOnError="false" enabled="true" name="String-Handler">
  <DisplayName>String Handler</DisplayName>
  <Parameters>
    <Parameter name="input">Gladys Kravitz</Parameter>
    <Parameter name="outputVariable">string.handler.output</Parameter>
  </Parameters>
  <SharedFlowBundle>StringHandler</SharedFlowBundle>
</FlowCallout>

기본값	해당 사항 없음
Presence	필수
유형	해당 사항 없음

속성

속성	설명	기본값	Presence	유형
name	이 매개변수로 만들 런타임 변수의 이름입니다.	없음	필수	문자열
ref	런타임 시 사용할 값이 포함된 변수입니다. 사용할 리터럴 값을 지정하는 경우 이 속성을 생략합니다.	없음	선택사항	문자열
value	이 매개변수로 생성된 런타임 변수에 사용할 값입니다. 값 소스로 사용해야 하는 변수의 이름을 지정하는 경우 이 속성을 생략합니다.	없음	선택사항	문자열

<Parameters> 요소

이 정책에서 호출하는 공유 흐름에 변수로 전달할 <Parameter> 요소 집합을 지정합니다.

구문

<Parameters>
  <Parameter name="parameter-name" value='parameter-value' />
</Parameters>

기본값	해당 사항 없음
Presence	선택사항
유형	해당 사항 없음

속성

없음.

스키마

샘플: 최신 스키마는 GitHub 저장소 샘플을 참조하세요.

흐름 변수

흐름 변수를 사용하면 HTTP 헤더, 메시지 콘텐츠 또는 흐름 컨텍스트를 기반으로 런타임 시 정책 및 흐름의 동적 동작을 사용 설정할 수 있습니다. 흐름 변수에 대한 자세한 내용은 변수 참조를 확인하세요.

변수	설명
apigee.edge.sharedflow.name	범위: 공유 흐름을 실행하는 동안 유형: 문자열 권한: 읽기 공유 흐름의 이름 속성 값입니다.
apigee.edge.flowhook.name	범위: 흐름 후크에 연결된 공유 흐름을 실행하는 동안 유형: 문자열 권한: 읽기 흐름 후크의 이름입니다.

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

도움말: 오류를 해결하는 데 도움이 필요하신가요? 해결 열의 를 클릭하여 자세한 문제 해결 정보를 확인합니다.

API 모니터링을 사용하여 오류 코드를 조사하고 문제를 더 빠르게 진단할 수 있습니다.

오류 코드	HTTP 상태	원인	해결
flow.SharedFlowNotFound	500	공유 흐름이 없거나 공유 흐름이 있지만 배포되지 않았습니다.

배포 오류

해당 없음

관련 주제

• 공유 흐름 만들기: 재사용 가능한 공유 흐름
• 여러 프록시에서 공유 흐름 실행: 흐름 후크를 사용하여 공유 흐름 연결