Política de XSLTransform

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Ícone da política

O que

A política XSLTransform aplica transformações da linguagem de folha de estilo extensível (XSLT, na sigla em inglês) a mensagens XML, permitindo transformá-las do XML para outro formato, como XML, HTML ou texto simples. Geralmente, a política é usada para integrar aplicativos compatíveis com XML, mas que exigem formatos XML diferentes para os mesmos dados.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Entradas

A política XSL usa as seguintes entradas:

  • (Obrigatório) O nome de uma folha de estilo XSLT, que contém um conjunto de regras de transformação armazenadas no proxy de API em /resources/xsl.
  • (Obrigatório) XML a ser transformado (normalmente uma mensagem de solicitação 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

A Apigee depende do processador Saxon XSLT (em inglês) e é compatível com XSLT 1.0 e 2.0.

Elementos XSL não compatíveis

A política XSL não é compatível com os seguintes elementos XSL:

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

Amostras

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

Política de XSL ->

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

Política simples de XSL. Vá para o próximo exemplo para ver a folha de estilo XSLT referenciada na política (my_transform.xsl). O elemento <Source> é importante. Por exemplo, se o XML que você quer transformar estiver na resposta, a transformação não ocorrerá a menos que você defina <Source> como response (e a política esteja anexada ao fluxo de resposta). Mas, nesse caso, o XML a ser transformado está na solicitação.

Folha de estilo 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 estilo my_transform.xsl referenciada na política. Acesse a próxima amostra para ver um exemplo de uma mensagem XML recebida.

Mensagem ->

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

Exemplo de mensagem na solicitação (indicada no elemento <Source>request</Source> da política na primeira amostra).

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 após a folha de estilo XSLT dessas amostras é aplicada à mensagem XML.

Elemento <XSL>

Define uma política XSLTransform.

Valor padrão n/a
Obrigatório? Obrigatório
Tipo Objeto complexo
Elemento pai n/a
Elemento filho <OutputVariable>
<Parameters>
<ResourceURL>
<Source>

O elemento <XSL> tem os seguintes atributos:

Atributo Descrição Obrigatório? Tipo
name Nome da política. Os caracteres que podem ser usados no nome são restritos a: A-Z0-9._\-$ %. No entanto, a IU da Apigee impõe outras restrições, como a remoção automática de caracteres que não são alfanuméricos. Obrigatório String

Referência a elementos filhos

Esta seção descreve os elementos filhos de <XSL>.

<OutputVariable>

Uma variável que armazena a saída da transformação. Defina esse elemento como uma variável personalizada e consuma essa variável.

Valor padrão n/a
Obrigatório? Opcional
Tipo String
Elemento pai <XSL>
Elemento filho Nenhum

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

Para substituir o conteúdo da mensagem pelo resultado da transformação, exclua esse elemento. Por exemplo, se você estiver transformando uma mensagem para HTML, não inclua esse elemento.

<Parameters>

Adiciona compatibilidade com o elemento <xsl:param> nas suas folhas de estilo. Você define cada parâmetro como um elemento filho <Parameter> desse elemento.

Valor padrão n/a
Obrigatório? Opcional
Tipo Matriz de elementos <Parameter>
Elemento pai <XSL>
Elemento filho <Parameter>

O elemento <Parameters> tem os seguintes atributos:

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

<Parameter>

Define um parâmetro no elemento <Parameters>.

Valor padrão n/a
Obrigatório? Opcional
Tipo Objeto complexo
Elemento pai <Parameters>
Elemento filho Nenhum

O elemento <Parameter> tem os seguintes atributos:

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

O nome do parâmetro. A Apigee corresponde ao valor definido aqui com o valor do atributo name em um elemento <xsl:param> na folha de estilo.

Por exemplo, se você inserir um nome uid, seu XSL poderá ser parecido com este:

<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 precisam ser definidos antes da avaliação desta política.

Por exemplo, se um parâmetro uid precisar receber o valor de uma variável chamada authn.uid, o elemento <Parameter> será semelhante ao seguinte:

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

Se você usar esse atributo, não use o atributo value.

value Opcional String

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

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

Se você usar esse atributo, não use o atributo ref.

O parâmetro recebe o valor do atributo ref ou com um value explícito.

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

<ResourceURL>

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

Valor padrão n/a
Obrigatório? Obrigatório
Tipo String
Elemento pai <XSL>
Elemento filho Nenhum

Exemplo:

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

Para mais informações, consulte Arquivos de recursos.

<Source>

Especifica a mensagem que é transformada. Normalmente, esse valor é definido como request ou response, dependendo se a mensagem a ser transformada é de entrada ou de saída.

Valor padrão n/a
Obrigatório? Opcional
Tipo String
Elemento pai <XSL>
Elemento filho Nenhum

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

  • Se não houver uma origem, ela será tratada como uma mensagem simples. Exemplo: <Source>message</Source>
  • Se a variável de origem não puder ser resolvida ou resolvida para um tipo não mensagem, a etapa de transformação falhará.

Referência de erros

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Código de falha Status HTTP Causa Correção
steps.xsl.XSLSourceMessageNotAvailable 500 Esse erro ocorrerá se a variável da mensagem ou da string especificada no elemento <Source> da política XSLTransform estiver fora do escopo (não disponível no fluxo específico em que a política estiver sendo executada) ou não pode ser resolvido (não foi definido).
steps.xsl.XSLEvaluationFailed 500 Esse erro ocorrerá se o payload XML de entrada estiver indisponível/malformado ou se a política XSLTransform falhar/não puder transformar o arquivo XML de entrada com base nas regras de transformação fornecidas no arquivo XSL. Pode haver muitas causas diferentes para a falha da política XSLTransform. O motivo da falha na mensagem de erro fornecerá mais informações sobre a causa.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém essa política.

Nome do erro Causa Correção
XSLEmptyResourceUrl Se o elemento <ResourceURL> na política XSLTransform estiver vazio, a implantação do proxy da API falhará.
XSLInvalidResourceType Se o tipo de recurso especificado no elemento <ResourceURL> da política XSLTransform não for do tipo xsl, a implantação do proxy de API falhará.

Temas relacionados