자바스크립트 정책

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

JavaScript 정책을 사용하면 API 프록시 흐름의 컨텍스트에서 실행되는 맞춤 JavaScript 코드를 추가할 수 있습니다. 이 정책을 사용하면 Apigee 정책에서 다루지 않는 맞춤 동작을 구현할 수 있습니다.

커스텀 JavaScript 코드에서는 Apigee JavaScript 객체 모델의 객체, 메서드, 속성을 사용할 수 있습니다. 프록시 흐름 컨텍스트에서 변수를 가져오고, 설정하고, 삭제하고, 맞춤 로직을 실행하고, 오류를 처리하고, 요청 또는 응답에서 데이터를 추출하고, 백엔드 대상 URL을 동적으로 수정할 수 있습니다. 객체 모델에서 사용할 수 있는 기본 암호화 함수를 사용할 수도 있습니다.

JavaScript 정책을 사용하면 실행할 JavaScript 소스 파일을 지정하거나 <Source> 요소를 사용하여 정책 구성에 JavaScript 코드를 직접 포함할 수 있습니다. 어떤 경우든 JavaScript 코드는 정책이 연결된 단계가 실행될 때 실행됩니다.

소스 파일 옵션의 경우 소스 코드는 항상 프록시 번들의 표준 위치(apiproxy/resources/jsc)에 저장됩니다. 또는 환경 또는 조직 수준에서 리소스 파일에 소스 코드를 저장할 수 있습니다. 자세한 내용은 리소스 파일을 참고하세요. Apigee UI 프록시 편집기를 사용하여 JavaScript를 업로드할 수도 있습니다.

Apigee는 다음 용도로 JavaScript 정책을 사용하지 않는 것을 권장합니다.

로깅. MessageLogging 정책은 Splunk, Sumo, Loggly와 같은 서드 파티 로깅 플랫폼을 사용하여 로깅하는 데 더 적합합니다. 또한 이 정책은 응답이 클라이언트에 반환된 후 PostClientFlow에서 실행되어 API 프록시 성능을 개선합니다.
Apigee 정책 교체. JavaScript 정책은 Apigee 정책의 기능을 대체하지 않습니다. 필요한 기능이 Apigee 정책에 있는 경우 맞춤 JavaScript 솔루션을 구현하는 대신 해당 정책을 사용하세요. 커스텀 JavaScript 코드는 Apigee 정책의 성능 및 최적화와 일치하지 않을 수 있습니다.

JavaScript 소스 파일에는 .js 확장자가 있어야 합니다.

Apigee는 Rhino JavaScript 엔진 1.7.13에서 실행되는 JavaScript를 지원합니다.

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

샘플

대상 URL 재작성

일반적인 사용 사례는 요청 본문에서 데이터를 추출하여 흐름 변수에 저장하고 프록시 흐름의 다른 곳에서 해당 흐름 변수를 사용하는 것입니다. 예를 들어 사용자가 HTML 양식에 이름을 입력하고 제출한다고 가정해 보겠습니다. 양식 데이터를 추출하고 백엔드 서비스 URL에 동적으로 추가하려면 JavaScript 정책을 사용하세요.

참고: 이 예시를 시도하려면 프록시 편집기에서 새 프록시를 만드세요. 프록시를 만들 때 백엔드 서비스 URL(예: http://www.example.com)을 제공합니다. 이 예시에서는 백엔드 URL을 동적으로 다시 작성합니다. 새 프록시를 만들어야 하는 경우 시작하기 튜토리얼을 참고하세요.

Apigee UI에서 프록시 편집기에서 만든 프록시를 엽니다.
개발 탭을 선택합니다.
새로 만들기 메뉴에서 새 스크립트를 선택합니다.
대화상자에서 JavaScript를 선택하고 스크립트 이름을 js-example로 지정합니다.
코드 편집기에 다음 코드를 붙여넣고 프록시를 저장합니다. context 객체는 프록시 흐름의 모든 위치에서 모든 JavaScript 코드에 사용할 수 있습니다. 흐름별 상수를 가져오고, 유용한 get/set 메서드를 호출하고, 기타 작업을 실행합니다. 이 객체는 Apigee JavaScript 객체 모델의 일부입니다. target.url 흐름 변수는 대상 요청 흐름에서 액세스할 수 있는 기본 제공 읽기/쓰기 변수입니다. API URL로 이 변수를 설정하면 Apigee가 해당 백엔드 URL을 호출합니다. 이렇게 하면 프록시를 만들 때 지정한 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);
}
```
새 정책 메뉴에서 JavaScript를 선택합니다.
target-rewrite 정책의 이름을 지정합니다. 기본값을 수락하고 정책을 저장합니다.
탐색기에서 프록시 엔드포인트 Preflow를 선택하면 정책이 해당 흐름에 추가됩니다.
탐색기에서 대상 엔드포인트 PreFlow를 선택합니다.
탐색기에서 JavaScript 정책을 흐름 편집기의 대상 엔드포인트 요청 쪽으로 드래그합니다.
저장을 클릭합니다.
API를 호출할 때 조직 이름과 프록시 이름을 대체합니다.

curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST -d 'user=Will' http://myorg-test.apigee.net/js-example

이 예시에서 사용된 JavaScript 정책의 XML 정의를 검사합니다. <ResourceURL> 요소는 실행할 JavaScript 소스 파일을 지정합니다. 이 패턴은 모든 JavaScript 소스 파일(jsc://filename.js)에 적용됩니다. JavaScript 코드에 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>

JavaScript에서 속성 값 검색

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

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

JavaScript에서는 다음과 같이 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>

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);

오류 처리

JavaScript 콜아웃에서 사용할 수 있는 오류 처리 기법에 대한 자세한 내용과 설명은 JavaScript 정책에서 오류를 반환하는 올바른 방법을 참고하세요. Apigee 커뮤니티의 제안은 정보 제공만을 목적으로 하며 Google에서 추천하는 권장사항을 나타내지는 않습니다.

JavaScript 정책에서 읽기 전용 모드로 request.content.asJSON에 액세스하면 큰 정수가 메시지 본문에서 지수 표기법으로 변환됩니다. 변환된 값으로 메시지를 덮어씁니다.

요소 참조

요소 참조는 JavaScript 정책의 요소 및 속성을 설명합니다.

<?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> 속성

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

속성	설명	기본값	존재 여부
languageVersion	코드가 작성된 JavaScript 언어의 버전을 지정합니다. 값으로는 `VERSION_DEFAULT`, `VERSION_1_0`, `VERSION_1_1`, `VERSION_1_2`, `VERSION_1_3`, `VERSION_1_4`, `VERSION_1_5`, `VERSION_1_6`, `VERSION_1_7`, `VERSION_1_8`, `VERSION_ES6`이 있습니다.	VERSION_DEFAULT	선택사항
timeLimit	스크립트가 실행될 수 있는 최대 시간(밀리초)을 지정합니다. 예를 들어 200ms의 한도를 초과하면 정책에서 `Javascript.policy_name failed with error: Javascript runtime exceeded limit of 200ms` 오류를 생성합니다. 참고: 무료 체험판 계정의 경우 실행 시간이 200ms로 제한됩니다.	해당 사항 없음	필수

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

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

기본값

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

해당 사항 없음

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

접속 상태 선택사항

유형 문자열

<IncludeURL> 요소

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

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

경고: JavaScript 파일이 프록시 또는 환경 수준에서 저장되면 -F 옵션을 사용하여 cURL으로 또는 REST 클라이언트를 통해 파일 첨부로 올바르게 업로드해야 합니다. Content-Type은 multipart/form-data입니다. 자세한 내용은 리소스 관리를 참고하세요.

<IncludeURL>jsc://my-javascript-dependency.js</IncludeURL>

기본값:	없음
Presence:	선택사항
유형:	문자열

<Property> 요소

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

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>

기본값:	없음
Presence:	선택사항
유형:	문자열

속성

속성	설명	기본값	존재 여부
이름	속성 이름을 지정합니다.	해당 사항 없음	필수

예

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

<ResourceURL> 요소

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

<ResourceURL>jsc://my-javascript.js</ResourceURL>

기본값:	없음
Presence:	`<ResourceURL>` 또는 `<Source>` 중 하나가 필수입니다. `<ResourceURL>`과 `<Source>`가 모두 있으면 정책에서 `<ResourceURL>`을 무시합니다.
유형:	문자열

예

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

<Source> 요소

정책의 XML 구성에 JavaScript를 직접 삽입할 수 있습니다. 삽입된 JavaScript 코드는 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> 요소

JavaScript 정책으로 생성되는 모든 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 구성 옵션을 참고하세요.

사용 참고사항

JavaScript 정책 코드 디버깅

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

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

디버그 도구를 열고 JavaScript 정책이 포함된 프록시의 추적 세션을 시작합니다.
프록시를 호출합니다.
디버그 도구에서 모든 트랜잭션의 출력을 클릭하여 출력 패널을 엽니다.
인쇄 문이 이 패널에 표시됩니다.

흐름 변수

이 정책은 기본적으로 변수를 입력하지 않습니다. 그러나 context 객체의 메서드를 호출하여 JavaScript 코드에서 흐름 변수를 설정하고 가져올 수 있습니다. 예를 들면 다음과 같습니다.

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

context 객체는 Apigee JavaScript 객체 모델의 일부입니다.

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 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`

오류 응답 예시

참고: 오류 처리에서 권장사항은 오류 응답의 errorcode 부분을 트래핑하는 것입니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.

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

JavaScript에서 다중 값 헤더를 처리하는 방법

자바스크립트 정책 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

샘플

대상 URL 재작성

JavaScript에서 속성 값 검색

오류 처리

요소 참조

<JavaScript> 속성

<DisplayName> 요소

<IncludeURL> 요소

<Property> 요소

속성

예

<ResourceURL> 요소

예

<Source> 요소

예

<SSLInfo> 요소

사용 참고사항

JavaScript 정책 코드 디버깅

흐름 변수

오류 참조

런타임 오류

배포 오류

오류 변수

오류 응답 예시

오류 규칙 예시

스키마

관련 주제

Apigee 커뮤니티 문서

자바스크립트 정책