Compartilhar via

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, o Gerenciamento de API do Azure permite que os editores respondam a condições de erro que podem ocorrer durante o processamento de solicitações. O objeto ProxyError é acessado por meio da propriedade context.LastError e pode ser usado por políticas na seção da política on-error. Este artigo fornece uma referência para os recursos de tratamento de erro no Gerenciamento de API do Azure.

Tratamento de erro 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 junto com as políticas, que estão no escopo da solicitação. Se ocorre um erro, o processamento imediatamente salta para a seção da política on-error. A seção de política on-error pode ser usada em qualquer escopo. Os editores de API podem configurar um comportamento personalizado, como registrar o erro para hubs de eventos ou criar uma nova resposta para retornar ao chamador.

Observação

A seção on-error não está presente nas 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 seção on-error, os chamadores receberão mensagens de resposta HTTP 400 ou 500 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 seção de política on-error, o erro é armazenado na propriedade context.LastError, que pode ser acessada por políticas na seção on-error. LastError tem as propriedades a seguir.

Nome Tipo Descrição Obrigatório
Source cadeia de caracteres Indica o elemento em que ocorreu o erro. Pode ser o nome de uma etapa do pipeline interno ou política. Sim
Reason cadeia de caracteres Código de erro amigável para computadores, que pode ser usado no tratamento de erro. Não
Message cadeia de caracteres Descrição de erro legível por humanos. Sim
Scope cadeia de caracteres Nome do escopo em que o erro ocorreu. Não
Section cadeia de caracteres Nome da seção em que ocorreu o erro. Valores possíveis: "inbound", "backend", "outbound" ou "on-error". Não
Path cadeia de caracteres Especifica hierarquia de políticas aninhadas, 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 de caracteres O valor do atributo id, se especificado pelo cliente, na política em que ocorreu o erro Não

Dica

É possível 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, o valor do atributo poderá ser recuperado usando a propriedade context.LastError.PolicyId.

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 OperationNotFound 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 chave e 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 A conexão downstream (de um cliente para um gateway de Gerenciamento de API) foi anulada pelo cliente enquanto a solicitação estava pendente FalhaNaConexãoDoCliente múltiplo
múltiplo A conexão upstream (de um gateway de Gerenciamento de API para um serviço de back-end) não foi estabelecida ou foi anulada pelo back-end FalhaNaConexãoComOBackend múltiplo
múltiplo Uma exceção de tempo de execução ocorreu durante a avaliação de uma expressão específica ExpressionValueEvaluationFailure múltiplo

Erros predefinidos 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 QuotaExceededed Fora da cota do volume de chamada. 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) CallbackParameterInvalid 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 CallerIpBlocked 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 HeaderNotFound 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 HeaderValueNotAllowed O valor do cabeçalho {header-name} de {header-value} não é permitido. Acesso negado.
validate-jwt O JWT está ausente na solicitação TokenNotPresent JWT não presente.
validate-jwt Falha na validação da assinatura TokenSignatureInvalid <mensagem da biblioteca jwt> Acesso negado.
validate-jwt Público-alvo inválido TokenAudienceNotAllowed <mensagem da biblioteca jwt> Acesso negado.
validate-jwt Emissor inválido TokenIssuerNotAllowed <mensagem da biblioteca jwt> Acesso negado.
validate-jwt Token expirado TokenExpired <mensagem da biblioteca jwt> Acesso negado.
validate-jwt A chave de assinatura não foi resolvida pela ID TokenSignatureKeyNotFound <mensagem da biblioteca jwt> Acesso negado.
validate-jwt As declarações necessárias estão ausentes no token TokenClaimNotFound JWT está faltando as seguintes declarações: <c1>, <c2>, ... Acesso negado.
validate-jwt Incompatibilidade de valores de declaração TokenClaimValueNotAllowed O valor da declaração {claim-name} de {claim-value} não é permitido. Acesso negado.
validate-jwt Outras falhas de validação JwtInvalid <mensagem da biblioteca jwt>
forward-request ou send-request Os cabeçalhos e o código de status de resposta HTTP não foram recebidos do back-end dentro do tempo limite configurado Tempo limite múltiplo

Exemplo

Configurando uma política de API para:

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

e enviar uma solicitação não autorizada resultará na resposta a seguir:

Resposta de erro não autorizada

Conteúdo relacionado

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

  • Last updated on