Política XSLTransform

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

Veja a documentação do Apigee Edge.

O quê

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.

Nota: esta política transforma o XML apenas se o cabeçalho Content-Type na mensagem a ser transformada estiver definido como XML. Por exemplo, text/xml ou application/xml.

Nota: a política de transformação XSL não suporta a leitura, o carregamento nem a manipulação de entidades externas XML (XXEs).

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

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>

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

Nota: <xsl:include> e <xsl:import> não são suportados.

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 este 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 a partir do atributo ref ou com um 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.

Exemplo: consulte os exemplos do nosso repositório do GitHub para ver os esquemas mais recentes.

Referência de erro

Erros de tempo de execução

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

Código de falha	Estado de HTTP	Causa	Corrigir
steps.xsl.XSLSourceMessageNotAvailable	500	Este erro ocorre se a variável de mensagem ou string especificada no elemento <Source> da política XSLTransform estiver fora do âmbito (não disponível no fluxo específico onde a política está a ser executada) ou não puder ser resolvida (não estiver definida).
steps.xsl.XSLEvaluationFailed	500	Este erro ocorre se a carga útil XML de entrada estiver indisponível/com formato incorreto ou se a política XSLTransform falhar/não conseguir transformar o ficheiro XML de entrada com base nas regras de transformação fornecidas no ficheiro XSL. Podem existir várias causas diferentes para a falha da política XSLTransform. O motivo da falha na mensagem de erro fornece mais informações sobre a causa.

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Precisa de ajuda para resolver um erro? Clique em junto à descrição da causa do erro para visitar a página de resolução de problemas.

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

Tópicos relacionados

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