Política de XSLTransform

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

Confira a documentação da Apigee Edge.

Conteúdo

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.

Observação: esta política só transforma XML se o cabeçalho Content-Type na mensagem a ser transformada estiver definido em XML. Por exemplo, text/xml ou application/xml.

Observação: a política de transformação do XSL não oferece suporte à leitura, ao carregamento ou à manipulação de entidades externas XML (XXEs).

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>

Observação: <xsl:include> e <xsl:import> não são compatíveis.

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

Amostra: veja nossas amostras de repositório do GitHub para os esquemas mais recentes.

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.

Precisa de ajuda para resolver um erro? Clique em ao lado da descrição do erro para visitar a página de solução de problemas.

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

• jira-release-notes
• paginação
• soap