Tratamento de erro em políticas de Gerenciamento de API

APLICA-SE A: todas as camadas do Gerenciamento de API

Ao fornecer um objeto ProxyError, Gerenciamento de API do Azure permite que os editores respondam às condições de erro, que podem ocorrer durante o processamento de solicitações. O ProxyError objeto é acessado por meio da propriedade contexto.LastError. As políticas na on-error seção de política podem usar o ProxyError objeto. Este artigo fornece uma referência para os recursos de tratamento de erro no Gerenciamento de API do Azure.

Tratamento de erros no Gerenciamento de API

As políticas no Gerenciamento de API do Azure são divididas nas seções inbound, backend, outbound e on-error conforme mostrado no exemplo a seguir.

<policies>
    <inbound>
        <!-- statements to be applied to the request go here -->
    </inbound>
    <backend>
        <!-- statements to be applied before the request is
             forwarded to the backend service go here -->
    </backend>
    <outbound>
        <!-- statements to be applied to the response go here -->
    </outbound>
    <on-error>
        <!-- statements to be applied if there is an error
             condition go here -->
    </on-error>
</policies>

Durante o processamento de uma solicitação, as etapas internas são executadas juntamente com as políticas que estão no escopo da solicitação. Se um erro ocorrer, o processamento imediatamente salta para a seção de política on-error.

A seção de política on-error pode ser usada em qualquer escopo. Os editores de API podem configurar o comportamento personalizado, como registrar o erro no Hubs de Eventos do Azure ou criar uma nova resposta como retorno para o chamador.

Observação

A on-error seção não está presente em políticas por padrão. Para adicionar a seção on-error a uma política, navegue até a política desejada no editor de políticas e adicione-a. Para informações sobre como configurar políticas, consulte Políticas do Gerenciamento de API.

Se não houver nenhuma on-error seção, os chamadores receberão 400 ou 500 mensagens de resposta HTTP se ocorrer uma condição de erro.

Políticas permitidas em caso de erro

As políticas a seguir podem ser usadas na seção da política on-error.

LastError

Quando ocorre um erro e o controle salta para a on-error seção de política, o erro é armazenado na propriedade context.LastError. As políticas na on-error seção podem acessar context.LastError. LastError tem as propriedades a seguir.

Nome Tipo Descrição Obrigatório
Source cadeia Nome do elemento em que o erro ocorreu. Pode ser o nome de uma etapa do pipeline interno ou política. Sim
Reason cadeia Código de erro amigável para computadores, que pode ser usado no tratamento de erro. Não
Message cadeia Descrição de erro legível por humanos. Sim
Scope cadeia Nome do escopo em que o erro ocorreu. Não
Section cadeia Nome da seção em que ocorreu o erro. Valores possíveis: inbound, backend, outboundou on-error. Não
Path cadeia Especifica a hierarquia de política aninhada, por exemplo choose[3]\\when[2]. Várias instâncias de uma política aninhada são indexadas a partir de 1. Não
PolicyId cadeia O valor do atributo id, se especificado pelo cliente, na política em que ocorreu o erro Não

Dica

Você pode acessar o código de status por meio de context.Response.StatusCode.

Observação

Todas as políticas têm um atributo id opcional que pode ser adicionado ao elemento raiz da política. Se esse atributo estiver presente em uma política quando ocorrer uma condição de erro, você poderá recuperar o valor do atributo usando a context.LastError.PolicyId propriedade.

Erros predefinidos para etapas internas

Os erros a seguir são predefinidos para condições de erro que podem ocorrer durante a avaliação das etapas de processamento interno.

Fonte Condição Motivo Mensagem
configuração O URI não corresponde a nenhuma API ou Operação OperaçãoNãoEncontrada Não é possível corresponder a solicitação recebida a uma operação.
autorização Chave de assinatura não fornecida SubscriptionKeyNotFound Acesso negado devido à ausência da chave de assinatura. Certifique-se de incluir a chave de assinatura ao fazer solicitações para esta API.
autorização O valor da chave de assinatura é inválido ChaveDeAssinaturaInválida Acesso negado devido à chave de assinatura inválida. Certifique-se de fornecer uma chave válida para uma assinatura ativa.
múltiplo O cliente anulou uma conexão downstream (de um cliente para um gateway de Gerenciamento de API) enquanto a solicitação estava pendente FalhaNaConexãoDoCliente múltiplo
múltiplo O back-end foi abortado ou não pôde estabelecer uma conexão de saída (de um API Management Gateway para um serviço de back-end) FalhaNaConexãoComOBackend múltiplo
múltiplo A exceção de runtime ocorreu durante a avaliação de uma expressão específica FalhaNaAvaliaçãoDoValorDaExpressão múltiplo

Falhas predefinidas para políticas

Os erros a seguir são predefinidos para condições de erro que podem ocorrer durante a avaliação da política.

Fonte Condição Motivo Mensagem
limitação de taxa Limite de taxa excedido Limite de Taxa Excedido O limite da taxa foi excedido
cota Cota excedida Cota Excedida Quota de volume de chamadas excedida. A cota será reposta em xx:xx:xx. – ou – Sem cota de largura de banda. A cota será reposta em xx:xx:xx.
jsonp O valor do parâmetro de retorno de chamada é inválido (contém caracteres errados) ParâmetroDeRetornoInválido O valor do parâmetro de retorno de chamada {callback-parameter-name} não é um identificador JavaScript válido.
filtro de IP Falha ao analisar o IP do chamador da solicitação Falha ao Analisar IP do Chamador Falha ao estabelecer o endereço IP para o chamador. Acesso negado.
filtro de IP O IP do chamador não está na lista de permissões IP do Chamador Não Permitido O endereço IP do chamador {ip-address} não é permitido. Acesso negado.
filtro de IP O IP do chamador está na lista de bloqueios IP do Chamador Bloqueado O endereço IP do chamador está bloqueado. Acesso negado.
cabeçalho de verificação O cabeçalho necessário não é apresentado ou o valor está ausente CabeçalhoNãoEncontrado O cabeçalho {header-name} não foi encontrado na solicitação. Acesso negado.
cabeçalho de verificação O cabeçalho necessário não é apresentado ou o valor está ausente ValorDeCabeçalhoNãoPermitido O valor do cabeçalho {header-name} de {header-value} não é permitido. Acesso negado.
validar JWT O JWT (Token Web JSON) está ausente na solicitação TokenNãoPresente JWT não presente.
validar JWT Falha na validação da assinatura AssinaturaDoTokenInválida <mensagem da biblioteca jwt> Acesso negado.
validar JWT Público-alvo inválido TokenAudienciaNaoPermitida <mensagem da biblioteca jwt> Acesso negado.
validar JWT Emissor inválido EmissorDeTokenNãoPermitido <mensagem da biblioteca jwt> Acesso negado.
validar JWT Token expirado Token Expirado <mensagem da biblioteca jwt> Acesso negado.
validar-jwt A chave de assinatura não foi resolvida pela ID TokenSignatureKeyNotFound <mensagem da biblioteca jwt> Acesso negado.
validar-jwt As declarações necessárias estão ausentes no token TokenClaimNãoEncontrado JWT está faltando as seguintes declarações: <c1>, <c2>, ... Acesso negado.
validar-jwt Incompatibilidade de valores de reivindicação ValorDeReivindicaçãoDeTokenNãoPermitido O valor da reivindicação {claim-name} de {claim-value} não é permitido. Acesso negado.
validar JWT Outras falhas de validação JwtInválido <mensagem da biblioteca jwt>
encaminhar solicitações ou enviar solicitações O código de status de resposta HTTP e os cabeçalhos não foram recebidos do back-end dentro do tempo limite configurado Timeout múltiplo

Exemplo

Defina uma política de API com o seguinte valor:

<policies>
    <inbound>
        <base />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />
    </outbound>
    <on-error>
        <set-header name="ErrorSource" exists-action="override">
            <value>@(context.LastError.Source)</value>
        </set-header>
        <set-header name="ErrorReason" exists-action="override">
            <value>@(context.LastError.Reason)</value>
        </set-header>
        <set-header name="ErrorMessage" exists-action="override">
            <value>@(context.LastError.Message)</value>
        </set-header>
        <set-header name="ErrorScope" exists-action="override">
            <value>@(context.LastError.Scope)</value>
        </set-header>
        <set-header name="ErrorSection" exists-action="override">
            <value>@(context.LastError.Section)</value>
        </set-header>
        <set-header name="ErrorPath" exists-action="override">
            <value>@(context.LastError.Path)</value>
        </set-header>
        <set-header name="ErrorPolicyId" exists-action="override">
            <value>@(context.LastError.PolicyId)</value>
        </set-header>
        <set-header name="ErrorStatusCode" exists-action="override">
            <value>@(context.Response.StatusCode.ToString())</value>
        </set-header>
        <base />
    </on-error>
</policies>

Enviar uma solicitação não autorizada resulta na seguinte resposta:

A captura de tela mostra a resposta ao exemplo, que inclui uma mensagem de erro.

Conteúdo relacionado

Para obter mais informações sobre como trabalhar com políticas, consulte:

  • Last updated on