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 seção on-error 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 multiple
múltiplo O back-end abortou ou não conseguiu estabelecer uma conexão upstream (de um gateway de API Management para um serviço de back-end) FalhaNaConexãoComOBackend múltiplo
multiple 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 RateLimitExceeded O limite da taxa foi excedido
cota Cota excedida QuotaExceeded 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 CallerIpNotAllowed 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.
check-header 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.
check-header O cabeçalho necessário não é apresentado ou o valor está ausente HeaderValueNotAllowed 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 TokenNotPresent 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 TokenAudienceNotAllowed <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 pelo 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 TokenClaimValueNotAllowed O valor da declaração {claim-name} de {claim-value} não é permitido. Acesso negado.
validar JWT Outras falhas de validação JwtInválido <mensagem da biblioteca jwt>
forward-request ou send-request O código de status de resposta HTTP e os cabeçalhos não foram recebidos do back-end dentro do tempo limite configurado Tempo limite 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