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

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. É importante conhecer estas informações se estiver a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte os artigos O que precisa de saber sobre erros de políticas e Como processar falhas.

Erros de tempo de execução

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

Código de falha	Estado de HTTP	Causa
steps.raisefault.RaiseFault	500	Veja a string de falha.

Erros de implementação

Nenhum.

Variáveis de falha

Estas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte o artigo O que precisa de saber sobre os erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo 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 especificado pelo utilizador da política que gerou a falha.	raisefault.RF-ThrowError.failed = true

Exemplo de resposta de erro

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque 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íticas estão disponíveis no GitHub.

Tópicos relacionados

Consulte o artigo Processamento de falhas