XSLTransform 정책

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

Apigee Edge 문서 보기

정책 아이콘

소개

XSLTransform 정책은 커스텀 확장 가능한 스타일시트 언어 변환(XSLT)을 XML 메시지에 적용하여 XML에서 XML, HTML, 또는 일반 텍스트와 같은 다른 형식으로 변환할 수 있도록 합니다. 이 정책은 XML을 지원하지만 동일한 데이터에 대해 다른 XML 형식이 필요한 애플리케이션을 통합하는 데 주로 사용됩니다.

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

입력

XSL 정책은 다음과 같은 입력을 수행합니다.

  • (필수) /resources/xsl 아래의 API 프록시에 저장된 변환 규칙 집합이 포함된 XSLT 스타일시트의 이름입니다.
  • (필수) 변환할 XML(일반적으로 요청 또는 응답 메시지)입니다.
  • (선택) 출력을 저장하는 변수 이름입니다.
  • (선택) XSL 스타일시트의 매개변수와 일치하는 매개변수입니다.

파싱 프로세서

Apigee는 Saxon XSLT 프로세서를 사용하며 XSLT 1.0 및 2.0을 지원합니다.

지원되지 않는 XSL 요소

XSL 정책은 다음 XSL 요소를 지원하지 않습니다.

  • <xsl:include>
  • <xsl:import>

샘플

다음 샘플은 XSL 변환 흐름을 보여줍니다.

XSL 정책 -->

<XSL name="TransformXML">
  <ResourceURL>xsl://my_transform.xsl</ResourceURL>
  <Source>request</Source>
</XSL>

간단한 XSL 정책입니다. 다음 예시로 이동하여 정책(my_transform.xsl)에서 참조된 XSLT 스타일시트를 확인하세요. <Source> 요소가 중요합니다. 예를 들어 변환하려는 XML이 응답에 있는 경우 <Source>을 response로 설정하지 않으면(또한 정책이 응답 흐름에 연결되지 않으면) 변환이 수행되지 않습니다. 하지만 이 경우에는 변환할 XML이 요청에 포함됩니다.

XSLT 스타일시트 -->

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
  <xsl:output method="text"/>
  <xsl:variable name="newline">
    <xsl:text></xsl:text>
  </xsl:variable>
  <xsl:template match="/">
  <xsl:text>&lt;Life&gt;</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:text>Here are the odd-numbered items from the list:</xsl:text>
    <xsl:value-of select="$newline"/>
    <xsl:for-each select="list/listitem">
      <xsl:if test="(position() mod 2) = 1">
        <xsl:number format="1. "/>
        <xsl:value-of select="."/>
        <xsl:value-of select="$newline"/>
      </xsl:if>
    </xsl:for-each>
  <xsl:text>&lt;/Life&gt;</xsl:text>
</xsl:template>
</xsl:stylesheet>

정책에서 참조되는 my_transform.xsl 스타일시트입니다. 수신 XML 메시지의 예시를 보려면 다음 샘플로 이동하세요.

메시지 -->

<?xml version="1.0"?>
<list>
  <title>A few of my favorite albums</title>
  <listitem>A Love Supreme</listitem>
  <listitem>Beat Crazy</listitem>
  <listitem>Here Come the Warm Jets</listitem>
  <listitem>Kind of Blue</listitem>
  <listitem>London Calling</listitem>
  <listitem>Remain in Light</listitem>
  <listitem>The Joshua Tree</listitem>
  <listitem>The Indestructible Beat of Soweto</listitem>
</list>

요청의 샘플 메시지입니다(첫 번째 샘플에서 정책의 <Source>request</Source> 요소에 표시됨).

변환된 메시지

<Life>
Here are the odd-numbered items from the list:
1. A Love Supreme
3. Here Come the Warm Jets
5. London Calling
7. The Joshua Tree
</Life>

이 샘플의 XSLT 스타일시트 이후에 변환된 메시지는 XML 메시지에 적용됩니다.

<XSL> 요소

XSLTransform 정책을 정의합니다.

기본값 해당 사항 없음
필수 여부 필수
유형 복합 객체
상위 요소 해당 사항 없음
하위 요소 <OutputVariable>
<Parameters>
<ResourceURL>
<Source>

<XSL> 요소에는 다음과 같은 속성이 있습니다.

속성 설명 필수 여부 유형
name 정책의 이름입니다. 이름에 사용할 수 있는 문자는 A-Z0-9._\-$ %로 제한됩니다. 그러나 Apigee UI는 영숫자가 아닌 문자를 자동으로 삭제하는 등 추가 제한사항을 적용합니다. 필수 문자열

하위 요소 참조

이 섹션에서는 <XSL>의 하위 요소를 설명합니다.

<OutputVariable>

변환의 출력을 저장하는 변수입니다. 이 요소를 커스텀 변수로 설정한 다음 해당 변수를 사용합니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 문자열
상위 요소 <XSL>
하위 요소 없음

<OutputVariable>의 값은 메시지 유형일 수 없습니다. 즉, message, request, response일 수 없습니다.

메시지 콘텐츠를 변환 출력으로 바꾸려면 이 요소를 삭제하세요. 예를 들어 메시지를 HTML로 변환하는 경우 이 요소를 포함하지 마세요.

<Parameters>

스타일시트에 <xsl:param> 요소에 대한 지원을 추가합니다. 각 매개변수를 이 요소의 <Parameter> 하위 요소로 정의합니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 <Parameter> 요소의 배열
상위 요소 <XSL>
하위 요소 <Parameter>

<Parameters> 요소에는 다음과 같은 속성이 있습니다.

속성 설명 필수 여부 유형
ignoreUnresolvedVariables 정책에 따라 XSLT 스크립트 안내에서 해결되지 않은 변수 오류를 무시하는지 확인합니다. 기본값은 false입니다. 즉, 기본적으로 해결되지 않은 변수가 확인되면 정책에 따라 오류가 발생합니다. 선택사항 부울

<Parameter>

<Parameters> 요소에서 매개변수를 정의합니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 복합 객체
상위 요소 <Parameters>
하위 요소 없음

<Parameter> 요소에는 다음과 같은 속성이 있습니다.

속성 필수 여부 유형 설명
name 필수 문자열

매개변수의 이름입니다. Apigee는 여기에 설정된 값을 스타일시트의 <xsl:param> 요소에 있는 name 속성 값과 일치시킵니다.

예를 들어 uid 이름을 입력하면 XSL이 다음과 비슷하게 표시됩니다. 

<xsl:param name="uid" select="''"/>
ref 선택사항 문자열

매개변수 값을 포함하는 컨텍스트 변수를 가리킵니다. 이 정책을 평가하기 전 ref 컨텍스트 변수에 대한 값을 설정해야 합니다.

예를 들어 uid 매개변수가 authn.uid라는 변수에서 값을 가져와야 하는 경우 <Parameter> 요소는 다음과 같이 표시됩니다.

<Parameter name="uid" ref="authn.uid"/>

이 속성을 사용할 때는 value 속성을 사용하지 않습니다.
value 선택사항 문자열

매개변수에 대해 하드 코딩된 값을 지정합니다. 예를 들어 answer라는 매개변수의 값이 42이면 <Parameter> 요소가 다음과 같이 표시됩니다.

<Parameter name="answer" value="42"/>

이 속성을 사용할 때는 ref 속성을 사용하지 않습니다.

이 매개변수는 ref 속성 또는 명시적인 value로 값을 가져옵니다.

예시 및 자세한 설명은 XSL 변환 정책에서 선택적 매개변수를 사용하는 방법을 참조하세요.

<ResourceURL>

Apigee에서 메시지 변환을 위해 사용되는 XSL 파일입니다. 이 요소의 값은 /resources/xsl에서 API 프록시에 저장된 XSL 스타일시트의 이름입니다.

기본값 해당 사항 없음
필수 여부 필수
유형 문자열
상위 요소 <XSL>
하위 요소 없음

예를 들면 다음과 같습니다.

<ResourceURL>xsl://SubscriberNumbers-Request.xsl</ResourceURL>

자세한 내용은 리소스 파일을 참조하세요.

<Source>

변환된 메시지를 지정합니다. 이 값은 변환할 메시지가 인바운드 또는 아웃바운드인지에 따라 request 또는 response로 설정됩니다.

기본값 해당 사항 없음
필수 여부 선택사항
유형 문자열
상위 요소 <XSL>
하위 요소 없음

변환을 정의하는 XSL 파일은 <ResourceURL>로 정의됩니다.

  • 소스가 누락된 경우 간단한 메시지로 처리됩니다. 예를 들면 다음과 같습니다. <Source>message</Source>
  • 소스 변수를 확인할 수 없거나 메시지 유형이 아닌 것으로 확인되면 변환 단계가 실패합니다.

오류 참조

런타임 오류

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

오류 코드 HTTP 상태 원인 해결
steps.xsl.XSLSourceMessageNotAvailable 500 이 오류는 XSLTransform 정책의 <Source> 요소에 지정된 메시지 또는 문자열 변수가 범위를 벗어난 경우(정책이 실행 중인 특정 흐름에서 사용할 수 없음) 또는 확인할 수 없는 경우(정의되지 않음)일 때 발생합니다.
steps.xsl.XSLEvaluationFailed 500 이 오류는 입력 XML 페이로드를 사용할 수 없거나 형식이 잘못되었거나, XSLTransform 정책이 실패하거나 XSL 파일에 제공된 변환 규칙에 따라 입력 XML 파일을 변환할 수 없는 경우에 발생합니다. XSLTransform 정책이 실패하는 원인은 여러 가지가 있습니다. 오류 메시지의 결함 이유를 통해 원인에 대한 자세한 정보를 얻을 수 있습니다.

배포 오류

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

오류 이름 원인 해결
XSLEmptyResourceUrl XSLTransform 정책의 <ResourceURL> 요소가 비어 있으면 API 프록시 배포가 실패합니다.
XSLInvalidResourceType XSLTransform 정책의 <ResourceURL> 요소에 지정된 리소스 유형이 xsl 유형이 아니면 API 프록시 배포가 실패합니다.

관련 주제