Política RaiseFault

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

Confira a documentação da Apigee Edge.

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.

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

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>
   </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>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Sobre a política RaiseFault

A Apigee permite que você realize o tratamento personalizado de exceções usando uma política do tipo RaiseFault. A política RaiseFault, semelhante à política AssignMessage, 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/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <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. FaultResponse usa as mesmas configurações que a política AssignMessage.

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>
</AssignMessage>

<AssignVariable> na política RaiseFault utiliza a mesma sintaxe do elemento <AssignVariable> na política AssignMessage.

Elemento <FaultResponse><Add>/<Headers>

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

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

Referência de erros

Nesta seção, descrevemos os códigos de falha e as mensagens de erro retornadas e as variáveis com falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

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

Erros de implantação

Nenhum.

Variáveis de falha

Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Exemplo de resposta de erro

{
   "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ítica estão disponíveis no GitHub.

Temas relacionados

Consulte Como lidar com falhas.