Política XSLTransform

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

A política XSLTransform aplica transformações de linguagem de folhas de estilo extensíveis (XSLT) personalizadas a mensagens XML, o que lhe permite transformá-las de XML para outro formato, como HTML ou texto simples. A política é frequentemente usada para integrar aplicações que suportam XML, mas que requerem formatos baseados em XML diferentes para os mesmos dados.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Entradas

A política XSL usa as seguintes entradas:

  • (Obrigatório) O nome de uma folha de estilos XSLT, que contém um conjunto de regras de transformação armazenadas no proxy de API em /resources/xsl.
  • (Obrigatório) O XML a ser transformado (normalmente, uma mensagem de pedido ou resposta).
  • (Opcional) O nome de uma variável que armazena a saída.
  • (Opcional) Parâmetros que correspondem aos parâmetros na folha de estilo XSL.

Processador de análise

O Apigee baseia-se no processador Saxon XSLTe suporta XSLT 1.0 e 2.0.

Elementos XSL não suportados

A política XSL não suporta os seguintes elementos XSL:

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

Amostras

Os exemplos seguintes mostram um fluxo de transformação XSL:

Política XSL -->

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

Política de XSL simples. Aceda ao exemplo seguinte para ver a folha de estilos XSLT referenciada na política (my_transform.xsl). O elemento <Source> é importante. Por exemplo, se o XML que quer transformar estiver na resposta, a transformação não ocorre, a menos que defina <Source> como response (e a política esteja anexada ao fluxo de resposta). No entanto, neste caso, o XML a ser transformado está no pedido.

Folha de estilos 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>

A folha de estilos my_transform.xsl referenciada na política. Aceda ao exemplo seguinte para ver um exemplo de uma mensagem XML recebida.

Message -->

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

Mensagem de exemplo no pedido (indicada no elemento <Source>request</Source> da política no primeiro exemplo).

Mensagem transformada

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

A mensagem transformada depois de a folha de estilos XSLT destes exemplos ser aplicada à mensagem XML.

<XSL> elemento

Define uma política XSLTransform.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo Objeto complexo
Elemento principal N/A
Elementos subordinados <OutputVariable>
<Parameters>
<ResourceURL>
<Source>

O elemento <XSL> tem os seguintes atributos:

Atributo Descrição Obrigatório? Tipo
name Nome da política. Os carateres que pode usar no nome estão restritos a: A-Z0-9._\-$ %. No entanto, a IU do Apigee aplica restrições adicionais, como a remoção automática de carateres que não sejam alfanuméricos. Obrigatória String

Referência de elemento secundário

Esta secção descreve os elementos subordinados de <XSL>.

<OutputVariable>

Uma variável que armazena o resultado da transformação. Deve definir este elemento como uma variável personalizada e, em seguida, consumir essa variável.

Valor predefinido N/A
Obrigatório? Opcional
Tipo String
Elemento principal <XSL>
Elementos subordinados Nenhum

O valor de <OutputVariable> não pode ser do tipo message, ou seja, não pode ser message, request nem response.

Para substituir o conteúdo da mensagem pelo resultado da transformação, elimine este elemento. Por exemplo, se estiver a transformar uma mensagem em HTML, não inclua o elemento.

<Parameters>

Adiciona suporte para o elemento <xsl:param> nos seus ficheiros de estilos. Define cada parâmetro como um elemento secundário <Parameter> deste elemento.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Matriz de <Parameter> elementos
Elemento principal <XSL>
Elementos subordinados <Parameter>

O elemento <Parameters> tem os seguintes atributos:

Atributo Descrição Obrigatório? Tipo
ignoreUnresolvedVariables Determina se a política ignora erros de variáveis não resolvidos nas instruções do script XSLT. O valor predefinido é false, o que significa que, por predefinição, a política vai gerar erros se encontrar variáveis não resolvidas. Opcional Booleano

<Parameter>

Define um parâmetro no elemento <Parameters>.

Valor predefinido N/A
Obrigatório? Opcional
Tipo Objeto complexo
Elemento principal <Parameters>
Elementos subordinados Nenhum

O elemento <Parameter> tem os seguintes atributos:

Atributo Obrigatório? Tipo Descrição
name Obrigatória String

O nome do parâmetro. O Apigee faz corresponder o valor que definir aqui ao valor do atributo name num elemento <xsl:param> na folha de estilos.

Por exemplo, se introduzir um nome de uid, o seu XSL pode ter um aspeto semelhante ao seguinte: 

<xsl:param name="uid" select="''"/>
ref Opcional String

Aponta para uma variável de contexto que contém o valor do parâmetro. Os valores das variáveis de contexto ref têm de ser definidos antes da avaliação desta política.

Por exemplo, se um parâmetro uid precisar de obter o respetivo valor de uma variável denominada authn.uid, o elemento <Parameter> seria semelhante ao seguinte:

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

Se usar este atributo, não use o atributo value.
value Opcional String

Especifica um valor codificado para o parâmetro. Por exemplo, se um parâmetro denominado answer tiver o valor 42, o elemento <Parameter> seria semelhante ao seguinte:

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

Se usar este atributo, não use o atributo ref.

O parâmetro obtém o respetivo valor do atributo ref ou com um elemento value explícito.

Para ver um exemplo e mais informações, consulte o artigo Como devem ser usados os parâmetros opcionais na política de transformação XSL?.

<ResourceURL>

O ficheiro XSL que o Apigee usa para transformar a mensagem. O valor deste elemento é o nome da folha de estilos XSL armazenada no proxy de API em /resources/xsl.

Valor predefinido N/A
Obrigatório? Obrigatória
Tipo String
Elemento principal <XSL>
Elementos subordinados Nenhum

Por exemplo:

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

Para mais informações, consulte os ficheiros de recursos.

<Source>

Especifica a mensagem que é transformada. Normalmente, este valor é definido como request ou response, consoante a mensagem a transformar seja de entrada ou de saída.

Valor predefinido N/A
Obrigatório? Opcional
Tipo String
Elemento principal <XSL>
Elementos subordinados Nenhum

O ficheiro XSL que define a transformação é definido pelo elemento <ResourceURL>.

  • Se a origem estiver em falta, é tratada como uma mensagem simples. Por exemplo, <Source>message</Source>
  • Se não for possível resolver a variável de origem ou esta for resolvida como um tipo que não seja de mensagem, o passo de transformação falha.

Referência de erro

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.xsl.XSLSourceMessageNotAvailable 500 This error occurs if the message or string variable specified in the <Source> element of the XSLTransform policy is either out of scope (not available in the specific flow where the policy is being executed) or can't be resolved (is not defined).
steps.xsl.XSLEvaluationFailed 500 This error occurs if the input XML payload is unavailable/malformed or the XSLTransform policy fails/is unable to transform the input XML file based on the transformation rules provided in the XSL file. There could be many different causes for the XSLTransform policy to fail. The reason for failure in the error message will provide more information on the cause.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
XSLEmptyResourceUrl If the <ResourceURL> element in the XSLTransform policy is empty, then the deployment of the API proxy fails.
XSLInvalidResourceType If the resource type specified in the <ResourceURL> element of the XSLTransform policy is not of type xsl, then the deployment of the API proxy fails.

Tópicos relacionados