Política RaiseFault

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

Confira a documentação da Apigee Edge.

Ícone da política

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. Nem todos os usuários têm necessidade de saber sobre os tipos de política e 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 support@company.com</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

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 Presença
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:

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

 verdadeiro Opcional
async

Esse atributo está obsoleto.

 falso 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.
Presença 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.

<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 Presença 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:

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

    <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 Presença 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:

 falso

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:

 falso

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

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