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

Retornar FaultResponse

No uso mais comum, RaiseFault é usado para retornar uma resposta de falha personalizada ao aplicativo solicitante. Por exemplo, esta política retornará um código de status 404 sem payload:

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

Payload de retorno de FaultResponse

Um exemplo mais complexo envolve retornar um payload de resposta a falhas personalizado, além de cabeçalhos HTTP e um código de status HTTP. No exemplo a seguir, a resposta de falha é preenchida com uma mensagem XML contendo o código de status HTTP recebido pela Apigee do serviço de back-end e um cabeçalho contendo o tipo de falha que ocorreu:

<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 de FaultResponse, consulte Referência de variáveis

Processar erros de chamada de serviço

Exemplo: aprenda fazendo!
Este exemplo de Aprenda a Apigee mostra como verificar o código HTTP em uma resposta ServiceCallout e lançar uma exceção personalizada com base no valor do código. O exemplo retorna uma mensagem de erro personalizada quando o serviço de destino retorna um status 404. Basta clonar o repositório e seguir as instruções nesse tópico. O exemplo ilustra um padrão comum para lidar com erros de chamada de serviço. .

---

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:

Atributo	Descrição	Padrão	Presence
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	false	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional
async	Esse atributo está obsoleto.	false	Descontinuado

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>

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo name da política.
Presence	Opcional
Tipo	String

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.

O elemento <Header> é compatível com o recurso de substituição de strings dinâmicas chamado modelo de mensagem.

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

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

Elemento <FaultResponse><Copy>

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

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

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

Atributos

 <Copy source="response">

Atributo	Descrição	Presence	Tipo
fonte	Especifica o objeto de origem da cópia. Se não for especificado, source será tratada como uma mensagem simples. Por exemplo, se a política estiver no fluxo de solicitações, a origem será padrão para o objeto request. Se a política estiver no fluxo de resposta, o padrão será o objeto response. Se você omitir a source, poderá 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 resolvida para um tipo não mensagem, <Copy> não responderá.	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 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.

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

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>

Padrão:	false
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>. 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.

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

Elemento <FaultResponse><Set>

Define as informações na mensagem de erro.

Os subelementos de <Set> são compatíveis com o recurso de substituição de string dinâmica chamado modelo de mensagem.

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

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

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>

Padrã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>

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>

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

Atributos

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

Atributo	Descrição	Presence	Tipo
contentType	Se contentType for especificado, o valor dele será atribuído ao cabeçalho Content-Type.	Opcional	String
variablePrefix	Opcionalmente, especifica o delimitador inicial em uma variável de fluxo porque os payloads JSON não podem usar o caractere "{" padrão.	Opcional	Caracteres
variableSuffix	Opcionalmente, especifica o delimitador à direita em uma variável de fluxo porque os payloads JSON não podem usar o caractere "}" padrão.	Opcional	Caracteres

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

Define o código de status da resposta.

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

Padrão:	false
Presença:	Opcional
Tipo:	Booleano

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

Padrão:	false
Presença:	Opcional
Tipo:	Booleano

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.

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

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>

TO exemplo a seguir ilustra o que seria 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 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.

Código de falha	Status HTTP	Causa
steps.raisefault.RaiseFault	500	Consulte string de falha.

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.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name = "RaiseFault"
raisefault.policy_name.failed	policy_name é o nome da política especificada pelo usuário que gerou a falha.	raisefault.RF-ThrowError.failed = true

Exemplo de resposta de erro

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

{
   "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.