이 페이지는 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><Life></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></Life></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" select="''"/> |
ref |
선택사항 | 문자열 |
매개변수 값을 포함하는 컨텍스트 변수를 가리킵니다. 이 정책을 평가하기 전 예를 들어 <Parameter name="uid" ref="authn.uid"/> 이 속성을 사용할 때는 |
value |
선택사항 | 문자열 |
매개변수에 대해 하드 코딩된 값을 지정합니다. 예를 들어 <Parameter name="answer" value="42"/> 이 속성을 사용할 때는 |
이 매개변수는 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> 요소에 지정된 메시지 또는 문자열 변수가 범위를 벗어난 경우(정책이 실행 중인 특정 흐름에서 사용할 수 없음) 또는 확인할 수 없는 경우(정의되지 않음)일 때 발생합니다.
|
build |
steps.xsl.XSLEvaluationFailed |
500 |
이 오류는 입력 XML 페이로드를 사용할 수 없거나 형식이 잘못되었거나, XSLTransform 정책이 실패하거나 XSL 파일에 제공된 변환 규칙에 따라 입력 XML 파일을 변환할 수 없는 경우에 발생합니다. XSLTransform 정책이 실패하는 원인은 여러 가지가 있습니다. 오류 메시지의 결함 이유를 통해 원인에 대한 자세한 정보를 얻을 수 있습니다. | build |
배포 오류
이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
오류 이름 | 원인 | 해결 |
---|---|---|
XSLEmptyResourceUrl |
XSLTransform 정책의 <ResourceURL> 요소가 비어 있으면 API 프록시 배포가 실패합니다. |
build |
XSLInvalidResourceType |
XSLTransform 정책의 <ResourceURL> 요소에 지정된 리소스 유형이 xsl 유형이 아니면 API 프록시 배포가 실패합니다. |
build |