Gestão de erros nas políticas de Gestão de API

APLICA-SE A: Todas as camadas de gerenciamento de API

Ao fornecer um objeto ProxyError, API Management do Azure permite aos editores responder a condições de erro que podem ocorrer durante o processamento de pedidos. O ProxyError objeto é acedido através da propriedade contexto.LastError. As políticas na on-error secção de políticas podem usar o ProxyError objeto. Este artigo fornece uma referência para os recursos de tratamento de erros 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 em inbound, backend, outbounde on-error seções, 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 um pedido, os passos incorporados são executados juntamente com quaisquer políticas que estejam no âmbito do pedido. Se ocorrer um erro, o processamento salta imediatamente para a secção política on-error .

A on-error seção de política pode ser usada em qualquer escopo. Os editores de APIs podem configurar comportamentos personalizados, como registar o erro no Hubs de Eventos do Azure ou criar uma nova resposta para devolver ao chamador.

Nota

A on-error secção não está presente nas apólices por defeito. Para adicionar a on-error seção a uma política, navegue até a política desejada no editor de políticas e adicione-a. Para obter mais informações sobre como configurar políticas, consulte Políticas no gerenciamento de API.

Se não houver secção on-error, os chamadores recebem mensagens de resposta HTTP 400 ou 500 caso ocorra uma condição de erro.

Políticas permitidas em caso de erro

As seguintes políticas podem ser usadas na secção de políticas on-error.

ÚltimoErro

Quando ocorre um erro e o controlo salta para a on-error secção de políticas, o erro é armazenado na propriedade contexto.LastError. As políticas na on-error seção podem aceder context.LastError a. LastError tem as seguintes propriedades.

Nome Tipo Descrição Obrigatório
Source cadeia (de caracteres) Nome do elemento onde ocorreu o erro. Pode ser uma política ou o nome de uma etapa de pipeline incorporada. Sim
Reason cadeia (de caracteres) Código de erro amigável à máquina, que pode ser usado no tratamento de erros. Não
Message cadeia (de caracteres) Descrição do erro legível por humanos. Sim
Scope cadeia (de caracteres) Nome do escopo onde ocorreu o erro. Não
Section cadeia (de caracteres) Nome da seção onde ocorreu o erro. Valores possíveis: inbound, backend, outbound, ou on-error. Não
Path cadeia (de caracteres) Especifica hierarquia de políticas aninhada, por exemplo choose[3]\\when[2]. Várias instâncias de uma política com estrutura aninhada são indexadas começando do número 1. Não
PolicyId cadeia (de caracteres) Valor do id atributo, se especificado pelo cliente, na política onde ocorreu o erro Não

Gorjeta

Pode aceder ao código de estado através de context.Response.StatusCode.

Nota

Todas as políticas têm um atributo opcional id que pode ser adicionado ao elemento raiz da política. Se este atributo estiver presente numa apólice quando ocorre uma condição de erro, pode obter 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 internas.

Origem Condição Razão Mensagem
configuração O URI não corresponde a nenhuma API ou operação OperaçãoNotFound Não foi possível associar a solicitação de entrada a uma operação.
autorização Chave de subscrição não fornecida ChaveDeSubscriçãoNãoEncontrada Acesso negado devido à falta de 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 subscrição é inválido ChaveDeSubscriçãoInválida Acesso negado devido a chave de subscrição inválida. Certifique-se de fornecer uma chave válida para uma assinatura ativa.
múltiplos O cliente abortou uma ligação a jusante (de um cliente para um gateway de Gestão de API) enquanto o pedido estava pendente Falha de Conexão do Cliente múltiplos
múltiplos O back end abortou ou não conseguiu estabelecer uma ligação ascendente (de um gateway de gestão de API para um serviço back end) FalhaNaConexãoDoBackend múltiplos
múltiplos A exceção em tempo de execução ocorreu durante a avaliação de uma expressão particular Falha na Avaliação do Valor da Expressão múltiplos

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.

Origem Condição Razão Mensagem
limitação de velocidade Limite de taxa excedido Limite de Taxa Excedido O limite da taxa é excedido
quota Quota excedida QuotaExcedido Fora da quota de volume de chamadas. A quota será reabastecida em xx:xx:xx. -ou- Fora do limite de largura de banda. A quota será reabastecida 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 FailedToParseCallerIP Falha ao estabelecer o endereço IP do chamador. Acesso negado.
filtro de IP O IP do chamador não está na lista de permitidos IPDoChamadorNãoPermitido 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 IPDoChamadorBloqueado O endereço IP do chamador está bloqueado. Acesso negado.
cabeçalho-verificação Cabeçalho obrigatório não apresentado ou valor ausente CabeçalhoNãoEncontrado Header {header-name} não foi encontrado na solicitação. Acesso negado.
cabeçalho-verificação Cabeçalho obrigatório não apresentado ou valor ausente ValorDeCabeçalhoNãoPermitido O valor de cabeçalho {header-name} de {header-value} não é permitido. Acesso negado.
validar-jwt O JSON Web Token (JWT) está em falta no pedido TokenNãoPresente JWT não presente.
validar-jwt Falha na validação da assinatura Assinatura do Token Inválida <Mensagem da biblioteca JWT>. Acesso negado.
validar-jwt Audiência inválida PúblicoDoTokenNãoPermitido <mensagem da biblioteca JWT>. Acesso negado.
validar-jwt Emissor inválido EmissorDeTokenNãoPermitido <Mensagem da biblioteca JWT>. Acesso negado.
validar-jwt O token expirou Token Expirado <Mensagem da biblioteca jwt>. Acesso negado.
validar-jwt A chave de assinatura não foi resolvida pelo ID TokenSignatureKeyNotFound (Chave de Assinatura do Token Não Encontrada) <Mensagem da biblioteca JWT>. Acesso negado.
validar-jwt As declarações necessárias estão ausentes do token Token de Reivindicação Não Encontrado JWT está a faltar as seguintes declarações: <c1>, <c2>, ... Acesso negado.
validar-jwt Incompatibilidade de valores de reclamação Valor de Reivindicação do Token Não Permitido 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>
Solicitação de encaminhamento ou solicitação de envio O código de estado da resposta HTTP e os cabeçalhos não foram recebidos do backend dentro do timeout configurado Limite de tempo excedido múltiplos

Exemplo

Defina uma política de API para 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 um pedido não autorizado resulta na seguinte resposta:

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

Conteúdos relacionados

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

  • Last updated on