흐름 변수 사용

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

Apigee Edge 문서 보기

흐름 변수는 정책 또는 유틸리티(예: 디버그 도구) 내에서 액세스할 수 있는 객체입니다. 이 API를 사용하면 Apigee에서 처리하는 API 트랜잭션과 관련된 상태를 유지할 수 있습니다.

빠른 시작: 모든 흐름 변수 및 속성의 전체 목록은 흐름 변수 참조를 확인하세요.

동영상

참고: 다음 동영상에서는 Apigee UI의 기본 프록시 편집기를 보여줍니다. Apigee는 동영상에 표시된 기본 버전과 설계가 다른 새 버전의 프록시 편집기를 도입합니다.

다음 동영상에서는 흐름 변수를 소개합니다.

흐름 변수란 무엇인가요?

흐름 변수는 API 프록시 흐름의 컨텍스트 내에서 존재하며 명명된 변수가 소프트웨어 프로그램에서 상태를 추적하는 방식으로 API 트랜잭션의 상태를 추적합니다. 흐름 변수는 다음과 같은 정보를 저장합니다.

• 요청하는 앱에서 전송한 IP 주소, 헤더, URL 경로, 페이로드
• Apigee가 요청을 수신한 날짜 및 시간과 같은 시스템 정보
• 정책을 실행할 때 파생된 데이터. 예를 들어 OAuth 토큰을 검증하는 정책이 실행된 후 Apigee는 요청 애플리케이션의 이름과 같은 정보를 보관하는 흐름 변수를 만듭니다.
• 대상 시스템의 응답에 대한 정보

일부 변수는 Apigee에 내장되어 있으며 API 요청이 수신될 때마다 자동으로 채워집니다. API 트랜잭션 전체에서 사용할 수 있으며, AssignMessage 정책과 같은 정책 또는 자바스크립트 및 자바 코드로 커스텀 변수를 만들 수도 있습니다.

보다시피 변수에는 범위가 있으며 액세스 가능한 위치는 API 프록시 흐름에서 생성된 시점에 따라 달라집니다. 일반적으로 변수가 생성되면 나중에 API 트랜잭션 흐름에서 실행되는 모든 정책 및 코드에 사용할 수 있습니다.

흐름 변수는 어떻게 사용되나요?

흐름 변수는 정책 및 조건부 흐름에서 사용됩니다.

• 정책은 흐름 변수에서 상태를 검색하고 이를 사용하여 작업을 수행할 수 있습니다.

  예를 들어 VerifyJWT 정책은 흐름 변수에서 확인할 토큰을 검색한 다음 이에 대해 확인 과정을 수행할 수 있습니다. 또 다른 예로 자바스크립트 정책은 흐름 변수를 검색하고 이러한 변수에 포함된 데이터를 인코딩할 수 있습니다.

• 조건부 흐름은 흐름 변수를 참조하여 프로그래밍에서 스위치 문이 작동하는 방식과 같이 Apigee를 통해 API의 흐름을 전달할 수 있습니다.

  예를 들어 결함을 반환하는 정책은 특정 흐름 변수가 설정된 경우에만 실행될 수 있습니다.

이러한 각각의 컨텍스트에서 변수가 사용되는 방법의 예시를 살펴보겠습니다.

정책의 흐름 변수

일부 정책은 흐름 변수를 입력으로 받습니다.

예를 들어 다음 AssignMessage 정책은 흐름 변수 client.ip 값을 가져와 My-Client-IP라는 요청 헤더에 입력합니다. 요청 흐름에 추가된 경우 이 정책은 백엔드 대상으로 전달되는 헤더를 설정합니다. 응답 흐름에서 설정되면 헤더가 클라이언트 앱으로 다시 전송됩니다.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="My-Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

또 다른 예시로 할당량 정책이 실행되면 몇 가지 흐름 변수가 정책 관련 값으로 채워집니다. 이러한 변수 중 하나는 ratelimit.my-quota-policy.used.count라고 합니다. 여기서 my-quota-policy는 원하는 할당량 정책의 이름입니다.

나중에 '현재 할당량 수가 최대 50% 아래이며 오전 9시부터 오후 5시 사이인 경우 다른 할당량을 적용합니다'라는 조건부 흐름을 실행할 수 있습니다. 이 조건은 현재 할당량 수 값과 기본 제공 Apigee 변수 중 하나인 system.time이라는 흐름 변수에 따라 달라질 수 있습니다.

조건부 흐름의 흐름 변수

조건부 흐름은 흐름 변수를 평가하고 프록시가 동적으로 작동하도록 합니다. 조건은 일반적으로 흐름, 단계, 라우팅 규칙의 동작을 변경하는 데 사용됩니다.

다음은 프록시 흐름 단계에서 request.verb 변수 값을 평가하는 조건부 흐름입니다. 이 경우 요청 동사가 POST이면 VerifyAPIKey 정책이 실행됩니다. 이는 API 프록시 구성에서 사용되는 일반적인 패턴입니다.

<PreFlow name="PreFlow">
    <Request>
        <Step>
            <Condition>request.verb equals "POST"</Condition>
            <Name>VerifyApiKey</Name>
        </Step>
    </Request>
</PreFlow>

이제 request.verb, client.ip, system.time과 같은 변수가 어디에서 오는지 궁금하실 수 있습니다. 언제 인스턴스화되고 값으로 채워질까요? 변수가 생성된 시기와 사용 가능한 시기를 이해하는 데 도움이 되도록 API 프록시 흐름 시각화를 참조하세요.

자바스크립트 정책으로 호출되는 자바스크립트 코드의 흐름 변수

자바스크립트 정책을 사용하면 API 프록시 흐름의 컨텍스트 내에서 자바스크립트 코드를 실행할 수 있습니다. 이 정책으로 실행되는 자바스크립트는 Apigee 자바스크립트 객체 모델을 사용합니다. 이 모델은 코드가 실행되는 API 프록시 흐름에 연결된 요청, 응답, 컨텍스트 객체에 대한 커스텀 코드 액세스를 제공합니다. 예를 들어 이 코드는 흐름 변수 target.name에서 가져온 값으로 응답 헤더를 설정합니다.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));

자바스크립트를 사용하여 변수를 읽고 설정하는 이 기법은 AssignMessage 정책(이전에 표시됨)으로 수행할 수 있는 작업과 유사합니다. 이는 Apigee에서 동일한 종류의 작업을 수행하는 또 다른 방법입니다. 기억해야 할 점은 자바스크립트 정책에 의해 실행된 자바스크립트는 API 프록시 흐름 내 범위에 존재하는 모든 흐름 변수에 액세스할 수 있다는 것입니다.

API 프록시의 흐름 시각화

흐름 변수 범위를 이해하려면 API 프록시를 통해 메시지가 전달되는 방식을 이해하고 시각화하는 것이 중요합니다. API 프록시는 흐름으로 구성된 일련의 메시지 처리 단계로 구성됩니다. 프록시 흐름의 모든 단계에서 프록시는 사용 가능한 정보를 평가하고 다음에 수행할 작업을 결정합니다. 이 과정에서 프록시는 정책 코드를 실행하거나 조건부 브랜치를 수행할 수 있습니다.

다음 그림은 이러한 흐름 순서를 보여줍니다. 흐름은 ProxyEndpoint 요청, TargetEndpoint 요청, TargetEndpoint응답, ProxyEndpoint 응답이라는 네 가지 주요 세그먼트로 구성됩니다.

이 주제의 나머지 부분을 통해 흐름 변수를 살펴볼 것이므로 이 흐름 구조를 염두에 두세요.

추가 자료 프록시 흐름 구조에 대한 자세한 내용은 흐름 구성을 참조하세요.

프록시 흐름과 관련된 변수 범위

앞에서 설명한 대로 메시지가 프록시를 통해 어떻게 전달되는지 시각화할 수 있게 되면 변수 범위를 이해할 수 있게 됩니다. 범위란 변수가 처음 인스턴스화될 때 프록시 흐름 수명 주기의 지점을 의미합니다.

예를 들어 ProxyEndpoint 요청 세그먼트에 연결된 정책이 있는 경우 정책은 TargetEndpoint 요청 세그먼트로 범위가 지정된 변수에 액세스할 수 없습니다. 그 이유는 흐름의 TargetEndpoint 요청 세그먼트가 아직 실행되지 않았으므로 API 프록시가 해당 범위에서 변수를 채울 기회가 없었기 때문입니다.

다음 표에서는 전체 변수 범위 세트를 나열하고 프록시 흐름에서 사용할 수 있게 되는 시점을 보여줍니다.

참고: 특정 범위 내에서 흐름 변수가 채워지면 프록시 흐름 수명 주기의 나머지를 통해 사용 가능한 상태로 유지됩니다. 아직 범위에 속하지 않은 변수에 액세스하려고 시도하는 경우 오류 또는 NULL 값이 수신됩니다.

변수 범위	이러한 변수가 채워진 위치
프록시 요청	ProxyEndpoint 요청 세그먼트
대상 요청	TargetEndpoint 요청 세그먼트
대상 응답	TargetEndpoint 응답 세그먼트
프록시 응답	ProxyEndpoint 응답 세그먼트
항상 이용 가능	프록시가 요청을 수신하는 즉시. 이러한 변수는 전체 프록시 흐름 수명 주기에서 사용할 수 있습니다.

예를 들어 client.ip라는 기본 제공 Apigee 변수가 있습니다. 이 변수의 범위는 프록시 요청이며 프록시라고 하는 클라이언트의 IP 주소가 자동으로 채워집니다. 이는 요청이 ProxyEndpoint에 처음 도달했을 때 채워지고 전체 프록시 흐름 수명 주기에서 계속 사용할 수 있게 됩니다.

참고: 모든 기본 제공 Apigee 변수의 범위는 흐름 변수 참조에 나열되어 있습니다.

target.url이라는 다른 기본 제공 변수가 있습니다. 이 변수의 범위는 대상 요청입니다. 이는 TargetEndpoint 요청 세그먼트에 백엔드 대상에 전송된 요청 URL로 채워집니다. ProxyEndpoint 요청 세그먼트에서 target.url에 액세스하려고 하면 NULL 값이 수신됩니다. 이 변수가 범위에 속하기 전에 설정하려고 하면 프록시는 오류가 발생시키지도 않으며 변수를 설정하지도 않으며 아무런 작업도 수행하지 않습니다.

참고: 정의되지 않은 변수에 액세스하는 경우 오류를 일으키거나 NULL를 반환하도록 일부 정책을 구성할 수 있습니다. 자세한 내용은 개별 정책 참조 페이지를 확인하세요.

다음은 변수 범위를 어떻게 생각해야 하는지를 보여주는 간단한 예시입니다. 요청 객체의 전체 콘텐츠(헤더, 매개변수, 본문)를 복사하여 응답 페이로드에 할당하여 호출 앱으로 다시 전송한다고 가정하겠습니다. 이 작업에는 AssignMessage 정책을 사용할 수 있습니다. 정책 코드는 다음과 같습니다.

<AssignMessage name="CopyRequestToResponse">
    <AssignTo type="response" createNew="false">response</AssignTo>
    <Copy source="request"/>
</AssignMessage>

이 정책은 단순히 request 객체를 복사하여 response 객체에 할당합니다. 하지만 이 정책은 프록시 흐름의 어느 지점에 위치해야 할까요? 응답 변수의 범위는 대상 응답이므로 TargetEndpoint 응답에 있어야 합니다.

흐름 변수 참조

Apigee의 모든 기본 제공 변수는 점 표기법 이름 지정 규칙을 따릅니다. 이 규칙을 사용하면 변수의 목적을 쉽게 확인할 수 있습니다. 예를 들면 system.time.hour 및 request.content입니다.

권장사항: 커스텀 흐름 변수를 만들 때는 점 표기법 이름 지정 규칙을 사용하는 것이 좋습니다. 마침표를 사용하여 맞춤 변수의 계층 구조를 구성하면 유용할 수 있습니다.

예를 들어 approval.code 및 approval.status는 모두 흐름 내 승인 기능을 참조할 수 있습니다.

Apigee는 관련 변수를 적절하게 정리하기 위해 다양한 프리픽스를 예약합니다. 이러한 프리픽스는 다음과 같습니다.

• request
• response
• system
• target

정책에서 변수를 참조하려면 중괄호로 묶습니다. 예를 들어 다음 AssignMessage 정책은 client.ip 변수의 값을 가져와 Client-IP라는 요청 헤더에 입력합니다.

<AssignMessage name="set-ip-in-header">
    <AssignTo createNew="false" transport="http" type="request">request</AssignTo>
    <Set>
        <Headers>
            <Header name="Client-IP">{client.ip}</Header>
        </Headers>
    </Set>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

조건부 흐름에서는 중괄호가 필요하지 않습니다. 다음 예시 조건은 request.header.accept 변수를 평가합니다.

<Step>
    <Condition>request.header.accept = "application/json"</Condition>
    <Name>XMLToJSON</Name>
</Step>

자바스크립트 및 자바 코드에서 흐름 변수를 참조할 수도 있습니다. 자세한 내용은 다음을 참고하세요.

• 자바스크립트 코드에서 흐름 변수로 작업
• 자바스크립트 정책

흐름 변수의 데이터 유형

흐름 변수의 각 속성에는 문자열, Long, 정수, 불리언, 컬렉션과 같은 잘 정의된 데이터 유형이 있습니다. 흐름 변수 참조에서 데이터 유형을 확인할 수 있습니다. 정책으로 생성된 변수의 경우 데이터 유형 정보에 대한 특정 정책 참조 주제를 참조하세요.

사용자가 직접 만든 변수는 변수가 생성될 때 지정된 유형을 가정하며 허용되는 값 유형에 따라 다릅니다.

정책에서 흐름 변수 사용

많은 정책이 정상 실행의 일부로 흐름 변수를 만듭니다. 정책 참조에는 이러한 정책별 변수가 모두 수록되어 있습니다.

프록시 및 정책을 사용할 때는 정책 참조를 참고하여 어떤 변수가 만들어지고 어떤 용도로 변수가 사용되는지 확인하세요. 예를 들어 할당량 정책은 할당량 수 및 한도, 만료 시간 등에 대한 정보가 포함된 변수 집합을 만듭니다.

일부 정책 변수는 디버깅에 유용합니다. 예를 들어 디버그 도구를 사용하여 프록시 흐름의 특정 인스턴스에 설정된 변수를 확인할 수 있습니다.

ExtractVariables 정책을 사용하면 메시지에서 추출된 데이터로 커스텀 변수를 채울 수 있습니다. 쿼리 매개변수, 헤더, 기타 데이터를 추출할 수 있습니다. 예를 들어 패턴을 사용하여 요청 및 응답 메시지를 파싱하여 메시지에서 특정 데이터를 추출할 수 있습니다.

다음 예시에서 ExtractVariables 정책은 응답 메시지를 파싱하고 응답에서 가져온 특정 데이터를 저장합니다. 정책은 두 개의 커스텀 변수 geocoderesponse.latitude 및 geocoderesponse.longitude를 만들고 값을 할당합니다.

<ExtractVariables name="ParseGeocodingResponse">
  <Source>response</Source>
  <VariablePrefix>geocoderesponse</VariablePrefix>
  <JSONPayload>
    <Variable name="latitude">
      <JSONPath>$.results[0].geometry.location.lat</JSONPath>
    </Variable>
    <Variable name="longitude">
      <JSONPath>$.results[0].geometry.location.lng</JSONPath>
    </Variable>
  </JSONPayload>
</ExtractVariables>

많은 정책이 자동으로 변수를 생성한다는 점에 유의하세요. 이러한 변수는 프록시 흐름 컨텍스트 내에서 액세스할 수 있으며 각 개별 정책 주제의 정책 참조 문서에 설명되어 있습니다.

자바스크립트 코드에서 흐름 변수로 작업

변수는 API 프록시의 컨텍스트에서 실행되는 자바스크립트 코드에서 직접 액세스하고 설정할 수 있습니다. Apigee에서 실행되는 자바스크립트는 Apigee 자바스크립트 객체 모델을 통해 프록시 흐름 변수에 직접 액세스할 수 있습니다.

참고: 자바스크립트 정책을 사용하여 프록시에서 자바스크립트를 호출할 수 있습니다.

자바스크립트 코드의 변수에 액세스하려면 이러한 객체에서 getter/setter 메서드를 호출합니다.

• context
• proxyRequest
• proxyResponse
• targetRequest
• targetResponse

보다시피 이러한 객체 참조는 이전의 API 프록시 흐름 시각화에서 설명된 대로 프록시 흐름 모델의 친숙한 세그먼트에 매핑됩니다.

context 객체는 시스템 변수와 같은 전역에서 사용 가능한 변수에 해당합니다. 예를 들어 context 객체에서 getVariable()을 호출하여 현재 연도를 가져올 수 있습니다.

var year = context.getVariable('system.time.year');

마찬가지로 setVariable()을 호출하여 맞춤 변수의 값 또는 바로 사용할 수 있는 쓰기 가능 변수의 값을 설정할 수 있습니다. 여기에서는 organization.name.myorg라는 맞춤 변수를 만들고 여기에 값을 할당합니다.

var org = context.setVariable('organization.name.myorg', value);

이 변수는 context 객체를 사용하여 생성되므로 모든 흐름 세그먼트에 사용할 수 있습니다(전역 변수를 만드는 것과 기본적으로 동일함).

참고: 흐름 변수 참조는 쓰기 가능한 변수와 읽기 전용 변수를 나타냅니다. 자세한 내용은 자바스크립트 객체 모델을 참조하세요.

JavaCallout 정책으로 실행하는 자바 코드에서 프록시 흐름 변수를 가져오거나 설정할 수도 있습니다.

알아 두어야 할 사항

다음은 흐름 변수에 대해 알아 두어야 할 몇 가지 주요 사항입니다.

• 일부 out-of-the-box 변수는 프록시에 의해 자동으로 인스턴스화되고 채워집니다. 이러한 정보는 흐름 변수 참조에 나와 있습니다.
• 프록시 흐름에서 사용할 수 있는 커스텀 변수를 만들 수 있습니다. AssignMessage 정책 및 자바스크립트 정책과 같은 정책을 사용하여 변수를 만들 수 있습니다.
• 변수에 범위가 있습니다. 예를 들어 첫 번째 프록시가 앱으로부터 요청을 수신하면 일부 변수는 자동으로 채워집니다. 다른 변수는 프록시의 응답 흐름 세그먼트에 채워집니다. 이 응답 변수는 응답 세그먼트가 실행될 때까지 정의되지 않은 상태로 유지됩니다.
• 정책이 실행되면 정책에서 정책별 변수를 생성하고 채울 수 있습니다. 각 정책에 대한 문서에는 이러한 관련된 정책별 변수가 모두 나와 있습니다.
• 조건부 흐름은 일반적으로 하나 이상의 변수를 평가합니다. 조건부 흐름을 만들려면 변수를 이해해야 합니다.
• 많은 정책에서는 변수를 입력 또는 출력으로 사용합니다. 한 정책에서 만든 변수는 나중에 다른 정책에서 사용될 수도 있습니다.

팁: 한 가지 방법 또는 다른 방법으로 변수를 사용하는 여러 가지 샘플이 있습니다. ExtractVariables 정책을 사용하는 항목을 찾아보세요. 이 정책은 프록시 흐름에서 변수를 처리하는 데 일반적으로 사용됩니다.

관련 주제

• API 프록시에 자동으로 채워진 모든 변수는 흐름 변수 참조에 나와 있습니다. 참조에는 각 변수의 유형과 범위도 나와 있습니다.
• 특정 정책에 의해 어떤 변수가 채워지는지 알아보려면 해당 정책의 참조 주제를 확인하세요. 예를 들어 할당량 정책 참조의 흐름 변수를 참조하세요.