Поделиться через


Обработка ошибок в политиках управления API

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

Предоставляя объект ProxyError, служба управления API Azure позволяет издателям реагировать на ошибки, которые могут возникать во время обработки запросов. Доступ к объекту ProxyError осуществляется через свойство context.LastError, и его могут использовать политики в разделе on-error. Эта статья содержит справочную информацию о возможностях обработки ошибок, которые предоставляет служба управления API Azure.

Обработка ошибок в службе управления API

Политики в службе управления API Azure включают разделы inbound, backend, outbound и on-error, как показано в следующем примере.

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

Во время обработки запроса встроенные действия выполняются с соблюдением всех политик в области запроса. Если возникает ошибка, обработка немедленно переходит к разделу on-error соответствующей политики. Раздел политики on-error можно использовать в любой области. Издатели API могут настроить требуемые действия, например запись информации об ошибках в концентраторы событий или создание нового ответа для передачи вызывающему объекту.

Примечание.

Раздел on-error в политиках отсутствует по умолчанию. Чтобы добавить в политику раздел on-error, перейдите к требуемой политике в редакторе политик и добавьте раздел. Дополнительные сведения о настройке политик см. в статье Политики в Azure API Management.

Если в политике нет раздела on-error, вызывающий объект при возникновении ошибки получит сообщение с HTTP-кодом 400 или 500.

Политики, которые можно использовать в разделе on-error

В разделе on-error можно использовать следующие политики.

LastError

Когда возникает ошибка и управление переходит в раздел политики on-error, ошибка сохраняется в свойстве context.LastError, к которому могут обращаться политики в разделе on-error. LastError имеет следующие свойства.

Имя. Тип Описание Обязательное поле
Source строка Указывает имя элемента, в котором произошла ошибка. Это может быть политика или имя встроенного шага конвейера. Да
Reason строка Код ошибки в машинном формате, который удобно использовать для обработки ошибок. Нет
Message строка Описание ошибки в понятном для человека формате. Да
Scope строка Имя области, в которой возникла ошибка. Здесь возможны следующие значения: global, product, api или operation. Нет
Section строка Имя раздела, в котором произошла ошибка. Возможные значения: inbound, backend, outbound или on-error. Нет
Path строка Задает вложенные политики, например: choose[3]/when[2]. Нет
PolicyId строка Значение атрибута id для политики, в которой произошла ошибка (если указано клиентом). No

Совет

Доступ к коду состояния можно получить с помощью context.Response.StatusCode.

Примечание.

Все политики имеют дополнительный атрибут id, который может быть добавлен к корневому элементу политики. Если этот атрибут присутствует в политике, в которой возникает ошибка, его значение можно извлечь с помощью свойства context.LastError.PolicyId.

Стандартные ошибки для встроенных шагов

Далее перечислены стандартные ошибки, которые могут возникать во время оценки встроенных шагов обработки.

Оригинал Condition Причина Сообщение
настройка URI не соответствует ни одному API или операции OperationNotFound Unable to match incoming request to an operation. (Не удалось сопоставить входящий запрос с операцией.)
авторизации Не предоставлен ключ подписки SubscriptionKeyNotFound Access denied due to missing subscription key. Make sure to include subscription key when making requests to this API. (Доступ запрещен из-за отсутствия ключа подписки. Обязательно включайте ключ подписки в запросы к этому API.)
авторизации Недопустимое значение ключа подписки SubscriptionKeyInvalid Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription. (Доступ запрещен из-за недопустимого ключа подписки. Укажите допустимый ключ активной подписки.)
несколько Нисходящее соединение (от клиента к шлюзу управления API) было прервано клиентом, пока запрос находился на рассмотрении ClientConnectionFailure несколько
несколько Восходящее соединение (от клиента к шлюзу управления API) было прервано клиентом, пока запрос находился на рассмотрении BackendConnectionFailure несколько
несколько Исключительная ситуация во время выполнения определенного выражения ExpressionValueEvaluationFailure несколько

Стандартные ошибки для политик

Далее перечислены стандартные ошибки, которые могут возникнуть во время оценки политик.

Оригинал Condition Причина Сообщение
rate-limit Превышено ограничение скорости RateLimitExceeded Rate limit is exceeded (Превышено ограничение скорости)
quota Превышена квота QuotaExceeded превышена квота на количество вызовов. Quota will be replenished in xx:xx:xx. (Квота будет пополнена в xx:xx:xx.) -или- Out of bandwidth quota. (Превышена квота пропускной способности.) Quota will be replenished in xx:xx:xx. (Квота будет пополнена в xx:xx:xx.)
jsonp Недопустимое значение параметра обратного вызова (содержит неправильные символы) CallbackParameterInvalid Value of callback parameter {callback-parameter-name} is not a valid JavaScript identifier. (Значение параметра обратного вызова {имя параметра обратного вызова} не является допустимым идентификатором JavaScript.)
ip-filter Не удалось проанализировать IP-адрес вызывающего объекта из запроса FailedToParseCallerIP Failed to establish IP address for the caller. Доступ запрещен.
ip-filter IP-адрес вызывающего объекта не входит в список разрешенных CallerIpNotAllowed Caller IP address {ip-address} is not allowed. Доступ запрещен.
ip-filter IP-адрес вызывающего объекта включен в список заблокированных CallerIpBlocked Caller IP address is blocked. Доступ запрещен.
check-header Отсутствует обязательный заголовок или его значение HeaderNotFound Header {header-name} was not found in the request. Доступ запрещен.
check-header Отсутствует обязательный заголовок или его значение HeaderValueNotAllowed Header {header-name} value of {header-value} is not allowed. Доступ запрещен.
validate-jwt В запросе отсутствует маркер JWT TokenNotPresent JWT отсутствует.
validate-jwt Ошибка при проверке подписи TokenSignatureInvalid <сообщение из библиотеки jwt>. Доступ запрещен.
validate-jwt Недопустимая аудитория TokenAudienceNotAllowed <сообщение из библиотеки jwt>. Доступ запрещен.
validate-jwt Недопустимый издатель TokenIssuerNotAllowed <сообщение из библиотеки jwt>. Доступ запрещен.
validate-jwt Истек срок действия маркера TokenExpired <сообщение из библиотеки jwt>. Доступ запрещен.
validate-jwt Ключ подписи не удалось разрешить по идентификатору TokenSignatureKeyNotFound <сообщение из библиотеки jwt>. Доступ запрещен.
validate-jwt В маркере отсутствуют необходимые утверждения TokenClaimNotFound В токене JWT отсутствуют следующие заявления: <c1>, <c2>, … Доступ запрещен.
validate-jwt Несоответствие значений утверждения TokenClaimValueNotAllowed Claim {claim-name} value of {claim-value} is not allowed. Доступ запрещен.
validate-jwt Прочие сбои при проверке данных JwtInvalid <сообщение из библиотеки jwt>
пересылка-запрос или отправка-запрос Код состояния ответа HTTP и заголовки не были получены от серверной части в течение настроенного тайм-аута Время ожидания несколько

Пример

Если задать политику API

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

и отправить неавторизованный запрос, появится следующий ответ:

Ответ при ошибке авторизации

Следующие шаги

Дополнительные сведения о работе с политиками см. в следующих статьях: