Política RaiseFault

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

O que

Gera uma mensagem personalizada em resposta a uma condição de erro. Use "Raise Fault" para definir uma resposta de falha que é retornada ao app solicitante quando ocorre uma condição específica.

Para informações gerais sobre como lidar com falhas, consulte Como lidar com falhas.

Amostras

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Sobre a política RaiseFault

O Apigee Edge permite que você execute o tratamento de exceções personalizado usando uma política do tipo IncreaseFault. A política ElevateFault, que é semelhante à política AtribuirMessage, permite 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 retornada ao aplicativo solicitante quando surgir uma condição de erro específica. A resposta de falha pode consistir em cabeçalhos HTTP, parâmetros de consulta e um payload de mensagem. Uma resposta de falha personalizada pode ser mais útil para desenvolvedores de apps e usuários finais do app do que mensagens de erro genéricas ou códigos de resposta HTTP.

Quando executada, a política RaiseFault transfere controle do fluxo atual para o fluxo de erros, que retorna a resposta de falha designada para o aplicativo cliente solicitante. Quando o fluxo de mensagens muda para o fluxo de erros, nenhum outro processamento de política ocorre. Todas as etapas de processamento restantes serão ignoradas, e a resposta de falha será retornada diretamente para o app solicitante.

Você pode usar RaiseFault em um ProxyEndpoint ou um TargetEndpoint. Normalmente, você anexa uma Condition à política RaiseFault. Depois que RaiseFault é executada, a Apigee realizará o processamento de falhas normal, a avaliação de FaultRules ou, se não houver regras de falha definidas, encerrará o processamento da solicitação.

Referência de elemento

A referência de elementos descreve os elementos e 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/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

Atributos de <RaiseFault>

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

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Elemento <IgnoreUnresolvedVariables>

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

Elemento <FaultResponse>

(Opcional) Define a mensagem de resposta retornada ao cliente solicitante. O FaultResponse usa As mesmas configurações da políticaAssignMessage (não disponível no Apigee Edge para nuvem privada).

Elemento <FaultResponse><AssignVariable>

Atribui um valor a uma variável de fluxo de destino. Se a variável de fluxo não existir, a AssignVariable a criará.

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

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

Você pode consultar essa variável em modelos de mensagens posteriormente na política RaiseFault. Além disso, uma política anexada a uma FaultRule pode acessar a variável. Por exemplo, a seguinte política AssignMessage 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>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> na política RaiseFault utiliza a mesma sintaxe do elemento <AssignVariable> na política AssignMessage. Essa funcionalidade não está disponível atualmente no Apigee Edge para nuvem privada.

Elemento {FaultResponse} {/ 0}

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

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

Elemento <FaultResponse><Copy>

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

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

Atributos

 <Copy source="response">

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 houver 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, ele não será copiado.

Elemento <FaultResponse><Copy>/<StatusCode>

O código de status HTTP a ser copiado do objeto especificado pelo atributo de origem para a mensagem de erro.

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

Elemento {FaultResponse} {XCop} / {/ 0}

A descrição do motivo a ser copiado do objeto especificado pelo atributo de origem para a mensagem de erro.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

Elemento <FaultResponse><Remove>/<Headers>

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

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

Se houver 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, ele não será removido.

Elemento <FaultResponse><Set>

Define as informações na mensagem de erro.

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

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

Define ou substitui os cabeçalhos HTTP na mensagem de erro. Observe 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 da mensagem especificada com o elemento <AssignTo>.

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

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>

Em um payload JSON, é possível inserir variáveis usando os atributos variablePrefix e variableSuffix com caracteres delimitadores, conforme mostrado no exemplo a seguir.

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

Ou, a partir da versão 16.08.17 da nuvem, também é possível usar chaves para inserir variáveis:

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

Definir um payload misto em XML:

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

Atributos

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

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

Define o código de status da resposta.

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

<FailResponse>/<Set>/<ReasonPhrase>

Define a frase do motivo da resposta.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

Elemento <ShortFaultReason>

Especifica a exibição de um motivo curto de falha na resposta:

<ShortFaultReason>true|false</ShortFaultReason>

Por padrã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, defina o elemento <ShortFaultReason> como verdadeiro para reduzir o faultstring apenas para o nome da política:

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

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

Variáveis de fluxo

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

Exemplo de uso de RaiseFault

O exemplo a seguir usa uma condição para aplicar a presença de um queryparam com o nome zipcode na solicitação de entrada. Se esse queryparam não estiver presente, o fluxo gerará uma falha por meio 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>

<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>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

Referência de erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge 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.

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.

Example error response

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

Schema

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

Temas relacionados

Consulte Como lidar com falhas.