Como lidar com falhas

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

Muitas condições de erro podem surgir enquanto os proxies da API estão atendendo as solicitações dos aplicativos. Por exemplo, os proxies de API podem encontrar problemas de rede ao se comunicar com serviços de back-end, aplicativos podem apresentar credenciais expiradas, mensagens de solicitação podem estar formatadas incorretamente e assim por diante.

Quando ocorre um erro depois que um aplicativo cliente chama um proxy de API, uma mensagem de erro é retornada ao cliente. Por padrão, o cliente recebe uma mensagem de erro criptiva frequentemente sem detalhes ou orientação. Mas se você quiser substituir as mensagens de erro padrão por outras mais úteis e ou até mesmo enriquecê-los com coisas como cabeçalhos HTTP adicionais, você precisa configurar uma falha no Edge.

O tratamento de falhas personalizado também permite que você adicione funcionalidades, como a geração de registros de mensagens, sempre que ocorrer um erro.

Antes de falar sobre a implementação de tratamento de erros personalizados nos proxies de API, é útil entender como os erros ocorrem e como os proxies de API reagem a eles.

Vídeos

Assista os vídeos abaixo para saber mais sobre como lidar com falhas.

Como ocorrem os erros

Primeiro, vamos abordar como os erros ocorrem. Saber como os erros ocorrem ajuda você a planejar as diferentes situações em quer implementar o tratamento de erros personalizado.

Erros automáticos

Um proxy de API gera um erro automaticamente nas seguintes situações:

• Uma política gera um erro. Por exemplo, se uma chamada de API envia uma chave expirada, a política VerifyAPIKey gera um erro automaticamente. ou se o número de chamadas de API exceder um determinado limite, a política de cotas ou a política de API do SpikeArrest gera um erro. Consulte a referência de erro de política para ver os tipos de erros que as políticas podem gerar.
• Há um problema no fluxo de mensagens do proxy da API, como um erro de roteamento.
• Há uma falha de back-end, como um erro HTTP devido a falhas no nível do protocolo, erros TLS/SSL ou um serviço de destino indisponível.
• Há uma falha no nível do sistema, como uma exceção de falta de memória.

Para mais informações sobre esses erros, consulte taxonomia de falhas neste tópico.

Erros personalizados

Para situações em que não há um erro automático, é recomendável gerar um erro personalizado. Por exemplo, se uma resposta contiver a palavra "indisponível" ou se o código de status HTTP for maior que 201. Para isso, adicione uma política crescente para o local apropriado em um fluxo de proxy de API.

É possível adicionar uma política RaiseFault a um fluxo de proxy da API, assim como você faz com qualquer outra política. No exemplo de configuração de proxy a seguir, a política Raise-Fault-1 é anexada à resposta TargetEndpoint. Se a palavra "indisponível" estiver presente na resposta do serviço de destino, a política RaisFault será executada e gerará um erro.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

Isso é apenas para mostrar que é possível lançar erros personalizados. Temos mais detalhes sobre a política IncrementFault na seção FailRules x vs. A política Atault (em inglês).

Para ver mais exemplos, consulte estas postagens nos Fóruns da comunidade da Apigee:

• Como fazer referência a variáveis JavaScript no raisFault

O que os proxies de API fazem quando ocorrem erros

Veja o que acontece quando um proxy gera um erro.

Sair do pipeline de proxy

Quando um proxy de API encontra um erro, independentemente de como ele ocorre, ele sai do pipeline de fluxo normal, insere um estado de erro e retorna uma mensagem de erro ao aplicativo cliente. Depois que o proxy da API entra no estado de erro, ele não pode retornar o processamento para o pipeline de fluxo normal.

Por exemplo, suponha que um proxy de API tenha políticas na seguinte ordem na solicitação ProxyEndpoint:

1. VerifyAPIKey
2. Cota
3. JSONtoXML

Se ocorrer um erro durante a verificação da chave de API, o proxy da API passará para um estado de erro. As políticas Quota e JSON para XML não são executadas, o proxy não segue para o TargetEndpoint, e uma mensagem de erro é retornada para o aplicativo cliente.

Verificar se há FaultRules

No estado do erro, os proxies da API também verificam a presença dos itens a seguir (na ordem) na configuração do proxy da API antes de retornar uma mensagem de erro padrão para o aplicativo cliente:

1. Uma seção <FaultRules>, que contém a lógica para acionar mensagens de erro personalizadas (e outras políticas) com base em condições específicas definidas por você.
2. Uma seção <DefaultFaultRule>, que aciona uma mensagem de erro padrão nas seguintes situações:
   • Nenhum <FaultRules> foi definido.
   • Nenhum <FaultRules> é executado.
   • O elemento <AlwaysEnforce> é definido como verdadeiro.

Em essência, o proxy de API oferece a oportunidade de retornar uma mensagem de erro personalizada e acionar outra lógica. Se o proxy não encontrar nenhuma dessas seções, ou elas existirem, mas não houver for acionada, o proxy enviará a própria mensagem padrão gerada pelo Edge.

Exemplo simples de tratamento de falhas

Comece com um exemplo simples, em que uma chamada para um proxy de API não contém uma chave de API obrigatória. Por padrão, a resposta a seguir é retornada ao app cliente:

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

Os usuários da API podem descobrir a mensagem de erro, mas não podem. E muitos erros padrão são mais sutis e mais difíceis de decifrar.

Como um desenvolvedor de API, cabe a você alterar essa mensagem para atender às necessidades de quem receberá a mensagem de erro, seja um desenvolvedor de apps para iOS ou um grupo de teste interno com formato de mensagem de erro próprio. para a instalação.

Veja um exemplo básico de como você pode criar uma mensagem de erro personalizada para tratar desse erro. Isso requer 1) uma política que define a mensagem personalizada e 2) uma FaultRule que executa a política quando o proxy entra em um estado de erro.

1. Crie uma política que defina a mensagem personalizada

Primeiro, crie uma política que define a mensagem de erro personalizada. Use qualquer tipo de política, como uma política AssignMessage, que pode definir um payload e cabeçalhos HTTP opcionais, como o código do status e a frase de motivo. A opção "Atribuir mensagem" é ideal para isso. Ele permite que você controle o payload da mensagem, defina um código de status HTTP diferente, defina uma frase de razão HTTP diferente e adicione cabeçalhos HTTP.

Não anexe a política a nenhum fluxo no proxy da API. É suficiente que ele exista no pacote de proxy. Para fazer isso no editor de proxy da interface de gerenciamento, vá para a guia Desenvolver e no Painel de navegação e clique no ícone + na barra de políticas.

Isso permite criar uma política sem anexá-la a um fluxo no proxy da API. Uma política que não está anexada a nenhum fluxo é marcada com o ícone "desanexado" na lista "Políticas", conforme mostrado adjacente à política de mensagens de chave da API mostrada na figura anterior.

Veja a seguir um exemplo de política da Atribuição de mensagem que:

• Retorna uma mensagem JSON.
• Define um código de status HTTP (911, que é um código de status inexistente inexistente) para ilustrar a flexibilidade que você tem. O código de status aparece no cabeçalho HTTP.
• Define uma frase de razão HTTP (para substituir a frase de motivo "Não autorizado" padrão para este erro de chave de API ausente). A frase do motivo aparece ao lado do código de status no cabeçalho HTTP.
• Cria e preenche um novo cabeçalho HTTP chamado invalidKey.

<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

Quando essa política for executada, a resposta ao app cliente será semelhante à seguinte. Compare-o com a resposta padrão mostrada anteriormente.

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

Sim, é um pouco bobo, mas mostra o que é possível. Agora, pelo menos, o desenvolvedor que recebe a mensagem sabe que ele se esqueceu de incluir uma chave de API como um parâmetro de consulta.

Mas como essa política é executada? A próxima seção mostra você.

2. Crie a <FaultRule> que acionará a política

Nas seções <ProxyEndpoint> ou <TargetEndpoint> da configuração do proxy, você adicionará um bloco XML <FaultRules> que contém uma ou mais seções individuais <FaultRule>. Cada FaultRule representa um erro diferente que você quer processar. Neste exemplo simples, usaremos apenas uma FaultRule para mostrar do que ela é composta.

Também é necessário adicionar um <DefaultFaultRule> para fornecer uma mensagem de erro geral personalizada se nenhuma das FaultRules for executada.

Exemplo

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Pontos principais

• As FaultRules são definidas no ProxyEndpoint. Isso é importante Mais informações sobre como inserir FaultRules no ProxyEndpoint x TargetEndpoint mais tarde.
• <Name>: o nome da política a ser executada. O nome vem do atributo name da política no elemento pai, conforme mostrado no exemplo da política anteriormente.

• <Condition>: o Edge avalia a condição e executa a política somente se a condição for verdadeira. Se houver várias FaultRules avaliar como verdadeiro, o Edge executará a primeira que for verdadeira. (Importantes: a ordem em que as FaultRules são avaliadas, de cima para baixo ou de baixo para cima, difere entre o TargetEndpoint e o ProxyEndpoint, conforme descrito na Várias lógicas FaultRules e lógica de execução.) Se você não incluir uma condição, a FaultRule será automaticamente verdadeira. Mas essa não é uma prática recomendada. Cada FaultRule precisa ter a própria condição.

• <DefaultFaultRule>: se nenhuma FaultRule personalizada for executado, o <DefaultFaultRule> é executado, enviando uma resposta mensagem personalizada em vez da mensagem criptografada padrão gerada pelo Edge. Um <DefaultFaultRule> também pode ter um <Condition>, mas, na maioria dos casos, você não incluirá um, porque quer que ele seja executado independentemente do último recurso.

  Normalmente, a DefaultFaultRule é usada para retornar uma mensagem de erro genérica de qualquer erro inesperado. Um exemplo seria uma mensagem contendo informações de contato para suporte técnico. Essa resposta padrão tem a finalidade dupla de fornecer informações amigáveis ao desenvolvedor e também ofuscar URLs de back-end ou outras informações que possam ser usadas para comprometer o sistema.

Várias lógicas FaultRules e de execução

Na seção Exemplo de tratamento de falhas simples, usamos um exemplo simples de uma única FaultRule e condição. Em um projeto de API real, com todos os possíveis erros que podem ocorrer, é provável que você tenha várias FaultRules e uma DefaultFaultRule em <ProxyEndpoint> e <TargetEndpoint>. No entanto, apenas uma falha FailRule é executada quando um proxy da API entra em um estado de erro.

Esta seção descreve a lógica que o Edge usa ao lidar com FaultRules, desde como ele chega ao uma única FaultRule executada como Condições de etapa são tratadas quando a FaultRule é acionada. Esta seção também fornece orientações sobre quando definir as falhas com falha em <ProxyEndpoint> vs. <TargetEndpoint> e descreve a relação entre FaultRules e a política crescente.

Execução de FaultRules

Em resumo, esta é a lógica que o Edge usa quando um proxy de API entra em um estado de erro. Observe que há uma pequena diferença entre a avaliação das FaultRules no ProxyEndpoint em comparação com o TargetEndpoint.

1. O Edge avalia as FaultRules no ProxyEndpoint ou no TargetEndpoint, dependendo onde o erro ocorreu:
   • ProxyEndpoint: o Edge começa com inferior <FaultRule> no XML de configuração e avança, avaliando o <Condition> de cada <FaultRule> (o "externo" e não a "interna", <Step>).
   • TargetEndpoint: o Edge começa com o topo <FaultRule> no XML de configuração e vai até o final, avaliando o <Condition> de cada <FaultRule> (o "externo" e não a "interna", <Step>).
2. Executa a primeira FaultRule com condição "true". Se uma FaultRule não tiver condição, ela será verdadeira por padrão.
   • Quando um ANRRule é executado, todas as etapas dentro da FailRule são avaliadas em ordem, de cima para baixo na configuração XML. Etapas sem condições são executadas automaticamente (as políticas são executadas) e as etapas que têm um <Condition> que é avaliado como "true" são executadas (condições que avaliam como "false" não são executadas).

   • Se uma FaultRule é executada, mas nenhuma etapa da FaultRule é executada (porque for avaliada como "false"), a mensagem de erro padrão gerada pelo Edge será retornada ao app cliente. O <DefaultFaultRule> não é executado, porque o Edge já executou sua única FaultRule.

3. Se nenhuma FaultRule for executada, o Edge executará a <DefaultFaultRule>, presente.

Veja a seguir exemplos com comentários in-line.

Execução do ProxyEndpoint

A avaliação de ProxyEndpoint FaultRules é de baixo para cima. Portanto, comece a ler na última FaultRule na amostra a seguir e a seguir. Observe a DefaultFaultRule por último.

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not 
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Execução de TargetEndpoint

A avaliação de TargetEndpoint FaultRules é de cima para baixo. Portanto, comece a ler na primeira FaultRule da amostra a seguir e siga as etapas abaixo. Observe a DefaultFaultRule por último.

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE. 
     A policy did not throw a FailedToResolveAPIKey error. 
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed. 
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer" 
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without 
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed. 
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Falha na ordem das regras

Como você pode ver no exemplo anterior, a ordem em que você coloca as FaultRules é importante dependendo se o erro ocorre no ProxyEndpoint em relação ao TargetEndpoint.

Exemplo:

Políticas a serem incluídas

Você pode executar qualquer política de uma FaultRule colocando-a em Etapas. Por exemplo, é possível executar uma política AssignMessage para formatar uma resposta para o app cliente e, em seguida, registrar uma mensagem com a política MessageLogging. As políticas são executadas na ordem em que você as coloca (de cima para baixo no XML).

As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError)

O cabeçalho pode parecer que se repete, mas há uma nuance específica em relação a um erro de proxy que faz com que um proxy de API entre em um estado de erro ou não inserir um estado de erro: o continueOnError em uma política.

Para recapitular: um proxy de API avalia <FaultRules> e <DefaultFaultRule> somente se o proxy tiver entrado em um estado de erro. Isso significa que, mesmo que uma condição FaultRule seja avaliada como verdadeira, ela não será acionada se o proxy não estiver em um estado de erro.

No entanto, aqui está um exemplo de erro e o proxy não está entrando em um estado de erro. Em qualquer política, você pode definir um atributo no elemento pai chamado continueOnError. Esse atributo é muito importante em relação ao tratamento de falhas, porque determina se o proxy entra ou não em um estado de erro se a política falhar. Na maioria dos casos, convém manter a continueOnError="false" padrão, que coloca o proxy em um estado de erro se a política falhar e seu tratamento de erros personalizados será acionado. No entanto, se continueOnError="true" (por exemplo, se você não quiser que a chamada de um serviço pare a execução do proxy), o proxy não entrará em um estado de erro, se a política falhar e o proxy não examinará suas FaultRules.

Para informações sobre como registrar erros quando continueOnError="true", consulte Como lidar com falhas de política no fluxo atual.

Onde definir FaultRules: ProxyEndpoint ou TargetEndpoint

Quando um proxy de API apresenta um erro, o erro ocorre em <ProxyEndpoint> (solicitação de ou com resposta ao aplicativo cliente) ou em <TargetEndpoint> (solicitação para ou da resposta do serviço de destino). Não importa onde ocorre quando o Edge procura por FaultRules.

Por exemplo, se um servidor de destino não estiver disponível (código de status HTTP 503), o proxy da API entrará em um estado de erro na resposta <TargetEndpoint>, e o fluxo de proxy de API normal não continue no <ProxyEndpoint>. Se você tiver um FailRules definido somente no <ProxyEndpoint>, ele não resolverá esse erro.

Veja outro exemplo. Se uma política RaiseFault na resposta <ProxyEndpoint> acionar um erro, uma FaultRule da <TargetEndpoint> não será executada.

FaultRules vs. a política RaiseFault

Regras de falha e a política RaiseFault podem aparecer de formas alternativas para realizar o tratamento de falhas e, em alguns aspectos, isso é verdade. Mas também funcionam juntas. Esta seção explica a relação entre as duas. Entender essa relação ajuda a projetar seu tratamento de falhas, especialmente se quiser usar as duas.

Para resumir:

• As regras de falha são sempre avaliadas quando um proxy de API entra em um estado de erro.

• A política RaiseFault é uma maneira de colocar um proxy de API em um estado de erro quando um erro não teria ocorrido de outra forma.

  Por exemplo, se você quiser gerar um erro se o código de status HTTP na resposta do serviço de destino for maior que 200, adicione uma política crescente para seu fluxo de respostas. Ele será parecido com:

  <TargetEndpoint name="default">
      <PreFlow name="PreFlow">
  ...
          <Response>
              <Step>
                  <Name>Raise-Fault-1</Name>
  <!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                  <Condition>(response.status.code GreaterThan "200")</Condition>
              </Step>
          </Response> 
  

  A política RaiseFault também envia uma mensagem de erro para o app cliente.

O que acontece quando uma política RaiseFault aciona um erro, o que coloca o proxy em um estado de erro, o que pode executar uma falha? É aqui que as coisas podem ficar um pouco complicadas. Se a política RaiseFault retornar uma mensagem de erro e uma FaultRule for acionada e retornar uma mensagem de erro, o que será retornado para o app cliente?

• Como a FaultRule ou a DefaultFaultRule é executada após a política RaiseFault, os dados de resposta da FaultRule vencem.
• Os dados de resposta da política RaiseFault (código de status, frase de motivo ou payload da mensagem) serão usados se esses dados não forem definidos pela FaultRule ou DefaultFaultRule.
• Se as políticas RaiseFault e FaultRule adicionarem cabeçalhos HTTP personalizados, ambos serão incluídos na resposta. Nomes de cabeçalho duplicados criam um cabeçalho com vários valores.

Veja um exemplo do que é definido por uma política RaisFault e uma FaultRule e o que é retornado ao aplicativo cliente. Os exemplos são projetados para ser conciso, não para práticas recomendadas.

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: woops,gremlins

Status Code: [none] 
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header: 
  errorNote: gremlins

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header: 
  errorNote: woops

Condições de criação

As condições são a chave para a execução da FaultRule. As condições FaultRule são criadas da mesma forma feitas para outras condições no Edge, como para fluxos condicionais ou condições

Para colocar o restante desta seção no contexto, confira um exemplo de regra de falha que tem uma condição de FaultRule externa e uma condição de etapa interna.

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

Variáveis específicas de erros de política

As variáveis fault.name e {policy_namespace}.{policy_name}.failed estão disponíveis quando uma política gera um erro.

fault.name

Quando uma política falhar, capture o erro em uma condição usando a variável fault.name. Exemplo:

<Condition>(fault.name = "policy_error_name")</Condition>

O nome do erro é exibido na mensagem de erro padrão. Por exemplo, o nome da falha é FailedToResolveAPIKey. Nesse caso, uma variável de fluxo chamada fault.name é definida como o valor FailedToResolveAPIKey.

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

Então, a condição seria assim:

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

Consulte a referência de erro de política para ver uma lista de erros de política.

{policy_namespace}.{policy_name}.falha

A variável *.failed estará disponível quando uma política falhar. Veja a seguir exemplos de variáveis *.failed para políticas diferentes. Para namespaces de políticas, consulte as variáveis de fluxo em cada tópico de referência da política.

• Política RaiseFault: raisefault.failed (o mesmo para todas as políticas RaiseFault)
• Política VerifyAPIKey: oauthV2.{policy_name}.failed, por exemplo, oauthV2.Verify-API-Key-1.failed.
• Política de cotas e Política SpikeArrest: ratelimit.{policy_name}.failed, por exemplo, ratelimit.Quota-1.failed

Outras variáveis disponíveis

Quando um proxy de API entra em um estado de erro, as únicas variáveis disponíveis para uso nas condições são:

• As variáveis da política que falharam.
• As variáveis de mensagem HTTP que existem no ponto de falha. Por exemplo, se um erro for gerado na resposta, uma FaultRule em <TargetEndpoint> poderá usar dados HTTP response.status.code, message.content, error.content e assim por diante. Ou se uma política de cotas falhar, use a variável ratelimit.{quota_policy_name}.exceed.count. Use a Ferramenta de rastreamento e a política tópicos de referência para ajudar você a descobrir quais variáveis e dados HTTP estão disponíveis.

Mais informações

• Condições: referência de condições e Variáveis e condições de fluxo

• Erros: referência de erros de política
• Variáveis: referência de variáveis e consulte páginas de referência de políticas individuais para variáveis disponíveis em cada política.

Práticas recomendadas para tratamento de falhas

O tratamento de falhas é uma importante tarefa de design arquitetônico para o desenvolvimento do proxy de API. É importante que você reserve um tempo para descobrir como e quando lidar com erros, determinar quais mensagens de erro dirão e projetar formatos de mensagem de erro. Depois (ou como) descobrir essas coisas, use essas práticas recomendadas para ajudar na implementação da manipulação de falhas.

Veja a seguir algumas práticas recomendadas para projetar e criar o tratamento de falhas:

• Para cada falha de regra, forneça um <Condition> externo (sibling ao elemento <Step>). As regras de falha sem condição externa são avaliadas automaticamente como "true". As condições da etapa "Inner" não são usadas para determinar se a FailRule é verdadeira ou falsa. As condições da etapa são avaliadas somente depois que o Edge executa a FaultRule que as contém. Em um FailRule, é comum ter várias etapas com políticas "Atribuir mensagem" (ou outras), cada uma com uma condição "Etapa".

• Para lidar com erros em várias políticas do mesmo tipo (por exemplo, várias políticas de cota), crie uma FaultRule por erro de política que você provavelmente receberá. Por exemplo, crie uma "FailRule" para cada erro provável em políticas de cota, como QuotaViolation, InvalidMessageWeight, StartTimeNotSupported. Consulte a referência de erro de política para ver os erros de política. À medida que você detecta outros erros que precisam ser tratados, pode voltar mais tarde e adicioná-los às FaultRules. Não há problema em ser iterativo, embora exija reimplantação de proxy. Essa abordagem permite que você identifique o mesmo tipo de erro, independentemente da política que a gera, o que torna seu XML FaultRules eficiente e eficiente.

  Em seguida, use as condições de Etapa interna se precisar de um controle de erros mais refinado. Por exemplo, se você estiver aplicando a cota individual do desenvolvedor e a cota global com duas políticas no fluxo de solicitação, defina a condição "externa" da FaultRule para ser acionada no erro QuotaViolation (que é gerado quando a cota passa em maiúsculas e minúsculas). Em seguida, defina condições de etapa para avaliar as variáveis exceed.count nas duas políticas de cota. Somente o erro relevante é enviado ao cliente (sobreuso de cota global ou de cota global). Veja um exemplo dessa configuração:

  <FaultRule name="over_quota">
  <!-- This condition catches a QuotaViolation in *any* Quota policy -->
    <Condition>(fault.name = "QuotaViolation")</Condition>
    <Step>
      <Name>developer-over-quota-fault</Name>
      <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
    <Step>
      <Name>global-over-quota-fault</Name>
      <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
  </FaultRule>
  

  Para ver outro exemplo, consulte esta conversa da comunidade da Apigee.

• Para lidar com erros quando você estiver usando uma única política de um tipo, considere uma única regra de falha que seja executada quando essa política falhar e inclua várias etapas que mapeiam para cada erro possível. Isso mantém seu XML eficiente usando uma único FailRule em vez de várias FaultRules (uma para cada tipo de erro). Exemplo:

  <FaultRule name="raise-fault-3">
  <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
    <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
    <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
    <Step>
      <Name>Generic-Key-Fault</Name>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-1</Name>
      <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-2</Name>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </Step>
  </FaultRule>
  

• Adicione o FaultRules onde os erros ocorrerão (do lado do cliente <ProxyEndpoint> ou do lado do destino <TargetEndpoint>). Inclua FaultRules para cada política que aparece em cada local.
• Em FaultRules, você pode executar qualquer tipo de política que possa retornar uma mensagem ao app cliente. A política AssignMessage é ideal para isso. Considere também registrar uma mensagem com a política MessageLogging se você quiser acompanhar os erros.
• Ao usar políticas BoostFail em conjunto com o FailRules, coordene os dados de resposta que são retornados de volta à política GenerateFault e à FlatRule. Por exemplo, se sua política IncrementFail redefinir o código de status HTTP, não tenha um FaultRule para redefinir o código de status. O pior que pode acontecer é que o código de status padrão é retornado ao app cliente.
• Execução de <DefaultFaultRule>:
  • Se você quiser que um <DefaultFaultRule> sempre seja executado quando nenhuma outra FailRule for executada, não inclua um <Condition>.
  • Se você quiser que uma <DefaultFaultRule> seja sempre executada, mesmo quando outra FaultRule for executada, adicione o elemento filho <AlwaysEnforce>true</AlwaysEnforce>.

Padrão para manipulação de falhas centralizada e reutilizável

A postagem da comunidade da Apigee a seguir descreve um padrão para tratamento de falhas centralizado sem duplicação de código:

https://community.apigee.com/articles/23724/an-error-handle-pattern-for-apigee-proxies.html (em inglês)

Criar regras de falha

Para adicionar uma FaultRule, edite a configuração XML do ProxyEndpoint ou TargetEndpoint. Use a interface do Edge para fazer essa edição no painel Código do Desenvolver a visualização de um proxy de API ou editar o arquivo XML que define o ProxyEndpoint ou o TargetEndpoint.

Se você criar FaultRules na interface do usuário de gerenciamento, primeiro crie as políticas que deseja executar, e adicioná-las à configuração FaultRule. Você verá um erro na IU se tentar salvar uma FaultRule que faz referência a uma política que ainda não foi criada.

Como adicionar políticas a uma FaultRule

Embora você possa colocar qualquer política na FaultRule, geralmente é usada a política AssignMessage para gerar uma mensagem de resposta personalizada para uma condição de erro. O AssignMessage permite configurar uma resposta HTTP com payload, código de status HTTP, cabeçalhos e elementos de frase de motivo.

O exemplo abaixo mostra uma configuração de Política de atribuição típica:

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Agora você pode usar essa política na seu FailRule. Observe como você menciona a política AssignMessage por nome na FaultRule:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Quando você implanta a configuração acima, o proxy da API executa a política AssignMessage chamada fault_invalidkey sempre que um aplicativo apresenta uma chave de API inválida.

Você pode executar várias políticas em uma FaultRule, como mostra o exemplo a seguir:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

As políticas são executadas na ordem definida. Por exemplo, você pode usar a política MessageLogging, a política ExtractVariables, a política AssignMessage ou qualquer outra política na FaultRule. Observe que o processamento de FaultRule será interrompido imediatamente se uma destas situações ocorrer:

• Qualquer política na FaultRule causa um erro
• Qualquer uma das políticas na FaultRule é do tipo RaiseFault

Definir a mensagem de erro personalizada retornada de uma FaultRule

Como prática recomendada, defina respostas de erro claras das APIs. Dessa forma, você fornece informações consistentes e úteis para seus clientes.

O exemplo a seguir Política de atribuição usa as tags <Payload>, <StatusCode> e <ReasonPhase> para definir a resposta de erro personalizada enviada ao cliente em uma InvalidApiKey (consulte o exemplo FaultRules anterior).

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization. 
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Essa resposta inclui:

• O payload que contém a mensagem de erro e um endereço de e-mail para entrar em contato com o suporte.
• Código de status HTTP retornado na resposta.
• A frase de motivo, que é uma breve descrição do erro.

Como criar uma DefaultFaultRule

Uma DefaultFaultRule atua como um gerenciador de exceções para qualquer erro não processado explicitamente por outra falha com falha. Se as condições de todas as FaultRules não corresponderem ao erro, a DefaultFailRule processará o erro. Ative o tratamento de falhas padrão adicionando a tag <DefaultFaultRule> como um elemento filho de um ProxyEndpoint ou TargetEndpoint.

Por exemplo, a configuração de TargetEndpoint abaixo define uma DefaultFaultRule que invoca uma política chamada ReturnGenericError:

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Normalmente, a DefaultFailRule é usada para retornar uma mensagem de erro genérica para qualquer erro inesperado, como uma mensagem que contenha dados de contato para suporte técnico. Essa resposta padrão tem a finalidade dupla de fornecer informações amigáveis ao desenvolvedor e também ofuscar URLs de back-end ou outras informações que podem ser usadas para comprometer o sistema.

Por exemplo, você define a seguinte política AssignMessage para retornar um erro genérico:

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

Inclua o elemento <AlwaysEnforce> na tag <DefaultFaultRule> para executar a DefaultFaultRule para cada erro, mesmo se outra FaultRule já tiver sido executada. A DefaultFaultRule é sempre a última falha de falha a ser executada:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

Um dos usos da DefaultFaultRule é determinar o tipo de erro que ocorre quando você não o determina. Por exemplo, o proxy da API está falhando devido a um erro que não é possível determinar. Use a DefaultFaultRule para invocar a seguinte política AssignMessage. Esta política grava o valor fault.name em um cabeçalho chamado DefaultFaultHeader na resposta:

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

O cabeçalho pode ser visualizado na ferramenta Edge Trace ou na resposta para saber o que causou o erro.

Como adicionar a geração de registros de mensagens ao PostClientFlow

O PostClientFlow é o único fluxo que é executado depois que o proxy entra no estado de erro. Somente a política MessageLogging pode ser anexada a esse fluxo, que é executada depois que a resposta é enviada de volta ao cliente. Embora a anexação da política MessageLogging a esse fluxo não seja tecnicamente um tratamento de erros, é possível usá-la para registrar informações no caso de um erro. Como ele é executado, independentemente de o proxy ter êxito ou falha, é possível colocar as políticas de Registro de mensagens no PostClientFlow e garantir que elas sejam sempre executadas.

Como lidar com falhas de política no fluxo atual

Todos os exemplos mostrados até agora usam uma FaultRule no ProxyEndpoint ou TargetEndpoint para lidar com erros de política como parte do estado do erro. Isso ocorre porque o valor padrão do elemento continueOnError de uma política é false, o que significa que, quando ocorre um erro em uma política, o controle é direcionado para o estado do erro. Quando estiver no estado de erro, não será possível retornar o controle ao pipeline normal e você normalmente retornará alguma mensagem de erro para o aplicativo de chamada.

No entanto, se você definir o elemento continueOnError como true para uma política, o controle permanecerá no fluxo atual e a próxima política no pipeline será executada após a política que causou o erro. A vantagem de lidar com o erro no fluxo atual é que você pode ter uma maneira de se recuperar do erro para concluir o processamento da solicitação.

Veja a seguir uma política VerifyAPIKey chamada verify-api-key com o elemento continueOnError definido como true:.

<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

Se a chave de API estiver ausente ou for inválida, a política VerifyAPIKey definirá a variável oauthV2.verify-api-key.failed como true, mas o processamento continuará no fluxo atual.

Em seguida, adicione a política VerifyAPIKey como uma etapa no PreFlow do ProxyEndpoint:

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>      
</ProxyEndpoint>  

Observe como a próxima etapa no PreFlow usa uma condição para testar a existência de um erro. Se ocorrer um erro na política VerifAPIKey, a política chamada FaultInFlow será executada. Caso contrário, a política FaultInFlow será ignorada. A política FaultInFlow pode fazer muitas coisas, como registrar o erro, tentar corrigi-lo ou executar outra ação.

Como acionar um erro usando a política RaiseFault

Você pode usar a política RaiseFault a qualquer momento em um fluxo para acionar um erro. Quando uma política RaiseFault é executada, ela encerra o fluxo atual e transfere o controle para o estado de erro.

Um uso da política RaiseFault é testar uma condição específica que outra política talvez não detecte. No exemplo acima, você adicionou uma tag <Condition> a uma tag <Step> do PreFlow que causou a execução da política FaultInFlow se a condição fosse atendida. Se FaultInFlow for uma política RaiseFault, controle as transferências para o estado de erro. Ou você pode inserir uma política RaiseFault em um fluxo para depurar e testar suas FaultRules.

Quando uma política RaiseFault acionar um erro, você poderá usar a seguinte FaultRule e a condição para processá-la:

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

Observe que a condição testa uma falha chamada RaiseFault. A política GrowFault sempre define o valor de fault.name como RaiseFault.

Tratamento personalizado de códigos de erros HTTP do servidor de destino

Os exemplos mostrados nas seções anteriores se aplicam a erros criados por políticas. No entanto, você também pode criar uma resposta personalizada para erros no nível do transporte, o que significa erros HTTP retornados do servidor de destino. Para controlar a resposta de um erro HTTP, configure um TargetEndpoint para processar códigos de resposta HTTP.

Por padrão, o Edge trata códigos de resposta HTTP no intervalo 1xx-3xx como "sucesso", e o HTTP códigos de resposta no intervalo 4xx-5xx como "falha". Isso significa que qualquer resposta do serviço de back-end com um código de resposta HTTP 4xx-5xx invoca automaticamente o estado do erro, que retorna uma mensagem de erro diretamente para o cliente solicitante.

Você pode criar gerenciadores personalizados para qualquer código de resposta HTTP. Por exemplo, talvez você não queira tratar todos os códigos de resposta HTTP no intervalo 4xx-5xx como "falha", mas apenas 5xx, ou convém retornar mensagens de erro personalizadas para os códigos de resposta HTTP 400 e 500.

No próximo exemplo, use a propriedade success.codes para configurar o TargetEndpoint para tratar os códigos de resposta HTTP 400 e 500 como um sucesso, juntamente com os códigos HTTP padrão. Ao tratar esses códigos como um sucesso, o TargetEndpoint assume o processamento da mensagem de resposta, em vez de invocar o estado do erro:

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Como você pode ver neste exemplo, é possível usar caracteres curinga para definir a propriedade fun.codes como um intervalo de valores.

A definição da propriedade success.codes substitui os valores padrão. Portanto, se você quiser adicionar o código HTTP 400 à lista de códigos de sucesso padrão, defina esta propriedade como:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

No entanto, se você quiser apenas que o código HTTP 400 seja tratado como um código de sucesso, defina a propriedade como:

<Property name="success.codes">400</Property>

Agora, é possível definir gerenciadores personalizados para os códigos de resposta HTTP 400 e 500 para retornar uma mensagem de resposta personalizada ao app solicitante. O seguinte TargetEndpoint usa a política chamada ReturnError para lidar com os códigos de resposta HTTP 400 e 500:

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Essa configuração de TargetEndpoint faz a política chamada ReturnError para processar a resposta sempre que o TargetEndpoint encontra um código de resposta HTTP de 400 ou 500.

Taxonomia

Os Serviços de API organizam falhas nas categorias e subcategorias a seguir.

Um erro é sempre acompanhado por uma descrição do texto do motivo da falha. Quando o sistema gera uma falha, um conjunto de atributos é preenchido para ajudar na solução de problemas. Uma falha inclui as seguintes informações:

• Motivo
• Atributos personalizados definidos pelo usuário