Política RaiseFault

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

Veja a documentação do Apigee Edge.

O quê

Gera uma mensagem personalizada em resposta a uma condição de erro. Use RaiseFault para definir uma resposta de erro que é devolvida à app que está a fazer o pedido quando surge uma condição específica.

Esta política é uma política padrão e pode ser implementada em qualquer tipo de ambiente. Para obter informações sobre os tipos de políticas e a disponibilidade com cada tipo de ambiente, consulte Tipos de políticas.

Para obter informações gerais sobre o processamento de falhas, consulte o artigo Processamento de falhas.

Amostras

Return FaultResponse

Na utilização mais comum, o elemento RaiseFault é usado para devolver uma resposta de falha personalizada à app que fez o pedido. Por exemplo, esta política devolve um código de estado 404 sem payload:

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

Devolve o payload FaultResponse

Um exemplo mais complexo envolve a devolução de uma carga útil de resposta de falha personalizada, juntamente com cabeçalhos HTTP e um código de estado HTTP. No exemplo seguinte, a resposta de falha é preenchida com uma mensagem XML que contém o código de estado HTTP recebido pelo Apigee do serviço de back-end e um cabeçalho que contém o tipo de falha ocorrida:

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact [e-mail]</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Para ver uma lista de todas as variáveis disponíveis para preencher dinamicamente mensagens FaultResponse, consulte a referência de variáveis

Resolva problemas com erros de pedidos de lances de serviços

Exemplo: Aprenda com a prática!
Este exemplo do Learn Apigee mostra como verificar o código HTTP numa resposta ServiceCallout e gerar uma exceção personalizada com base no valor do código. O exemplo devolve uma mensagem de erro personalizada quando o serviço de destino devolve um estado 404. Basta clonar o repositório e seguir as instruções nesse tópico. O exemplo ilustra um padrão comum para processar erros de pedidos de lances de serviços. .

---

Acerca da política RaiseFault

O Apigee permite-lhe realizar o processamento de exceções personalizado através de uma política do tipo RaiseFault. A política RaiseFault, que é semelhante à política AssignMessage, permite-lhe gerar uma resposta de falha personalizada em resposta a uma condição de erro.

Use a política RaiseFault para definir uma resposta de falha que é devolvida à app que está a fazer o pedido quando surge uma condição de erro específica. A resposta de falha pode consistir em cabeçalhos HTTP, parâmetros de consulta e uma carga útil de mensagem. Uma resposta de falha personalizada pode ser mais útil para os programadores de apps e os utilizadores finais de apps do que as mensagens de erro genéricas ou os códigos de resposta HTTP.

Quando executada, a política RaiseFault transfere o controlo do fluxo atual para o fluxo de erro, que devolve a resposta de falha designada à app cliente solicitante. Quando o fluxo de mensagens muda para o fluxo de erro, não ocorre mais processamento de políticas. Todos os passos de processamento restantes são ignorados e a resposta de falha é devolvida diretamente à app que fez o pedido.

Pode usar o RaiseFault num ProxyEndpoint ou num TargetEndpoint. Normalmente, anexa uma condição à política RaiseFault. Após a execução de RaiseFault, o Apigee realiza o processamento de falhas normal, avaliando as FaultRules ou, se não existirem regras de falhas definidas, termina o processamento do pedido.

Referência do elemento

A referência de elementos descreve os elementos e os atributos da política RaiseFault.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

Atributos <RaiseFault>

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <IgnoreUnresolvedVariables>

(Opcional) Ignora qualquer erro de variável não resolvido no fluxo. Valores válidos: verdadeiro/falso. Predefinição true.

Elemento <FaultResponse>

(Opcional) Define a mensagem de resposta devolvida ao cliente que está a fazer o pedido. FaultResponse usa as mesmas definições que a política AssignMessage.

Elemento <FaultResponse><AssignVariable>

Atribui um valor a uma variável do fluxo de destino. Se a variável de fluxo não existir, o elemento AssignVariable cria-a.

Por exemplo, use o seguinte código para definir a variável denominada myFaultVar na política RaiseFault:

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

Em seguida, pode consultar essa variável nos modelos de mensagens mais tarde na política RaiseFault. Além disso, uma política anexada a uma FaultRule pode, então, aceder à variável. Por exemplo, a política AssignMessage seguinte usa a variável definida em RaiseFault para definir um cabeçalho na resposta de falha:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</AssignMessage>

<AssignVariable> na política RaiseFault usa a mesma sintaxe que o elemento <AssignVariable> na política AssignMessage.

Elemento <FaultResponse><Add>/<Headers>

Adiciona cabeçalhos HTTP à mensagem de erro. Tenha em atenção que o cabeçalho vazio <Add><Headers/></Add> não adiciona nenhum cabeçalho. Este exemplo copia o valor da variável de fluxo request.user.agent para o cabeçalho.

O elemento <Header> suporta a funcionalidade de substituição de strings dinâmicas denominada modelos de mensagens.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

Predefinição:	N/A
Presença:	Opcional
Tipo:	String

<FaultResponse><Copy> element

Copia informações de da mensagem especificada pelo atributo source para a mensagem de erro.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
    </Copy>

Predefinição:	N/A
Presença:	Opcional
Tipo:	String

Atributos

 <Copy source="response">

Atributo	Descrição	Presença	Tipo
fonte	Especifica o objeto de origem da cópia. Se source não for especificado, é tratado como uma mensagem simples. Por exemplo, se a política estiver no fluxo de pedidos, a origem é predefinida como o objeto request. Se a política estiver no fluxo de resposta, é predefinida para o objeto response. Se omitir source, pode usar uma referência absoluta a uma variável de fluxo como a origem da cópia. Por exemplo, especifique o valor como {request.header.user-agent}. Se a variável de origem não puder ser resolvida ou for resolvida para um tipo que não seja de mensagem, o comando <Copy> não responde.	Opcional	String

Elemento <FaultResponse><Copy>/<Headers>

Copia o cabeçalho HTTP especificado da origem para a mensagem de erro. Para copiar todos os cabeçalhos, especifique <Copy><Headers/></Copy>.

<Copy source='request'>
    <Headers>
        <Header name="headerName"/>
    </Headers>
</Copy>

Se existirem vários cabeçalhos com o mesmo nome, use a seguinte sintaxe:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

Este exemplo copia "h1", "h2" e o segundo valor de "h3". Se "h3" tiver apenas um valor, não é copiado.

Predefinição:	N/A
Presença:	Opcional
Tipo:	String

Elemento <FaultResponse><Copy>/<StatusCode>

O código de estado HTTP a copiar do objeto especificado pelo atributo source para a mensagem de erro.

<Copy source='response'>
    <StatusCode>404</StatusCode>
</Copy>

Predefinição:	falso
Presença:	Opcional
Tipo:	String

Elemento <FaultResponse><Remove>/<Headers>

Remove os cabeçalhos HTTP especificados da mensagem de erro. Para remover todos os cabeçalhos, especifique <Remove><Headers/></Remove>. Este exemplo remove o cabeçalho user-agent da mensagem.

<Remove>
    <Headers>
        <Header name="user-agent"/>
    </Headers>
</Remove>

Se existirem vários cabeçalhos com o mesmo nome, use a seguinte sintaxe:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

Este exemplo remove "h1", "h2" e o segundo valor de "h3". Se "h3" tiver apenas um valor, não é removido.

Predefinição:	N/A
Presença:	Opcional
Tipo:	String

<FaultResponse><Set> element

Define informações na mensagem de erro.

Os subelementos de <Set> suportam a funcionalidade de substituição de strings dinâmicas denominada modelos de mensagens.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
    </Set>

Predefinição:	N/A
Presença:	Opcional
Tipo:	N/A

Elemento <FaultResponse>/<Set>/<Headers>

Define ou substitui os cabeçalhos HTTP na mensagem de erro. Tenha em atenção que o cabeçalho vazio <Set><Headers/></Set> não define nenhum cabeçalho. Este exemplo define o cabeçalho user-agent para a variável de mensagem especificada com o elemento <AssignTo>.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>
    </Headers>
</Set>

Predefinição:	N/A
Presença:	Opcional
Tipo:	String

Elemento <FaultResponse>/<Set>/<Payload>

Define o payload da mensagem de erro.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Defina um payload JSON:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

Num payload JSON, pode inserir variáveis através dos atributos variablePrefix e variableSuffix com carateres delimitadores, conforme mostrado no exemplo seguinte.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

Em alternativa, a partir da versão na nuvem 16.08.17, também pode usar chavetas para inserir variáveis:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Defina uma carga útil mista em XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

Predefinição:
Presença:	Opcional
Tipo:	String

Atributos

 <Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

Atributo	Descrição	Presença	Tipo
contentType	Se contentType for especificado, o respetivo valor é atribuído ao cabeçalho Content-Type.	Opcional	String
variablePrefix	Especifica opcionalmente o delimitador inicial numa variável de fluxo, uma vez que as cargas úteis JSON não podem usar o caráter "{" predefinido.	Opcional	Char
variableSuffix	Especifica opcionalmente o delimitador final numa variável de fluxo porque as cargas úteis JSON não podem usar o caráter "}" predefinido.	Opcional	Char

Elemento <FaultResponse>/<Set>/<StatusCode>

Define o código de estado da resposta.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

Predefinição:	falso
Presença:	Opcional
Tipo:	Booleano

Elemento <ShortFaultReason>

Especifica a apresentação de um breve motivo de falha na resposta:

<ShortFaultReason>true|false</ShortFaultReason>

Por predefinição, o motivo da falha na resposta da política é:

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Para tornar a mensagem mais legível, pode definir o elemento <ShortFaultReason> como verdadeiro para abreviar o faultstring apenas para o nome da política:

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Valores válidos: true/false(predefinição).

Predefinição:	falso
Presença:	Opcional
Tipo:	Booleano

Variáveis de fluxo

As variáveis de fluxo permitem o comportamento dinâmico das políticas e dos fluxos no tempo de execução, com base nos cabeçalhos HTTP, no conteúdo das mensagens ou no contexto do fluxo. As seguintes variáveis de fluxo predefinidas estão disponíveis após a execução de uma política RaiseFault. Para mais informações sobre as variáveis de fluxo, consulte a Referência de variáveis.

Variável	Tipo	Autorização	Descrição
fault.name	String	Só de leitura	Quando a política RaiseFault é executada, esta variável é sempre definida como a string RaiseFault.
fault.type	String	Só de leitura	Devolve o tipo de falha no erro e, se não estiver disponível, uma string vazia.
fault.category	String	Só de leitura	Devolve a categoria de falha no erro e, se não estiver disponível, uma string vazia.

Exemplo de utilização de RaiseFault

O exemplo seguinte usa uma condição para aplicar a presença de um queryparam com o nome zipcode no pedido de entrada. Se esse queryparam não estiver presente, o fluxo gera uma falha através de RaiseFault:

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>

A imagem seguinte ilustra o que estaria em RaiseFault:

<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
    </Set>
  </FaultResponse>
</RaiseFault>

Referência de erro

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code	HTTP status	Cause
steps.raisefault.RaiseFault	500	See fault string.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name = "RaiseFault"
raisefault.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	raisefault.RF-ThrowError.failed = true

Example error response

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

Esquema

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de políticas estão disponíveis no GitHub.

Tópicos relacionados

Consulte o artigo Processamento de falhas