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

Обработка ошибок в политиках управления 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 можно использовать следующие политики.

ПоследняяОшибка

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

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

Совет

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

Примечание.

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

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

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

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

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

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

Исходный код Состояние Причина Сообщение
ограничение частоты Превышено ограничение скорости Превышено ограничение скорости запросов Rate limit is exceeded (Превышено ограничение скорости)
квота Превышена квота Квота превышена превышена квота на количество вызовов. 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 Недопустимое значение параметра обратного вызова (содержит неправильные символы) Недопустимый параметр обратного вызова Value of callback parameter {callback-parameter-name} is not a valid JavaScript identifier. (Значение параметра обратного вызова {имя параметра обратного вызова} не является допустимым идентификатором JavaScript.)
IP-фильтр Не удалось проанализировать IP-адрес вызывающего объекта из запроса Не удалось разобрать IP-адрес вызывающего абонента Не удалось установить IP-адрес вызывающего объекта. Доступ запрещен.
IP-фильтр IP-адрес вызывающего объекта не входит в список разрешенных Запрещённый IP вызывающего IP-адрес звонящего {ip-address} не разрешен. Доступ запрещен.
IP-фильтр IP-адрес вызывающего объекта включен в список заблокированных БлокировкаIPЗвонящего IP-адрес вызывающего абонента заблокирован. Доступ запрещен.
проверить заголовок Отсутствует обязательный заголовок или его значение ЗаголовокНеНайден В запросе не найден заголовок {header-name}. Доступ запрещен.
проверить заголовок Отсутствует обязательный заголовок или его значение ЗначениеЗаголовкаНеДопустимо Значение заголовка {header-name} равно {header-value} не допускается. Доступ запрещен.
проверка JWT JWT отсутствует в запросе Токен отсутствует JWT отсутствует.
проверка JWT Ошибка при проверке подписи Недействительная подпись токена <сообщение из библиотеки jwt>. Доступ запрещен.
проверка JWT Недопустимая аудитория АудиторияТокенаНеРазрешена <сообщение из библиотеки jwt>. Доступ запрещен.
проверка JWT Недопустимый издатель Выдающий токены не разрешен <сообщение из библиотеки jwt>. Доступ запрещен.
проверка JWT Истек срок действия маркера Срок действия токена истёк <сообщение из библиотеки jwt>. Доступ запрещен.
проверка JWT Ключ подписи не удалось разрешить по идентификатору Ключ подписи токена не найден <сообщение из библиотеки jwt>. Доступ запрещен.
проверка JWT В маркере отсутствуют необходимые утверждения Требование токена не найдено JWT отсутствуют следующие утверждения: <c1>, <c2>, ... Доступ запрещен.
проверка JWT Несоответствие значений утверждения Значение токена не разрешено Не допускается утверждение {claim-name} значения {claim-value}. Доступ запрещен.
проверка 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>

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

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

Связанный контент

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