이 페이지는 Cloud Translation API를 통해 번역되었습니다.

JavaScript로 API 프록시 프로그래밍

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

이 주제에서는 JavaScript를 사용하여 응답 메시지에 HTTP 헤더를 동적으로 추가하는 방법과 JSON 응답을 파싱하고 요청 앱에 속성의 하위 집합을 반환하는 방법을 설명합니다.

샘플 코드 다운로드 및 사용해 보기

설명서 예시 정보

이 설명서 예에서는 JavaScript에서 API 동작을 구현하는 API 프록시 패턴을 보여줍니다. JavaScript 예는 간단한 변수와 메시지 콘텐츠를 사용하는 방법을 보여주기 위해 설계되었습니다. 한 샘플은 변수를 get 및 set하는 방법을 보여줍니다. 두 번째 예는 JSON을 파싱하고 그 결과에서 메시지를 구성하는 방법을 보여줍니다.

API 프록시에 두 개의 JavaScript 샘플이 있습니다.

setHeaders.js: 이 JavaScript는 API 프록시가 호출될 때 설정된 몇 가지 변수의 값을 가져옵니다. JavaScript는 각 요청의 값을 볼 수 있도록 이러한 변수를 응답 메시지에 추가합니다.
minimize.js: 이 JavaScript는 메시지 콘텐츠로 작업하는 방법을 보여줍니다. 이 샘플의 배경은 서비스가 필요한 것보다 더 많은 데이터를 반환하는 경우가 많다는 것입니다. 따라서 JavaScript가 응답 메시지를 파싱하고 몇 가지 흥미로운 속성을 추출한 다음 이 속성을 사용하여 응답 메시지의 콘텐츠를 빌드합니다.

setHeader.js의 코드는 다음과 같습니다.

context.setVariable("response.header.X-Apigee-Target", context.getVariable("target.name"));
context.setVariable("response.header.X-Apigee-ApiProxyName", context.getVariable("apiproxy.name"));
context.setVariable("response.header.X-Apigee-ProxyName", context.getVariable("proxy.name"));
context.setVariable("response.header.X-Apigee-ProxyBasePath", context.getVariable("proxy.basepath"));
context.setVariable("response.header.X-Apigee-ProxyPathSuffix", context.getVariable("proxy.pathsuffix"));
context.setVariable("response.header.X-Apigee-ProxyUrl", context.getVariable("proxy.url"));

minimize.js의 코드는 다음과 같습니다.

// Parse the respose from the target.
var res = JSON.parse(context.proxyResponse.content);

// Pull out only the information we want to see in the response.
var minimizedResponse = { city: res.root.city,
                          state: res.root.state };
          
// Set the response variable. 
context.proxyResponse.content = JSON.stringify(minimizedResponse);

컨텍스트 객체를 통해 자바스크립트의 흐름 변수에 액세스할 수 있습니다. 이 객체는 Edge JavaScript 객체 모델의 일부입니다. 객체 모델에 관한 자세한 내용은 JavaScript 객체 모델을 참조하세요.

시작하기 전에

이 설명서 예시를 살펴보기 전에 다음과 같은 기본 개념을 숙지해야 합니다.

정책의 정의 및 정책을 프록시에 연결하는 방법 정책에 대한 소개는 정책이란 무엇인가요?를 참조하세요.
흐름 구성에 설명된 프록시 흐름의 구조 흐름을 사용하면 정책이 API 프록시에서 실행되는 순서를 지정할 수 있습니다. 이 예시에서는 여러 정책을 만들어 API 프록시 흐름에 추가합니다.
API 프록시 구성 참조에 설명된 대로 API 프록시 프로젝트가 파일 시스템에서 구성되는 방식입니다.
XML, JSON, 자바스크립트에 관한 실무 지식 이 예시에서는 파일 시스템에 있는 XML 파일로 API 프록시와 정책을 빌드합니다.

샘플 코드를 다운로드한 경우 이 주제에서 다루는 모든 파일을 javascript-cookbook 샘플 폴더에서 찾을 수 있습니다. 다음 섹션에서는 샘플 코드를 자세히 설명합니다.

프록시 흐름 이해하기

JavaScript가 API 프록시에서 실행되도록 하려면 '단계'라는 정책 연결을 사용하여 흐름에 연결해야 합니다. 자바스크립트 유형 (대소문자 참고)의 정책에는 단순히 자바스크립트 파일의 이름 참조가 포함됩니다. ResourceURL 요소를 사용하여 정책을 자바스크립트 파일로 가리킵니다.

예를 들어 다음 정책은 setHeader.js라는 자바스크립트 파일을 참조합니다.

<Javascript name='setHeaders' timeLimit='200'>
    <ResourceURL>setHeaders.js</ResourceURL>
</Javascript>

권장사항: 자바스크립트 리소스에는 항상 .js 확장 프로그램을 사용하세요.

다른 정책 유형과 마찬가지로 이 정책을 API 프록시 흐름에 연결할 수 있습니다. 정책을 API 프록시 흐름에 연결하면 JavaScript가 실행되어야 하는 위치를 나타낼 수 있습니다. 이를 통해 요청 메시지 또는 응답 메시지가 API 프록시를 통해 '흐르면서' 이러한 메시지와 상호작용하는 자바스크립트를 실행할 수 있습니다. 이 예시에서 두 가지 JavaScript는 모두 응답 메시지에 HTTP 헤더를 설정하고 Apigee Edge가 요청 앱에 반환하는 응답 메시지를 '최소화'하는 두 가지 작업을 수행하기 때문에 응답 흐름에서 실행됩니다.

관리 UI에서 이 흐름 구성을 열면 아래에 흐름 구성이 표시됩니다.

Navigator 창에서 Proxy Endpoints > default > PostFlow를 선택합니다.

아래에는 'default'라는 ProxyEndpoint의 해당 XML 구성이 나와 있습니다.

<ProxyEndpoint name="default">
  <PostFlow>
    <Response>
      <!-- Steps reference policies under /apiproxy/policies -->
      <!-- First, set a few HTTP headers with variables for this transaction. -->
      <Step><Name>setHeaders</Name></Step>
      <!-- Next, transform the response from XML to JSON for easier parsing with JavaScript -->
      <Step><Name>transform</Name></Step>
      <!-- Finally, use JavaScript to create minimized response with just city and state. -->
      <Step><Name>minimize</Name></Step>
    </Response>
  </PostFlow>
  <HTTPProxyConnection>
        <!-- BasePath defines the network address for this API proxy. See the script 'invoke.sh' to see how the complete URL for this API proxy is constructed.-->
    <BasePath>/javascript-cookbook</BasePath>
     <!-- Set VirtualHost to 'secure' to have this API proxy listen on HTTPS. -->
    <VirtualHost>default</VirtualHost>
  </HTTPProxyConnection>
  <RouteRule name="default">
    <TargetEndpoint>default</TargetEndpoint>
  </RouteRule>
</ProxyEndpoint>

다음은 흐름의 요소를 요약한 것입니다.

<Request> - <Request> 요소는 여러 <Step> 요소로 구성됩니다. 각 단계에서는 이 주제의 나머지 부분에서 만든 정책 중 하나를 호출합니다. 이러한 정책은 JavaScript를 API 프록시 흐름에 연결하며 정책 연결 위치에 따라 JavaScript가 실행되는 시점이 결정됩니다.
<Response> - <Response> 요소에는 <Steps>도 포함됩니다. 이러한 단계는 대상의 최종 응답 처리를 담당하는 정책도 호출합니다 (이 예시에서는 Apigee의 모의 서비스 대상입니다. /apiproxy/targets/default.xml 아래의 HTTPTargetConnection 설정을 확인하세요.)
<HTTPProxyConnection> - 앱이 이 API를 사용하기 위해 호출하는 네트워크 주소를 정의하는 호스트 및 URI 경로를 지정합니다.
<RouteRule> - 이 요소는 ProxyEndpoint에서 호출하는 TargetEndpoint 구성을 지정합니다.

프록시에 자바스크립트 코드 추가

자바스크립트 (예: Python 스크립트, 자바 JAR 파일, XSLT 파일 등)는 리소스로 저장됩니다. JavaScript로 처음 작업을 시작하는 경우 API 프록시에 JavaScript 파일을 저장하는 것이 가장 쉽습니다. 계속 진행함에 따라 자바스크립트를 최대한 일반적이고 재사용 가능하도록 만든 다음 환경 또는 조직 수준에 저장해야 합니다. 이렇게 하면 동일한 자바스크립트 파일을 여러 API 프록시에 저장하지 않아도 되므로 관리가 빠르게 어려워질 수 있습니다.

조직 및 환경 수준에서 리소스를 저장하는 방법을 알아보려면 리소스 파일을 참고하세요.

사용해 보기

프록시 배포 및 호출에 대한 안내는 자바스크립트 설명서 리드미를 참조하세요.

API 프록시 가져오기 및 배포

변경한 후 관리 UI에 있는 API 프록시 빌더 도구에서 API 프록시를 저장할 수 있습니다.

또는 /api-platform-samples/doc-samples/javascript-cookbook 디렉터리에서 다음 명령어를 실행할 수도 있습니다.

$ sh deploy.sh

자바스크립트 테스트

/api-platform-samples/doc-samples/javascript-cookbook 디렉터리에서 다음 명령어를 실행합니다.

$ sh invoke.sh

curl 플래그 -v는 셸 스크립트에서 자바스크립트로 수정된 응답 메시지의 HTTP 헤더를 보는 데 사용됩니다.

다음 단계에 따라 직접 요청을 제출할 수 있습니다.

$ curl -v http://{org_name}-test.apigee.net/javascript-cookbook

JavaScript가 올바르게 실행되면 다음과 같은 응답이 표시됩니다.

< X-Apigee-Demo-Target: default
< X-Apigee-Demo-ApiProxyName: simple-javascript
< X-Apigee-Demo-ProxyName: default
< X-Apigee-Demo-ProxyBasePath: /javascript-cookbook
< X-Apigee-Demo-ProxyPathSuffix: /xml
< X-Apigee-Demo-ProxyUrl: http://rrt331ea.us-ea.4.apigee.com/javascript-cookbook/xml
 
{"city":"San Jose","state":"CA"}

이제 JavaScript를 수정하여 새로운 것을 시도하고, API 프록시를 다시 배포하고, 동일한 요청을 제출하여 결과를 확인할 수 있습니다. 변경사항을 적용하려면 항상 자바스크립트가 포함된 API 프록시를 배포해야 합니다.

스크립트 오류

JavaScript를 작성할 때는 오류가 발생할 수밖에 없습니다. API 프록시에서 발생하는 JavaScript 오류의 형식은 아래에 나와 있습니다.

{  
   "fault":{  
      "faultstring":"Execution of rewriteTargetUrl failed with error: Javascript runtime error: \"TypeError: Cannot find function getVariable in object TARGET_REQ_FLOW. (rewriteTargetUrl_js#1). at line 1 \"",
      "detail":{  
         "errorcode":"steps.javascript.ScriptExecutionFailed"
      }
   }
}

JavaScript를 사용하는 경우

Apigee Edge에는 일반적으로 여러 가지 방법으로 특정 기능을 구현할 수 있습니다. 가능하면 즉시 사용 가능한 정책을 사용하고 모든 API 프록시 로직을 자바스크립트로 코딩하려는 유혹을 피하세요. Apigee Edge는 컴파일된 JavaScript를 사용하여 성능을 개선하지만 JavaScript가 정책만큼 수행될 가능성은 낮습니다. JavaScript는 유지관리 및 디버깅이 더 어려울 수 있습니다. 요구사항에 맞는 기능을 위해 JavaScript를 예약합니다.

커스텀 기능의 성능이 중요한 경우 가능하면 자바를 사용하세요.

요약

이 설명서 주제에서는 JavaScript를 API 프록시 구성에 포함하여 맞춤 동작을 구현하는 방법을 배웠습니다. 샘플로 구현된 커스텀 동작은 및 변수를 가져오는 방법과 JSON을 파싱하고 커스텀 응답 메시지를 구성하는 방법을 보여줍니다.