자바스크립트 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동
정보

내용

이 정책을 사용하면 API 프록시 흐름의 컨텍스트 내에서 실행되는 커스텀 자바스크립트 코드를 추가할 수 있습니다. 커스텀 JavaScript 코드에서 Apigee Edge JavaScript 객체 모델의 객체, 메서드, 속성을 사용할 수 있습니다. 객체 모델을 사용하면 프록시 흐름 컨텍스트에서 변수를 가져오고 설정하고 삭제할 수 있습니다. 객체 모델과 함께 제공되는 기본 암호화 함수를 사용할 수도 있습니다.

정보

자바스크립트 정책에 대한 많은 사용 사례가 있습니다. 예를 들어 흐름 변수를 가져오고 설정하고 맞춤 로직을 실행하고 요청 또는 응답에서 데이터를 추출하고 백엔드 대상 URL을 동적으로 수정하는 등의 작업을 수행할 수 있습니다. 이 정책을 사용하면 다른 표준 Edge 정책에서 다루지 않는 커스텀 동작을 구현할 수 있습니다. 실제로 자바스크립트 정책을 사용하면 다른 정책에 의해 구현된 동일한 동작을 다수 수행할 수 있습니다(예를 들어 AssignMessage 및 ExtractVariable).

자바스크립트 정책에 권장되지 않는 한 가지 사용 사례는 로깅입니다. 메시지 로깅 정책은 Splunk, Sumo, Loggly와 같은 타사 로깅 플랫폼에 로깅하는 데 훨씬 적합하며, 응답이 클라이언트로 다시 전송된 후 실행되는 PostClientFlow에서 메시지 로깅 정책을 실행하여 API 프록시 성능을 개선합니다.

자바스크립트 정책을 사용하면 실행할 자바스크립트 소스 파일을 지정하거나 <Source> 요소를 사용하여 정책 구성에 자바스크립트 코드를 직접 포함할 수 있습니다. 어떤 경우든 자바스크립트 코드는 정책이 연결된 단계가 실행될 때 실행됩니다. 소스 파일 옵션의 경우 소스 코드는 항상 프록시 번들의 표준 위치(apiproxy/resources/jsc)에 저장됩니다. 환경 또는 조직 수준에서 리소스 파일에 소스 코드를 저장할 수도 있습니다. 자세한 내용은 리소스 파일을 참조하세요. Apigee UI 프록시 편집기를 통해 자바스크립트를 업로드할 수도 있습니다.

자바스크립트 소스 파일에는 항상 .js 확장자가 있어야 합니다.

현재 지원되는 JavaScript 버전은 지원되는 소프트웨어 및 지원되는 버전을 참고하세요.

동영상

자바스크립트 정책을 사용하여 맞춤 정책 확장 프로그램을 만드는 방법을 알아보려면 짧은 동영상을 시청하세요.

샘플

대상 URL 재작성

일반적인 사용 사례는 요청 본문에서 데이터를 추출하여 흐름 변수에 저장하고 프록시 흐름의 다른 곳에서 해당 흐름 변수를 사용하는 것입니다. 사용자가 HTML 양식에 사용자 이름을 입력하고 제출하는 앱이 있다고 가정해 보겠습니다. API 프록시가 양식 데이터를 추출하고 백엔드 서비스를 호출하는 데 사용되는 URL에 이를 동적으로 추가하도록 하려고 합니다. 자바스크립트 정책에서 어떻게 수행하나요?

참고: 이 예를 사용해 보려면 프록시 편집기에서 새 프록시를 만들었다고 가정합니다. URL을 만들 때 백엔드 서비스 URL(http://www.example.com)을 제공하기만 하면 됩니다. 이 예시에서는 백엔드 URL을 동적으로 다시 작성해 보겠습니다. 새 프록시를 만드는 방법을 모르는 경우 시작하기 튜토리얼을 참조하세요. .

  1. Edge UI에서 프록시 편집기에서 만든 프록시를 엽니다.
  2. 개발 탭을 선택합니다.
  3. 새로 만들기 메뉴에서 새 스크립트를 선택합니다.
  4. 대화상자에서 자바스크립트를 선택하고 스크립트에 js-example과 같은 이름을 지정합니다.
  5. 코드 편집기에 다음 코드를 붙여넣고 프록시를 저장합니다. 주목해야 할 중요한 사항은 context 객체입니다. 이 객체는 프록시 흐름의 모든 위치에서 모든 자바스크립트 코드에 사용할 수 있습니다. 이는 흐름별 상수를 가져오고, 유용한 get/set 메서드를 호출하고, 더 많은 작업을 처리하는 데 사용됩니다. 이 객체 부분은 Edge의 JavaScript 객체 모델입니다. target.url 흐름 변수는 대상 요청 흐름에서 액세스할 수 있는 기본 제공 읽기/쓰기 변수입니다. API URL로 변수를 설정하면 Edge는 해당 URL에 백엔드를 호출합니다. 기본적으로 프록시를 만들 때 지정한 대로 원래 대상 URL을 다시 작성했습니다(예: http://www.example.com).

    if (context.flow=="PROXY_REQ_FLOW") {
         var username = context.getVariable("request.formparam.user");
         context.setVariable("info.username", username);
    }
    
    
    if (context.flow=="TARGET_REQ_FLOW") {
         context.setVariable("request.verb", "GET");
         var name = context.getVariable("info.username");
         var url = "http://mocktarget.apigee.net/"
         context.setVariable("target.url", url + "?user=" + name);
    }
    
  6. 새 정책 메뉴에서 JavaScript를 선택합니다.
  7. 정책 이름을 지정합니다(예: target-rewrite). 기본값을 수락하고 정책을 저장합니다.
  8. 탐색기에서 프록시 엔드포인트 Preflow를 선택하면 정책이 해당 흐름에 추가된 것을 확인할 수 있습니다.
  9. 탐색기에서 대상 엔드포인트 PreFlow를 선택합니다.
  10. 탐색기에서 자바스크립트 정책을 흐름 편집기의 대상 엔드포인트 요청 쪽으로 드래그합니다.
  11. 저장을 클릭합니다.
  12. 올바른 조직 이름과 프록시 이름으로 적절하게 바꿔 다음과 같이 API를 호출합니다.
curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

마지막으로, 이 예시에서 사용된 자바스크립트 정책의 XML 정의를 살펴보겠습니다. <ResourceURL> 요소가 실행할 자바스크립트 소스 파일을 지정하는 데 사용된다는 점에 유의해야 합니다. 이와 동일한 패턴이 자바스크립트 소스 파일(jsc://filename.js)에 사용됩니다. 자바스크립트 코드에 includes가 필요하다면 이 참조 뒷부분에서 설명하는 <IncludeURL> 요소를 하나 이상 사용합니다.

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

자바스크립트에서 속성 값 검색

구성에 <Property> 요소를 추가하면 이후 런타임에 자바스크립트로 요소의 값을 검색할 수 있습니다.

요소의 name 속성을 사용하여 자바스크립트 코드에서 속성에 액세스하는 데 사용할 이름을 지정합니다. <Property> 요소의 값(여는 태그와 닫는 태그 사이의 값)은 자바스크립트에서 수신하는 리터럴 값입니다.

자바스크립트에서는 다음과 같이 Properties 객체의 속성으로 액세스하여 정책 속성 값을 검색합니다.

  • 속성을 구성합니다. 여기서 속성 값은 변수 이름 response.status.code입니다.
    <Javascript async="false" continueOnError="false" enabled="true" timeLimit="200" name="JavascriptURLRewrite">
        <DisplayName>JavascriptURLRewrite</DisplayName>
        <Properties>
            <Property name="source">response.status.code</Property>
        </Properties>
        <ResourceURL>jsc://JavascriptURLRewrite.js</ResourceURL>
    </Javascript>
    
  • 자바스크립트로 속성을 검색합니다. 여기서 검색된 값(변수 이름)은 getVariable 함수가 변수 값을 검색하는 데 사용됩니다.
    var responseCode = properties.source; // Returns "response.status.code"
    var value = context.getVariable(responseCode); // Get the value of response.status.code
    context.setVariable("response.header.x-target-response-code", value);
    

오류 처리

자바스크립트 콜아웃에서 사용할 수 있는 오류 처리 기법과 예제에 대해서는 Apigee 커뮤니티의 이 게시물을 참조하세요. Apigee 커뮤니티에서 제공하는 제안은 정보 제공만을 목적으로 하며 Apigee에서 추천하는 권장사항을 나타내지는 않습니다.


요소 참조

요소 참조는 자바스크립트 정책의 요소 및 속성을 설명합니다.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Javascript async="false" 
        continueOnError="false" enabled="true" timeLimit="200" 
        name="JavaScript-1">
    <DisplayName>JavaScript 1</DisplayName>
    <Properties>
        <Property name="propName">propertyValue</Property>
    </Properties>
    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
    <IncludeURL>jsc://a-javascript-library-file</IncludeURL>
    <ResourceURL>jsc://my-javascript-source-file</ResourceURL>
    <Source>insert_js_code_here</Source>

</Javascript>

<JavaScript> 속성

<Javascript name="Javascript-1" enabled="true" continueOnError="false" async="false" timeLimit="200">

다음 속성은 이 정책에만 해당합니다.

속성 설명 기본 계정 현재 상태
timeLimit

스크립트 실행이 허용되는 최대 시간(ms)을 지정합니다. 예를 들어 200밀리초의 한도를 초과하면 정책에서 Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms 오류가 발생합니다.

참고: 무료 체험판 계정의 경우 실행 시간이 200ms로 제한됩니다.

N/A 필수

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

속성 설명 기본 계정 현재 상태
name

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

N/A 필수
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다.

false 선택사항
enabled

정책을 시행하려면 true로 설정합니다.

정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

true 선택사항
async

이 속성은 지원이 중단되었습니다.

false 지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>
기본 계정

N/A

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.

현재 상태 선택사항
유형 문자열

<IncludeURL> 요소

<ResourceURL> 또는 <Source> 요소를 사용하여 지정한 기본 자바스크립트 파일에 종속 항목으로 로드할 자바스크립트 라이브러리 파일을 지정합니다. 스크립트는 정책에 나열된 순서대로 평가됩니다. 코드에서 자바스크립트 객체 모델의 객체, 메서드, 속성을 사용할 수 있습니다.

추가 <IncludeURL> 요소를 사용하여 자바스크립트 종속 항목 리소스를 두 개 이상 포함합니다.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>
기본값: 없음
현재 상태: 선택사항
유형: 문자열

샘플 섹션의 기본 예시를 참조하세요.

<Property> 요소

런타임 시 자바스크립트 코드에서 액세스할 수 있는 속성을 지정합니다.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
기본값: 없음
현재 상태: 선택사항
유형: 문자열

특성

속성 설명 기본 계정 현재 상태
이름

속성 이름을 지정합니다.

N/A 필수 항목입니다.

샘플 섹션의 예시를 참조하세요.

<ResourceURL> 요소

API 흐름에서 실행할 기본 자바스크립트 파일을 지정합니다. 리소스 파일에 설명된 대로 이 파일을 API 프록시 범위 (API 프록시 번들의 /apiproxy/resources/jsc 아래 또는 API 프록시 편집기 탐색기 창 내 스크립트 섹션) 또는 여러 API 프록시에서 재사용할 수 있도록 조직 또는 환경 범위에 저장할 수 있습니다. 코드에서 자바스크립트 객체 모델의 객체, 메서드, 속성을 사용할 수 있습니다.

<ResourceURL>jsc://my-javascript.js</ResourceURL>
기본값: 없음
Presence: <ResourceURL> 또는 <Source> 중 하나가 필수입니다. <ResourceURL><Source>가 둘 다 존재하는 경우 <ResourceURL>이 무시됩니다.
유형: 문자열

샘플 섹션의 기본 예시를 참조하세요.

<Source> 요소

정책의 XML 구성에 자바스크립트를 직접 삽입할 수 있습니다. 삽입된 자바스크립트 코드는 API 흐름에서 정책이 실행될 때 실행됩니다.

기본값: 없음
Presence: <ResourceURL> 또는 <Source> 중 하나가 필수입니다. <ResourceURL><Source>가 둘 다 존재하는 경우 <ResourceURL>이 무시됩니다.
유형: 문자열

예시

<Javascript name='JS-ParseJsonHeaderFullString' timeLimit='200' >
  <Properties>
    <Property name='inboundHeaderName'>specialheader</Property>
    <Property name='outboundVariableName'>json_stringified</Property>
  </Properties>
  <Source>
var varname = 'request.header.' + properties.inboundHeaderName + '.values.string';
var h = context.getVariable(varname);
if (h) {
  h = JSON.parse(h);
  h.augmented = (new Date()).valueOf();
  var v = JSON.stringify(h, null, 2) + '\n';
  // further indent
  var r = new RegExp('^(\S*)','mg');
  v= v.replace(r,'    $1');
  context.setVariable(properties.outboundVariableName, v);
}
  </Source>
</Javascript>

<SSLInfo> 요소

자바스크립트 정책으로 생성되는 모든 HTTP 클라이언트 인스턴스에 TLS를 구성하는 데 사용되는 속성을 지정합니다.

    <SSLInfo>
        <Enabled>trueFalse</Enabled>
        <ClientAuthEnabled>trueFalse</ClientAuthEnabled>
        <KeyStore>ref://keystoreRef</KeyStore>
        <KeyAlias>keyAlias</KeyAlias>
        <TrustStore>ref://truststoreRef</TrustStore>
    </SSLInfo>
기본값: 없음
현재 상태: 선택사항
유형: 문자열

HTTP 클라이언트의 TLS를 구성하는 프로세스는 TargetEndpoint/TargetServer에 TLS를 구성하는 프로세스와 동일합니다. 자세한 내용은 Edge에서 백엔드로 TLS 구성을 참조하세요.

사용법 참고사항

자바스크립트 정책에는 실제 코드가 없습니다. 대신 자바스크립트 정책은 자바스크립트 '리소스'를 참조하고 자바스크립트가 실행되는 API 흐름의 단계를 정의합니다. 관리 UI 프록시 편집기를 통해 스크립트를 업로드하거나 로컬에서 개발한 API 프록시의 /resources/jsc 디렉터리에 포함할 수 있습니다.

자바스크립트 정책 코드 디버깅

print() 함수를 사용하여 Trace 도구의 트랜잭션 출력 패널에 디버그 정보를 출력합니다. 자세한 내용과 예제는 자바스크립트 print() 문으로 디버그를 참조하세요.

Trace에서 인쇄 문을 보려면 다음 안내를 따르세요.

  1. Trace 도구를 열고 자바스크립트 정책이 포함된 프록시의 추적 세션을 시작합니다.
  2. 프록시를 호출합니다.
  3. Trace 도구에서 Output from all Transactions를 클릭하여 출력 패널을 엽니다.

  4. 인쇄 문이 이 패널에 표시됩니다.

print() 함수를 사용하여 Trace 도구에 디버그 정보를 출력할 수 있습니다. 이 함수는 자바스크립트 객체 모델을 통해 직접 사용할 수 있습니다. 자세한 내용은 'print() 문으로 자바스크립트 디버그'를 참고하세요.

흐름 변수

이 정책은 기본적으로 변수를 입력하지 않습니다. 그러나 컨텍스트 객체의 메서드를 호출하여 자바스크립트 코드에서 흐름 변수를 설정하고 가져올 수 있습니다. 일반적인 패턴은 다음과 같습니다.

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

컨텍스트 객체는 Apigee Edge JavaScript 객체 모델의 일부입니다.

오류 참조

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.javascript.ScriptExecutionFailed 500 The JavaScript policy can throw many different types of ScriptExecutionFailed errors. Commonly seen types of errors include RangeError, ReferenceError, SyntaxError, TypeError, and URIError.
steps.javascript.ScriptExecutionFailedLineNumber 500 An error occurred in the JavaScript code. See the fault string for details. N/A
steps.javascript.ScriptSecurityError 500 A security error occurred when the JavaScript executed. See the fault string for details. N/A

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidResourceUrlFormat If the format of the resource URL specified within the <ResourceURL> or the <IncludeURL> element of the JavaScript policy is invalid, then the deployment of the API proxy fails.
InvalidResourceUrlReference If the <ResourceURL> or the <IncludeURL> elements refer to a JavaScript file that does not exist, then the deployment of the API proxy fails. The referenced source file must exist either the API proxy, environment, or organization level.
WrongResourceType This error occurs during deployment if the <ResourceURL> or the <IncludeURL> elements of the JavaScript policy refer to any resource type other than jsc (JavaScript file).
NoResourceURLOrSource The deployment of the JavaScript policy can fail with this error if the <ResourceURL> element is not declared or if the resource URL is not defined within this element. <ResourceURL> element is a mandatory element. Or, The <IncludeURL> element is declared but the resource URL is not defined within this element. The <IncludeURL> element is optional but if declared, the resource URL must be specified within the <IncludeURL> element.

Fault variables

These variables are set when this policy triggers an error at runtime. For more information, see What you need to know about policy errors.

Variables Where Example
fault.name="fault_name" fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed policy_name is the user-specified name of the policy that threw the fault. javascript.JavaScript-1.failed = true

Example error response

{
  "fault": {
    "faultstring": "Execution of SetResponse failed with error: Javascript runtime error: "ReferenceError: "status" is not defined. (setresponse.js:6)\"",
    "detail": {
      "errorcode": "steps.javascript.ScriptExecutionFailed"
    }
  }
}

Example fault rule

<FaultRule name="JavaScript Policy Faults">
    <Step>
        <Name>AM-CustomErrorResponse</Name>
        <Condition>(fault.name Matches "ScriptExecutionFailed") </Condition>
    </Step>
    <Condition>(javascript.JavaScript-1.failed = true) </Condition>
</FaultRule>

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.

관련 주제

Apigee 커뮤니티 문서

Apigee 커뮤니티에서 관련 자료를 찾아보세요.