Обработка ошибок в политиках управления 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 можно использовать следующие политики.
- choose
- set-variable
- find-and-replace
- return-response
- set-header
- set-method
- set-status
- send-request
- send-one-way-request
- log-to-eventhub
- json-to-xml
- xml-to-json
- ограничение параллелизма
- mock-response
- повтор
- trace
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>
и отправить неавторизованный запрос, появится следующий ответ:
Следующие шаги
Дополнительные сведения о работе с политиками см. в следующих статьях:
- Политики в управлении API
- Преобразование API-интерфейсов.
- Полный перечень операторов политик и их параметров см. в справочнике по политикам.
- Примеры политик.