Erro ao processar as políticas de Gestão de API

  • Artigo

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

Ao fornecer um ProxyError objeto, 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 ProxyError objeto é acessado através do contexto. LastError propriedade e pode ser usado por políticas na on-error seção de política. 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 uma solicitação, as etapas internas são executadas juntamente com quaisquer políticas, que estão no escopo da solicitação. 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 API podem configurar um comportamento personalizado, como registrar o erro em hubs de eventos ou criar uma nova resposta para retornar ao chamador.

Nota

A on-error seção não está presente nas políticas por padrão. 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 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 no erro

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

LastError

Quando ocorre um erro e o controle salta para a seção de on-error política, o erro é armazenado no contexto. LastError propriedade, que pode ser acessada on-error por políticas na seção . LastError tem as seguintes propriedades.

Nome Tipo Descrição Obrigatório
Source string Nomeia o elemento onde o erro ocorreu. Pode ser uma política ou um nome de etapa de pipeline interno. Sim
Reason string Código de erro amigável à máquina, que pode ser usado no tratamento de erros. Não
Message string Descrição do erro legível por humanos. Sim
Scope string Nome do escopo onde o erro ocorreu e pode ser um de "global", "product", "api" ou "operation" Não
Section string Nome da seção onde ocorreu o erro. Valores possíveis: "inbound", "backend", "outbound" ou "on-error". Não
Path string Especifica a política aninhada, por exemplo "choose[3]/when[2]". Não
PolicyId string Valor do id atributo, se especificado pelo cliente, na política onde ocorreu o erro Não

Gorjeta

Você pode acessar o código de status através do contexto. Response.StatusCode.

Nota

Todas as políticas têm um atributo opcional id 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 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.

Source Condição Razão Mensagem
configuração O Uri não corresponde a nenhuma API ou operação OperaçãoNotFound Não é possível fazer corresponder a solicitação de entrada a uma operação.
autorização Chave de subscrição não fornecida SubscriptionKeyNotFound 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 SubscriptionKeyInvalid Acesso negado devido a chave de subscrição inválida. Certifique-se de fornecer uma chave válida para uma assinatura ativa.
múltiplos A conexão downstream (de um cliente para um gateway de gerenciamento de API) foi abortada pelo cliente enquanto a solicitação estava pendente ClientConnectionFailure múltiplos
múltiplos A conexão upstream (de um gateway de gerenciamento de API para um serviço de back-end) não foi estabelecida ou foi abortada pelo back-end BackendConnectionFailure múltiplos
múltiplos A exceção de tempo de execução ocorreu durante a avaliação de uma expressão específica ExpressionValueEvaluationFailure 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.

Source Condição Razão Mensagem
limite de taxa Limite de taxa excedido RateLimitExceeded O limite da taxa é excedido
quota Quota excedida QuotaExceeded Volume de chamadas fora da quota. A quota será reposta em xx:xx:xx. -ou- Fora da cota de largura de banda. A quota 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.
ip-filter Falha ao analisar o IP do chamador da solicitação FailedToParseCallerIP Falha ao estabelecer o endereço IP do chamador. Acesso negado.
ip-filter O IP do chamador não está na lista de permitidos CallerIpNotAllowed O endereço IP do chamador {ip-address} não é permitido. Acesso negado.
ip-filter O IP do chamador está na lista de bloqueios CallerIpBlocked O endereço IP do chamador está bloqueado. Acesso negado.
cabeçalho-verificação Cabeçalho obrigatório não apresentado ou valor ausente HeaderNotFound 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 HeaderValueNotAllowed O valor de cabeçalho {header-name} de {header-value} não é permitido. Acesso negado.
validar-jwt O token Jwt está faltando na solicitação TokenNotPresent JWT não presente.
validar-jwt Falha na validação da assinatura TokenSignatureInvalid <Mensagem da Biblioteca> JWT. Acesso negado.
validar-jwt Audiência inválida TokenAudienceNotAllowed <Mensagem da Biblioteca> JWT. Acesso negado.
validar-jwt Emissor inválido TokenIssuerNotAllowed <Mensagem da Biblioteca> JWT. Acesso negado.
validar-jwt O token expirou TokenExpired <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 do token TokenClaimNotFound O token JWT está faltando as seguintes declarações: <c1>, <c2>, ... Acesso negado.
validar-jwt Incompatibilidade de valores de reivindicação TokenClaimValueNotAllowed Não é permitida a reivindicação {claim-name} valor de {claim-value}. Acesso negado.
validar-jwt Outras falhas de validação JwtInvalid <Mensagem da Biblioteca JWT>
Solicitação de encaminhamento ou solicitação de envio O código de status da resposta HTTP e os cabeçalhos não foram recebidos do back-end dentro do tempo limite configurado Limite de tempo excedido múltiplos

Exemplo

Definindo 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 o envio de uma solicitação não autorizada resultará na seguinte resposta:

Resposta de erro não autorizada

Próximos passos

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