자바스크립트 정책

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

Apigee Edge 문서 보기

정책 아이콘

소개

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

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

정보

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

자바스크립트 정책에 권장되지 않는 한 가지 사용 사례는 로깅입니다. MessageLogging 정책은 Splunk, Sumo, Loggly 등의 제3자 로깅 플랫폼에 로깅하는 데 더욱 적합하며 응답이 클라이언트에게 다시 보내진 후 실행되는 PostClientFlow에서 MessageLogging 정책을 실행하여 API 프록시 성능을 향상시킵니다.

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

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

Apigee는 Rhyno 자바스크립트 엔진 1.7.13에서 실행되는 자바스크립트를 지원합니다.

동영상

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

샘플

대상 URL 재작성

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

  1. Apigee UI에서 프록시 편집기에서 만든 프록시를 엽니다.
  2. 개발 탭을 선택합니다.
  3. 새로 만들기 메뉴에서 새 스크립트를 선택합니다.
  4. 대화상자에서 자바스크립트를 선택하고 스크립트에 js-example과 같은 이름을 지정합니다.
  5. 코드 편집기에 다음 코드를 붙여넣고 프록시를 저장합니다. 주목해야 할 중요한 사항은 context 객체입니다. 이 객체는 프록시 흐름의 모든 위치에서 모든 자바스크립트 코드에 사용할 수 있습니다. 이는 흐름별 상수를 가져오고, 유용한 get/set 메서드를 호출하고, 더 많은 작업을 처리하는 데 사용됩니다. 이 객체 부분은 Apigee의 자바스크립트 객체 모델에 포함됩니다. target.url 흐름 변수는 대상 요청 흐름에서 액세스할 수 있는 기본 제공 읽기/쓰기 변수입니다. API URL로 이 변수를 설정하면 Apigee가 해당 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에서 추천하는 권장사항을 나타내지는 않습니다.

요소 참조

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

<?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)을 지정합니다. 예를 들어 200ms의 한도를 초과하면 정책에서 Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms 오류를 생성합니다.

 해당 사항 없음 필수

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

속성 설명 기본값 접속 상태
name

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

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

 해당 사항 없음 필수
continueOnError

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

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

 거짓 선택사항
enabled

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

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

 참 선택사항
async

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

 거짓 지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>
기본값

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
접속 상태 선택사항
유형 문자열

<IncludeURL> 요소

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

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

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

예

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

<Property> 요소

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

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

속성

속성 설명 기본값 접속 상태
이름

속성 이름을 지정합니다.

 해당 사항 없음 필수 항목입니다.

예

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

<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>
기본값: 없음
Presence: 선택사항
유형: 문자열

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

사용 참고사항

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

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

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

  1. 디버그 도구를 열고 자바스크립트 정책이 포함된 프록시의 추적 세션을 시작합니다.
  2. 프록시를 호출합니다.
  3. 디버그 도구에서 모든 트랜잭션의 출력을 클릭하여 출력 패널을 엽니다.

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

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

흐름 변수

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

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

컨텍스트 객체는 Apigee 자바스크립트 객체 모델의 일부입니다.

오류 참조

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

런타임 오류

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

오류 코드 HTTP 상태 원인 수정
steps.javascript.ScriptExecutionFailed 500 JavaScript 정책으로 인해 여러 가지 유형의 ScriptExecutionFailed 오류가 발생할 수 있습니다. 흔히 볼 수 있는 오류 유형에는 RangeError, ReferenceError, SyntaxError, TypeError, URIError가 있습니다.
steps.javascript.ScriptExecutionFailedLineNumber 500 JavaScript 코드에서 오류가 발생했습니다. 자세한 내용은 오류 문자열을 참조하세요. 해당 사항 없음
steps.javascript.ScriptSecurityError 500 JavaScript 실행 시 보안 오류가 발생했습니다. 자세한 내용은 오류 문자열을 참조하세요. 해당 사항 없음

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름 원인 수정
InvalidResourceUrlFormat JavaScript 정책의 <ResourceURL> 또는 <IncludeURL> 요소 내에서 지정된 리소스 URL 형식이 잘못된 경우 API 프록시 배포가 실패합니다.
InvalidResourceUrlReference <ResourceURL> 또는 <IncludeURL> 요소가 존재하지 않는 JavaScript 파일을 참조하는 경우 API 프록시 배포가 실패합니다. 참조된 소스 파일은 API 프록시, 환경 또는 조직 수준에 있어야 합니다.
WrongResourceType 이 오류는 JavaScript 또는 <ResourceURL> 정책의 <IncludeURL> 요소가 jsc(JavaScript 파일) 이외의 리소스 유형을 참조하는 경우에 배포 중에 발생합니다.
NoResourceURLOrSource <ResourceURL> 요소가 선언되지 않았거나 이 요소 내에 리소스 URL이 정의되지 않은 경우 JavaScript 정책을 배포할 때 오류가 발생할 수 있습니다. <ResourceURL> 요소는 필수 요소입니다. <IncludeURL> 요소는 선언되지만 리소스 URL은 이 요소 내에서 정의되지 않습니다. <IncludeURL> 요소는 선택사항이지만 선언된 경우 리소스 URL은 <IncludeURL> 요소 내에 지정되어야 합니다.

오류 변수

이러한 변수는 이 정책이 런타임 시 오류를 트리거할 때 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수 장소 예
fault.name="fault_name" fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "ScriptExecutionFailed"
javascript.policy_name.failed policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. javascript.JavaScript-1.failed = true

오류 응답 예시

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

오류 규칙 예시

<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 커뮤니티에서 관련 자료를 찾아보세요.