Обработка ошибок

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X. Информация

При обработке запросов от приложений прокси API могут столкнуться с различными ошибками. Например, при взаимодействии с внутренними сервисами у прокси API могут возникнуть проблемы с сетью, приложения могут предоставлять учетные данные с истекшим сроком действия, запросы могут быть неправильно отформатированы и т. д.

Если после вызова клиентским приложением прокси-сервера API возникает ошибка, клиенту возвращается сообщение об ошибке. По умолчанию клиент получает сообщение об ошибке, которое часто бывает непонятным и не содержит подробностей или инструкций. Но если вы хотите заменить сообщения об ошибках по умолчанию более полезными пользовательскими сообщениями и даже дополнить их, например, дополнительными заголовками HTTP, вам нужно настроить обработку ошибок в Edge.

С помощью пользовательской обработки ошибок можно также добавлять такие функции, как ведение журнала сообщений при возникновении ошибки.

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

Видео

Чтобы узнать больше об обработке ошибок, посмотрите следующие видео:

Как возникают ошибки

Сначала мы расскажем о том, как возникают ошибки. Зная, как возникают ошибки, вы сможете планировать различные ситуации, в которых хотите реализовать собственную обработку ошибок.

Автоматические ошибки

Прокси-сервер API автоматически выдает ошибку в следующих ситуациях:

• Правило выдает ошибку. Например, если при вызове API отправляется ключ с истекшим сроком действия, правило VerifyAPIKey автоматически выдает ошибку. Если количество вызовов API превышает определенный лимит, правило Quota или правило SpikeArrest выдает ошибку. (Типы ошибок, которые могут возникать при нарушении правил, описаны в Справочнике по ошибкам правил.)
• Проблема в потоке сообщений прокси-сервера API, например ошибка маршрутизации.
• Произошла ошибка на сервере, например ошибка HTTP из-за сбоев на уровне протокола, ошибок TLS/SSL или недоступности целевого сервиса.
• Произошел сбой на уровне системы, например исключение из-за нехватки памяти.

Подробнее об этих ошибках можно узнать в разделе Классификация ошибок.

Собственные сообщения об ошибках

Если автоматическая ошибка не возникает, вы можете создать собственную. Например, если в ответе есть слово "недоступно" или код статуса HTTP больше 201. Для этого добавьте правило RaiseFault в нужное место потока прокси-сервера API.

Вы можете добавить правило RaiseFault в поток прокси-сервера API так же, как и любое другое правило. В примере конфигурации прокси-сервера ниже правило Raise-Fault-1 прикреплено к ответу TargetEndpoint. Если в ответе целевого сервиса есть слово "недоступно", выполняется правило RaiseFault и возникает ошибка.

<TargetEndpoint name="default">
...
  <Response>
    <Step>
      <Name>Raise-Fault-1</Name>
      <Condition>(message.content Like "*unavailable*")</Condition>
    </Step>
  </Response>

Это просто пример того, как можно создавать собственные ошибки. Подробнее о правиле RaiseFault рассказывается в разделе Правила FaultRules и правило RaiseFault.

Другие примеры можно найти на форуме сообщества Apigee:

• Как ссылаться на переменные JavaScript в RaiseFault

Что происходит с прокси API при возникновении ошибок

Вот что происходит, когда прокси-сервер выдает ошибку.

Как выйти из последовательности прокси

Когда в прокси-сервере API возникает ошибка, независимо от того, как она произошла, он выходит из обычного конвейера, переходит в состояние ошибки и возвращает сообщение об ошибке клиентскому приложению. После того как прокси-сервер API переходит в состояние ошибки, он не может вернуться к обычному конвейеру.

Например, предположим, что в запросе ProxyEndpoint прокси-сервера API есть правила в следующем порядке:

1. Как проверить ключ API
2. Квота
3. JSON в XML

Если при проверке ключа API возникает ошибка, прокси-сервер API переходит в состояние ошибки. Правила Quota и JSON to XML не выполняются, прокси-сервер не переходит к TargetEndpoint, а клиентскому приложению возвращается сообщение об ошибке.

Проверка наличия правил FaultRules

При возникновении ошибки прокси-серверы API также проверяют наличие следующих элементов (в указанном порядке) в конфигурации прокси-сервера API, прежде чем вернуть клиентскому приложению сообщение об ошибке по умолчанию:

1. Раздел <FaultRules>, в котором содержится логика для запуска специальных сообщений об ошибках (и других правил) на основе определенных условий, заданных вами.
2. Раздел <DefaultFaultRule>, который активирует сообщение об ошибке по умолчанию в следующих ситуациях:
   • Не определены никакие датчики <FaultRules>.
   • Не выполняется ни один существующий <FaultRules>.
   • Элемент <AlwaysEnforce> имеет значение true.

По сути, прокси API дает вам возможность вернуть собственное сообщение об ошибке и запустить другую логику. Если прокси-сервер не найдет ни одного из этих разделов или они будут существовать, но не будет активирована специальная ошибка, прокси-сервер отправит собственное сообщение по умолчанию, сгенерированное Edge.

Простой пример обработки ошибок

Начнем с простого примера, в котором вызов прокси-сервера API не содержит обязательный ключ API. По умолчанию клиентскому приложению возвращается следующий ответ:

HTTP/1.1 401 Unauthorized
Date: Wed, 20 Jul 2016 19:19:32 GMT
Content-Type: application/json
Content-Length: 150
Connection: keep-alive
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

Пользователи API могут понять сообщение об ошибке, но не обязаны это делать. А многие ошибки по умолчанию более незаметны и сложны для понимания.

Как разработчик API, вы можете изменить это сообщение в соответствии с потребностями тех, кто будет получать сообщение об ошибке, например разработчиков приложений для iOS или внутренней группы тестирования, у которой есть собственные требования к формату сообщений об ошибках.

Ниже приведен простой пример того, как создать собственное сообщение об ошибке для обработки этой ошибки. Для этого необходимо: 1) правило, определяющее пользовательское сообщение, и 2) правило FaultRule, которое выполняет это правило, когда прокси-сервер переходит в состояние ошибки.

1. Создайте правило, определяющее специальное сообщение

Сначала создайте правило, определяющее специальное сообщение об ошибке. Вы можете использовать любой тип правил, например AssignMessage, который позволяет задать полезную нагрузку и необязательные заголовки HTTP, такие как код статуса и фраза причины. Для этого идеально подходит функция "Назначить сообщение". Он позволяет управлять полезной нагрузкой сообщения, задавать другой код статуса HTTP, другую фразу причины HTTP и добавлять заголовки HTTP.

Не прикрепляйте правила к потокам в прокси-сервере API. Достаточно, чтобы он просто существовал в пакете прокси. Чтобы сделать это в редакторе прокси-сервера интерфейса управления, перейдите на вкладку Develop (Разработка) и на панели навигации нажмите на значок "+" на панели Policies (Правила).

Это позволяет создать правило, не прикрепляя его к потоку в прокси-сервере API. Правило, не привязанное ни к одному потоку, отмечается значком "Отключено" в списке правил, как показано рядом с правилом для сообщений с ключом API на предыдущем рисунке.

Ниже приведен пример правила AssignMessage, которое:

• Возвращает сообщение в формате JSON.
• Задает код статуса HTTP (911, который явно не существует, чтобы показать, насколько гибкими могут быть настройки). Код статуса появится в заголовке HTTP.
• Задает фразу причины HTTP (вместо фразы причины "Неавторизовано" по умолчанию для этой ошибки отсутствия ключа API). Фраза причины появляется рядом с кодом статуса в заголовке HTTP.
• Создает и заполняет новый HTTP-заголовок invalidKey.

<AssignMessage async="false" continueOnError="false" enabled="true" name="invalid-key-message">
    <DisplayName>Invalid key message</DisplayName>
    <Set>
        <Payload contentType="application/json">{"Citizen":"Where's your API key? I don't see it as a query parameter"}</Payload>
        <StatusCode>911</StatusCode>
        <ReasonPhrase>Rejected by API Key Emergency Services</ReasonPhrase>
    </Set>
    <Add>
        <Headers>
            <Header name="invalidKey">Invalid API key! Call the cops!</Header>
        </Headers>
    </Add>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>

При выполнении этого правила ответ клиентскому приложению будет выглядеть следующим образом: Сравните его с ответом по умолчанию, который был показан ранее.

HTTP/1.1 911 Rejected by API Key Emergency Services
Date: Wed, 20 Jul 2016 18:42:36 GMT
Content-Type: application/json
Content-Length: 35
Connection: keep-alive
invalidKey: Invalid API key! Call the cops!
Server: Apigee Router

* Connection #0 to host myorg-test.apigee.net left intact
{"Citizen":"Where's your API key? I don't see it as a query parameter."}

Да, это немного глупо, но зато показывает, что возможно. Теперь разработчик, получивший сообщение, знает, что забыл добавить ключ API в качестве параметра запроса.

Как это правило применяется на практике? в следующем разделе.

2. Создайте правило <FaultRule>, которое будет запускать правила.

В разделах <ProxyEndpoint> или <TargetEndpoint> конфигурации прокси-сервера добавьте XML-блок <FaultRules>, содержащий один или несколько отдельных разделов <FaultRule>. Каждое правило FaultRule представляет собой отдельную ошибку, которую вы хотите обработать. В этом простом примере мы используем только одно правило FaultRule, чтобы показать, из чего оно состоит.

Также следует добавить <DefaultFaultRule>, чтобы предоставить общее сообщение об ошибке, если ни одно из правил FaultRule не будет выполнено.

Пример

<ProxyEndpoint name="default">
...
    <FaultRules>
       <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Ключевые моменты:

• Правила обработки ошибок определяются в ProxyEndpoint. Это важно. Подробнее о том, как размещать FaultRules в ProxyEndpoint и TargetEndpoint, рассказывается ниже.
• <Name> – название правила, которое нужно выполнить. Название берется из атрибута name правила в родительском элементе, как показано в примере правила выше.

• <Condition> – Edge оценивает условие и применяет правило, только если условие истинно. Если несколько правил FaultRule оцениваются как истинные, Edge выполняет первое из них. (Важно! Порядок оценки правил FaultRule (сверху вниз или снизу вверх) зависит от того, какой конечной точки они касаются – целевой или прокси. Подробнее об этом рассказывается в разделе Несколько правил FaultRule и логика их выполнения.) Если условие не указано, FaultRule автоматически принимает значение true. Но это не лучший вариант. У каждого правила FaultRule должно быть собственное условие.

• <DefaultFaultRule> – если не выполняется ни одно пользовательское правило FaultRule, выполняется правило <DefaultFaultRule>, отправляющее более общее пользовательское сообщение вместо непонятного сообщения по умолчанию, сгенерированного Edge. В отличие от пользовательского правила <FaultRule>, правило <DefaultFaultRule> не оценивает внешний элемент <Condition> на уровне правила. Чтобы условно выполнить правило в элементе <DefaultFaultRule>, добавьте внутренний элемент <Condition> в элемент <Step> внутри <DefaultFaultRule>.

  Правило DefaultFaultRule обычно используется для возврата общего сообщения об ошибке при любой непредвиденной ошибке. Например, это может быть письмо с контактной информацией службы технической поддержки. Ответ по умолчанию выполняет две функции: предоставляет удобную для разработчиков информацию и скрывает URL или другие данные, которые могут быть использованы для взлома системы.

Несколько правил FaultRule и логика выполнения

В разделе Пример простого обработчика ошибок мы использовали простой пример с одним правилом FaultRule и условием. В реальном проекте API, где может возникнуть множество ошибок, скорее всего, у вас будет несколько правил FaultRule и одно правило DefaultFaultRule в <ProxyEndpoint> и <TargetEndpoint>. Однако при возникновении ошибки в прокси-сервере API выполняется только одно правило FaultRule.

В этом разделе описывается логика, которую Edge использует при обработке FaultRule, начиная с того, как выбирается одна FaultRule для выполнения, и заканчивая тем, как обрабатываются условия "внутренних" шагов при срабатывании их FaultRule. В этом разделе также приведены рекомендации о том, когда следует определять FaultRules в <ProxyEndpoint> и <TargetEndpoint>, и описана связь между FaultRules и правилом RaiseFault.

Выполнение правил обработки ошибок

Ниже описана логика, которую Edge использует, когда прокси-сервер API переходит в состояние ошибки. Обратите внимание, что оценка FaultRules в ProxyEndpoint и TargetEndpoint немного отличается.

1. Edge оценивает правила FaultRules в ProxyEndpoint или TargetEndpoint в зависимости от того, где произошла ошибка:
   • ProxyEndpoint – Edge начинает с нижнего <FaultRule> в XML-файле конфигурации и движется вверх, оценивая <Condition> каждого <FaultRule> (внешнее условие, а не внутренние условия <Step>).
   • TargetEndpoint – Edge начинает с верхнего тега <0x0A> <FaultRule> в XML-файле конфигурации и движется вниз, оценивая тег <Condition> каждого тега <FaultRule> (внешнее условие, а не внутренние условия <Step>).
2. Выполняет первое правило FaultRule, условие которого истинно. Если в FaultRule нет условия, по умолчанию оно считается истинным.
   • Когда выполняется FaultRule, все шаги внутри FaultRule оцениваются по порядку, сверху вниз в конфигурации XML. Шаги без условий выполняются автоматически (применяются правила), а шаги с условием <Condition>, которое оценивается как "истина", выполняются (условия, которые оцениваются как "ложь", не выполняются).

   • Если правило FaultRule выполняется, но ни один из шагов в нем не выполняется (поскольку их условия оцениваются как "false"), клиентскому приложению возвращается сообщение об ошибке по умолчанию, сгенерированное Edge. <DefaultFaultRule> не выполняется, поскольку Edge уже выполнил одно правило FaultRule.

3. Если ни одно правило FaultRule не выполняется, Edge выполняет правило <DefaultFaultRule>, если оно присутствует.

Ниже приведены примеры с комментариями.

Выполнение ProxyEndpoint

Правила FaultRule для ProxyEndpoint оцениваются снизу вверх, поэтому начните с последнего правила FaultRule в приведенном ниже примере и двигайтесь вверх. Правило DefaultFaultRule следует рассматривать в последнюю очередь.

<ProxyEndpoint name="default">
...
    <FaultRules>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer"
     condition. But because the FaultRule just below this got
     executed (bottom-to-top evaluation in a ProxyEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed.
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
<FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 1. Because this is the ProxyEndpoint, Edge looks at this FaultRule
     first. But let's say this FaultRule is FALSE. A policy did not
     throw a FailedToResolveAPIKey error. Edge moves UP to check
     the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed.
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Выполнение TargetEndpoint

Правила FaultRule для TargetEndpoint оцениваются сверху вниз, поэтому начните с первого правила FaultRule в приведенном ниже примере и двигайтесь вниз. Правило DefaultFaultRule следует рассматривать в последнюю очередь.

<TargetEndpoint name="default">
...
    <FaultRules>
<!-- 1. Because this is the TargetEndpoint, Edge looks at this FaultRule
     first. Let's say this FaultRule is FALSE.
     A policy did not throw a FailedToResolveAPIKey error.
     Edge moves down to the next FaultRule. -->
        <FaultRule name="invalid_key_rule">
            <Step>
                <Name>invalid-key-message</Name>
            </Step>
            <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
        </FaultRule>
<!-- 2. Let's say this fault is TRUE. The Quota policy threw a QuotaViolation
     error. This is the first FaultRule to be TRUE, so it's executed.
     Now the Steps are evaluated, and for the ones whose conditions
     evaluate to TRUE, their policies are executed. Steps without
     conditions are automatically true. -->
        <FaultRule name="over_quota">
            <Step>
                <Name>developer-over-quota-fault</Name>
                <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>global-over-quota-fault</Name>
                <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
            </Step>
            <Step>
                <Name>log-error-message</Name>
            </Step>
            <Condition>(fault.name = "QuotaViolation")</Condition>
        </FaultRule>
<!-- 3. This FaultRule is automatically TRUE, because there's no "outer"
     condition. But because the FaultRule just above this got
     executed (top-to-bottom evaluation in a TargetEndpoint), Edge
     doesn't even evaluate this FaultRule.
     Note that it's not a best practice to have a FaultRule without
     an outer condition, which automatically makes the FaultRule true. -->
        <FaultRule name="random-error-message">
            <Step>
                <Name>Random-fault</Name>
            </Step>
        </FaultRule>
    </FaultRules>

<!-- If no <FaultRule> is executed, the <DefaultFaultRule> is executed.
     If a FaultRule is executed, but none of its Steps are executed,
     The DefaultFaultRule is not executed (because Edge has already
     executed its one FaultRule). -->
    <DefaultFaultRule name="default-fault">
        <Step>
            <Name>Default-message</Name>
        </Step>
    </DefaultFaultRule>

Порядок правил обработки ошибок

Как видно из предыдущего примера, порядок, в котором вы размещаете FaultRules, важен в зависимости от того, возникает ли ошибка в ProxyEndpoint или TargetEndpoint.

Пример:

Правила, которые нужно добавить

Вы можете выполнить любые правила из FaultRule, поместив их в Steps. Например, вы можете выполнить правило AssignMessage, чтобы отформатировать ответ для клиентского приложения, а затем зарегистрировать сообщение с помощью правила MessageLogging. Правила выполняются в том порядке, в котором они указаны в XML-файле (сверху вниз).

Правила обработки ошибок срабатывают ТОЛЬКО при возникновении ошибки (о continueOnError)

Заголовок может показаться повторением, но есть один нюанс, о котором нужно знать в отношении ошибки прокси-сервера, из-за которой прокси-сервер API переходит в состояние ошибки, или, скорее, не переходит в состояние ошибки: атрибут continueOnError в правиле.

Напоминаем, что прокси-сервер API оценивает <FaultRules> и <DefaultFaultRule> только в том случае, если прокси-сервер перешел в состояние ошибки. Это означает, что даже если условие FaultRule оценивается как истинное, оно не будет активировано, если прокси-сервер не находится в состоянии ошибки.

Однако ниже приведен пример ошибки, при которой прокси-сервер не переходит в состояние ошибки. В любом правиле можно задать атрибут continueOnError для родительского элемента. Этот атрибут очень важен для обработки ошибок, поскольку он определяет, переходит ли прокси-сервер в состояние ошибки при сбое правила. В большинстве случаев рекомендуется оставить значение по умолчанию continueOnError="false", при котором прокси-сервер переходит в состояние ошибки, если не удается выполнить правило, и запускается обработка ошибок, заданная вами. Однако, если вы не хотите, чтобы сбой вызова сервиса останавливал выполнение прокси, continueOnError="true" (например, если вы не хотите, чтобы сбой вызова сервиса останавливал выполнение прокси), прокси не перейдет в состояние ошибки, если это правило не будет выполнено, и прокси не будет проверять FaultRules.

Информацию о том, как регистрировать ошибки при использовании continueOnError="true", можно найти в разделе Обработка ошибок правил в текущем потоке.

Где определять правила FaultRules: в ProxyEndpoint или TargetEndpoint

Если в прокси-сервере API возникает ошибка, она происходит либо в <ProxyEndpoint> (запрос от клиентского приложения или ответ на него), либо в <TargetEndpoint> (запрос к целевому сервису или ответ от него). Именно в том месте, где возникает ошибка, Edge ищет FaultRules.

Например, если целевой сервер недоступен (код статуса HTTP 503), прокси-сервер API перейдет в состояние ошибки в ответе <TargetEndpoint>, и обычный поток прокси-сервера API не будет продолжаться до <ProxyEndpoint>. Если вы определили FaultRules только в <ProxyEndpoint>, они не смогут обработать эту ошибку.

Вот ещё один пример. Если правило RaiseFault в ответе <ProxyEndpoint> вызывает ошибку, правило FaultRule в <TargetEndpoint> не выполняется.

Правила FaultRules и правило RaiseFault

Правила обработки ошибок и правило RaiseFault могут показаться альтернативными способами обработки ошибок, и в некотором смысле это так. но они также работают вместе. В этом разделе объясняется, как они связаны. Понимание этой взаимосвязи поможет вам разработать стратегию обработки ошибок, особенно если вы хотите использовать оба типа.

Вкратце:

• Правила обработки ошибок всегда оцениваются, когда прокси-сервер API переходит в состояние ошибки.

• Правило RaiseFault позволяет перевести прокси-сервер API в состояние ошибки, если в противном случае ошибка бы не возникла.

  Например, если вы хотите, чтобы при получении от целевого сервиса ответа с кодом статуса HTTP больше 200 возникала ошибка, добавьте в поток ответов правило RaiseFault. В этом случае URL будет выглядеть примерно так:

  <TargetEndpoint name="default">
      <PreFlow name="PreFlow">
  ...
          <Response>
              <Step>
                  <Name>Raise-Fault-1</Name>
  <!-- If the condition is true, the Raise-Fault-1 policy gets executed -->
                  <Condition>(response.status.code GreaterThan "200")</Condition>
              </Step>
          </Response>

  Правило RaiseFault также отправляет сообщение об ошибке клиентскому приложению.

Что происходит, когда правило RaiseFault вызывает ошибку, из-за которой прокси-сервер переходит в состояние ошибки и потенциально выполняет правило FaultRule? Здесь всё немного сложнее. Если правило RaiseFault возвращает сообщение об ошибке и срабатывает правило FaultRule и возвращает сообщение об ошибке, что будет возвращено клиентскому приложению?

• Поскольку FaultRule или DefaultFaultRule выполняется после правила RaiseFault, данные ответа FaultRule имеют приоритет.
• Данные ответа правила RaiseFault (код статуса, фраза причины или полезная нагрузка сообщения) используются, если эти данные не заданы в FaultRule или DefaultFaultRule.
• Если и правило RaiseFault, и правило FaultRule добавляют специальные заголовки HTTP, оба заголовка включаются в ответ. Если имена заголовков повторяются, создается заголовок с несколькими значениями.

Ниже приведен пример того, что задается правилом RaiseFault и FaultRule и что возвращается клиентскому приложению. Примеры приведены в сокращенном виде и не отражают рекомендации по использованию.

Status Code: 468
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header:
  errorNote: woops,gremlins

Status Code: [none]
Reason Phrase: Something happened
Payload: {"Whoa":"Sorry."}
Header:
  errorNote: gremlins

Status Code: 468
Reason Phrase: Can't do that
Payload: {"DOH!":"Try again."}
Header:
  errorNote: woops

Как создавать условия

Условия – это ключевой элемент выполнения FaultRule. Условия FaultRule создаются так же, как и другие условия в Edge, например для условных потоков или условий RaiseFault.

Чтобы лучше понять остальную часть этого раздела, приведем пример правила обработки ошибок с внешним условием FaultRule и внутренним условием Step.

<FaultRule name="invalid_key_rule">
    <Step>
        <Name>invalid-key-message</Name>
        <Condition>(oauthV2.Verify-API-Key-1.failed = true)</Condition>
    </Step>
    <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
</FaultRule>

Переменные, относящиеся к ошибкам правил

Переменные fault.name и {policy_namespace}.{policy_name}.failed доступны, когда правило вызывает ошибку.

fault.name

Если правило не выполняется, перехватите ошибку в условии, используя переменную fault.name. Пример:

<Condition>(fault.name = "policy_error_name")</Condition>

Название ошибки будет указано в сообщении об ошибке по умолчанию. Например, в приведенном ниже коде имя ошибки – FailedToResolveAPIKey. В этом случае переменная потока fault.name получает значение FailedToResolveAPIKey.

{"fault":{"faultstring":"Failed to resolve API Key variable request.queryparam.apikey","detail":{"errorcode":"steps.oauth.v2.FailedToResolveAPIKey"}}}

В результате условие будет выглядеть так:

<Condition>(fault.name = "FailedToResolveAPIKey")</Condition>

Список ошибок приведен в справочнике по ошибкам правил.

{policy_namespace}.{policy_name}.failed

Переменная *.failed доступна, когда не удается применить правило. Ниже приведены примеры переменных *.failed для разных правил. Информацию о пространствах имен правил можно найти в разделе переменных потока в каждом справочном разделе о правилах.

• Правило RaiseFault: raisefault.failed (одинаково для всех правил RaiseFault)
• Правило VerifyAPIKey: oauthV2.{policy_name}.failed, например oauthV2.Verify-API-Key-1.failed.
• Правила квоты и правила SpikeArrest: ratelimit.{policy_name}.failed, например, ratelimit.Quota-1.failed

Другие доступные переменные

Когда прокси-сервер API переходит в состояние ошибки, в условиях можно использовать только следующие переменные:

• Переменные правила, которое не удалось применить.
• Переменные HTTP-сообщений, которые существуют в момент сбоя. Например, если в ответе возникает ошибка, правило FaultRule в <TargetEndpoint> может использовать данные HTTP response.status.code, message.content, error.content и т. д. Если не удалось применить правило квоты, можно использовать переменную ratelimit.{quota_policy_name}.exceed.count. Чтобы узнать, какие переменные и данные HTTP доступны, используйте инструмент трассировки и справочные статьи о правилах.

Дополнительная информация

• Условия: справочник по условиям и переменные и условия потока.

• Ошибки: Справочник по ошибкам правил
• Переменные. См. справочную информацию о переменных и отдельные страницы справочной информации о правилах, чтобы узнать, какие переменные доступны для каждого правила.

Рекомендации по обработке ошибок

Обработка ошибок – важная задача при разработке архитектуры прокси-сервера API. Важно заранее продумать, как и когда вы будете обрабатывать ошибки, какие сообщения об ошибках будут показываться и в каком формате. После того как вы определитесь с этими вопросами, следуйте приведенным ниже рекомендациям, чтобы реализовать обработку ошибок.

Ниже приведены некоторые рекомендации по проектированию и созданию обработчиков ошибок.

• Для каждого правила FaultRule укажите внешний элемент <Condition> (на одном уровне с элементом <Step>). Правила обработки ошибок без внешнего условия автоматически оцениваются как истинные. Условия внутреннего шага не используются для определения того, является ли правило FaultRule истинным или ложным. Условия шага оцениваются только после того, как Edge выполнит FaultRule, содержащий их. В FaultRule обычно несколько этапов с политиками Assign Message (или другими), у каждого из которых есть условие Step.

• Чтобы обрабатывать ошибки в нескольких правилах одного типа (например, в нескольких правилах Quota), создайте по одному правилу FaultRule для каждой ошибки, которую вы можете получить. Например, создайте правило FaultRule для каждой вероятной ошибки в правилах квоты, такой как QuotaViolation, InvalidMessageWeight или StartTimeNotSupported. Подробнее об ошибках, связанных с нарушением правил… Если вы обнаружите другие ошибки, которые нужно обработать, вы сможете вернуться к этому шагу позже и добавить их в FaultRules. Итеративный подход допустим, но требует повторного развертывания прокси. Этот подход позволяет обнаруживать ошибки одного типа независимо от того, какое правило их вызывает, что делает XML-код FaultRules более эффективным.

  Если вам нужен более точный контроль ошибок, используйте условия внутреннего шага. Например, если вы применяете квоту для отдельного разработчика и глобальную квоту с помощью двух правил в потоке запросов, задайте для условия "внешнего" правила FaultRule триггер на ошибку QuotaViolation (которая возникает, когда квота превышена в любом случае). Затем задайте условия шага, чтобы оценить переменные exceed.count в обоих правилах квоты. Клиенту отправляется только соответствующая ошибка (превышение квоты разработчика или глобальной квоты). Вот пример такой конфигурации:

  <FaultRule name="over_quota">
  <!-- This condition catches a QuotaViolation in *any* Quota policy -->
    <Condition>(fault.name = "QuotaViolation")</Condition>
    <Step>
      <Name>developer-over-quota-fault</Name>
      <Condition>(ratelimit.developer-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
    <Step>
      <Name>global-over-quota-fault</Name>
      <Condition>(ratelimit.global-quota-policy.exceed.count GreaterThan "0")</Condition>
    </Step>
  </FaultRule>

  Ещё один пример можно найти в этой теме на форуме сообщества Apigee.

• Чтобы обрабатывать ошибки при использовании одного правила одного типа, создайте правило обработки ошибок, которое будет выполняться при сбое этого правила, и добавьте несколько шагов, соответствующих каждой возможной ошибке. Это позволяет сделать XML-код более эффективным, поскольку используется одно правило FaultRule вместо нескольких (по одному для каждого типа ошибки). Пример:

  <FaultRule name="raise-fault-3">
  <!-- This condition catches *any* error in the Verify-API-Key-1 policy. -->
    <Condition>(oauthV2.Verify-API-Key-1.failed = "true")</Condition>
    <!-- This first step always executes, which handles errors you haven't mapped with inner conditions. -->
    <Step>
      <Name>Generic-Key-Fault</Name>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-1</Name>
      <Condition>(fault.name = "FailedToResolveAPIKey")</Condition>
    </Step>
    <Step>
      <Name>Assign-Message-Raise-Fault-2</Name>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </Step>
  </FaultRule>

• Добавьте FaultRules в те места, где могут возникнуть ошибки (на стороне клиента <ProxyEndpoint> или на стороне целевого сервиса <TargetEndpoint>). Добавьте FaultRules для каждого правила, которое появляется в каждом месте.
• В FaultRules можно выполнять любые правила, которые могут возвращать сообщение клиентскому приложению. Для этого идеально подходит правило AssignMessage. Если вы хотите отслеживать ошибки, также можно зарегистрировать сообщение с помощью правила MessageLogging.
• При использовании правил RaiseFault вместе с FaultRules необходимо координировать данные ответа, которые отправляются, когда и правило RaiseFault, и правило FaultRule возвращают данные. Например, если правило RaiseFault сбрасывает код статуса HTTP, не нужно, чтобы правило FaultRule сбрасывало код статуса. В худшем случае клиентскому приложению будет возвращен код статуса по умолчанию.
• <DefaultFaultRule> execution:
  • <DefaultFaultRule> выполняется автоматически, если не выполняется ни одно другое правило FaultRule. Не добавляйте дочерний элемент <Condition> на уровне правила в элемент <DefaultFaultRule>. Чтобы условно выполнить правило внутри элемента <DefaultFaultRule>, поместите элемент <Condition> в дочерний элемент <Step>.
  • Если вы хотите, чтобы <DefaultFaultRule> всегда выполнялся, даже если был выполнен другой элемент FaultRule, добавьте дочерний элемент <AlwaysEnforce>true</AlwaysEnforce>.

Шаблон для централизованной обработки ошибок, который можно использовать повторно

В следующем сообщении на форуме Apigee Community описан шаблон централизованной обработки ошибок без дублирования кода:

Шаблон обработки ошибок для прокси-серверов Apigee

Создание правил FaultRules

Чтобы добавить FaultRule, вам нужно изменить конфигурацию XML ProxyEndpoint или TargetEndpoint. Чтобы внести это изменение в интерфейсе Edge, откройте панель Code в представлении Develop (Разработка) для прокси-сервера API или измените XML-файл, в котором определен ProxyEndpoint или TargetEndpoint.

Если вы создаете FaultRules в интерфейсе управления, сначала создайте правила, которые хотите выполнить, а затем добавьте их в конфигурацию FaultRule. Если вы попытаетесь сохранить правило FaultRule, ссылающееся на ещё не созданное правило, в интерфейсе появится сообщение об ошибке.

Как добавить правила в FaultRule

В FaultRule можно указать любое правило, но обычно используется AssignMessage, чтобы создать специальное сообщение об ошибке. AssignMessage позволяет настроить HTTP-ответ с элементами полезной нагрузки, кода статуса HTTP, заголовков и фразы причины.

Ниже приведен пример типичной конфигурации правила AssignMessage:

<AssignMessage name="fault_invalidkey">
  <Set>
      <Payload contentType="text/plain">Contact support at support@mycompany.com.</Payload>
      <StatusCode>401</StatusCode>
      <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

Теперь вы можете использовать это правило в FaultRule. Обратите внимание, как в FaultRule упоминается правило AssignMessage по названию:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>fault_invalidkey</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Когда вы развернете указанную выше конфигурацию, прокси-сервер API будет выполнять правило AssignMessage под названием fault_invalidkey всякий раз, когда приложение будет предоставлять недействительный ключ API.

В FaultRule можно выполнить несколько правил, как показано в следующем примере:

<ProxyEndpoint name="default">
  ...
  <FaultRules>
    <FaultRule name="invalid_key_rule">
      <Step>
        <Name>policy1</Name>
      </Step>
      <Step>
        <Name>policy2</Name>
      </Step>
      <Step>
        <Name>policy3</Name>
      </Step>
      <Condition>(fault.name = "InvalidApiKey")</Condition>
    </FaultRule>
  </FaultRules>
</ProxyEndpoint>

Правила выполняются в заданном порядке. Например, можно использовать правило MessageLogging, правило ExtractVariables, правило AssignMessage или любое другое правило в FaultRule. Обратите внимание, что обработка FaultRule немедленно прекращается, если происходит одно из следующих событий:

• Любое правило в FaultRule вызывает ошибку.
• Одно из правил в FaultRule имеет тип RaiseFault.

Как задать пользовательское сообщение об ошибке, возвращаемое из FaultRule

Рекомендуем задать понятные ответы об ошибках в ваших API. Таким образом вы будете предоставлять клиентам актуальную и полезную информацию.

В следующем примере правила AssignMessage используются теги <Payload>, <StatusCode> и <ReasonPhase>, чтобы определить специальный ответ об ошибке, который отправляется клиенту при ошибке InvalidApiKey (см. предыдущий пример FaultRules).

<AssignMessage name="fault_invalidkey">
  <Set>
    <Payload contentType="text/plain">You have attempted to access a resource without the correct authorization.
       Contact support at support@mycompany.com.</Payload>
    <StatusCode>401</StatusCode>
    <ReasonPhrase>Unauthorized</ReasonPhrase>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>

В ответе:

• Полезная нагрузка, содержащая сообщение об ошибке и адрес электронной почты для связи со службой поддержки.
• Код статуса HTTP, возвращенный в ответе.
• Фраза причины – краткое описание ошибки.

Создание DefaultFaultRule

DefaultFaultRule действует как обработчик исключений для любой ошибки, которая не обрабатывается явно другим правилом FaultRule. Если условия ни одного из правил FaultRule не соответствуют ошибке, ее обрабатывает правило DefaultFaultRule. Чтобы включить обработку ошибок по умолчанию, добавьте тег <DefaultFaultRule> в качестве дочернего элемента ProxyEndpoint или TargetEndpoint.

Например, в приведенной ниже конфигурации TargetEndpoint определено правило DefaultFaultRule, которое вызывает правило ReturnGenericError:

<TargetEndpoint name="default">
  ...
  <FaultRules>
    ...
  </FaultRules>

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
  </DefaultFaultRule>

  <HTTPTargetConnection>
    <URL>http://mocktarget.apigee.net</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Правило DefaultFaultRule обычно используется для возврата общего сообщения об ошибке при возникновении непредвиденной ошибки, например сообщения, содержащего контактную информацию службы технической поддержки. Ответ по умолчанию выполняет две функции: предоставляет удобную для разработчиков информацию и скрывает URL внутренних ресурсов или другие данные, которые могут быть использованы для взлома системы.

Например, вы можете определить следующие правила AssignMessage, чтобы возвращать общую ошибку:

<AssignMessage name="ReturnGenericError">
  <Set>
    <Payload type="text/plain">SERVICE UNAVAILABLE. PLEASE CONTACT SUPPORT: support@company.com.</Payload>
  </Set>
</AssignMessage>

Добавьте элемент <AlwaysEnforce> в тег <DefaultFaultRule>, чтобы правило DefaultFaultRule выполнялось при каждой ошибке, даже если другое правило FaultRule уже было выполнено. Правило DefaultFaultRule всегда выполняется последним:

  <DefaultFaultRule name="fault-rule">
    <Step>
      <Name>ReturnGenericError</Name>
    </Step>
    <AlwaysEnforce>true</AlwaysEnforce>
  </DefaultFaultRule>

Правило DefaultFaultRule можно использовать, чтобы определить тип ошибки, когда другими способами это сделать не удается. Например, прокси-сервер API не работает из-за ошибки, которую вы не можете определить. Используйте DefaultFaultRule, чтобы вызвать следующее правило AssignMessage. Это правило записывает значение fault.name в заголовок DefaultFaultHeader в ответе:

<AssignMessage async="false" continueOnError="false" enabled="true" name="DefaultFaultRule">
  <DisplayName>DefaultFaultRule</DisplayName>
  <Set>
    <Headers>
      <Header name="DefaultFaultHeader">{fault.name}</Header>
    </Headers>
  </Set>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

Затем вы можете посмотреть заголовок в инструменте трассировки Edge или в ответе, чтобы узнать, что вызвало ошибку.

Добавление регистрации сообщений в PostClientFlow

PostClientFlow – единственный поток, который выполняется после того, как прокси-сервер переходит в состояние ошибки. К этому потоку можно прикрепить только правило MessageLogging, которое выполняется после того, как ответ отправляется клиенту. Хотя прикрепление правила MessageLogging к этому потоку технически не является обработкой ошибок, вы можете использовать его для регистрации информации в случае ошибки. Поскольку он выполняется независимо от того, удалось ли прокси-серверу подключиться, вы можете разместить правила регистрации сообщений в PostClientFlow и быть уверенными, что они всегда будут выполняться.

Обработка ошибок, связанных с правилами, в текущем процессе

В приведенных выше примерах для обработки ошибок правил в рамках состояния ошибки используется FaultRule в ProxyEndpoint или TargetEndpoint. Это связано с тем, что значение по умолчанию элемента continueOnError правила – false. Это означает, что при возникновении ошибки в правиле управление переходит в состояние ошибки. После того как произошла ошибка, вы не можете вернуть управление в обычный конвейер и обычно возвращаете вызывающему приложению сообщение об ошибке.

Однако если для правила задать для элемента continueOnError значение true, управление останется в текущем потоке, и следующее правило в конвейере будет выполнено после правила , вызвавшего ошибку. Преимущество обработки ошибки в текущем потоке заключается в том, что вы можете устранить ее и завершить обработку запроса.

Ниже показано правило VerifyAPIKey с названием verify-api-key, в котором для элемента continueOnError задано значение true:.

<VerifyAPIKey async="false" continueOnError="true" enabled="true" name="verify-api-key">
  <DisplayName>Verify API Key</DisplayName>
  <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

Если ключ API отсутствует или недействителен, правило VerifyAPIKey присваивает переменной oauthV2.verify-api-key.failed значение true, но обработка продолжается в текущем потоке.

Затем добавьте правило VerifyAPIKey в качестве шага в PreFlow ProxyEndpoint:

<ProxyEndpoint name="default">
  ...
  <PreFlow name="PreFlow">
    <Request>
      <Step>
        <Name>verify-api-key</Name>
      </Step>
      <Step>
        <Name>FaultInFlow</Name>
        <Condition>(oauthV2.verify-api-key.failed = "true")</Condition>
      </Step>
    </Request>
    <Response/>
  </PreFlow>
</ProxyEndpoint>

Обратите внимание, что на следующем шаге в PreFlow используется условие для проверки наличия ошибки. Если в правиле VerifAPIKey произошла ошибка, выполняется правило FaultInFlow. В противном случае правило FaultInFlow пропускается. Правило FaultInFlow может выполнять различные действия, например регистрировать ошибку, пытаться исправить ее или выполнять другие действия.

Как вызвать ошибку с помощью правила RaiseFault

Вы можете использовать правило RaiseFault в любой момент потока, чтобы вызвать ошибку. Когда выполняется правило RaiseFault, текущий поток завершается и управление передается в состояние ошибки.

Одно из применений правила RaiseFault – проверка на наличие определенного условия, которое другое правило может не обнаружить. В примере выше вы добавили тег <Condition> в тег PreFlow <Step>, в результате чего при выполнении условия будет выполняться правило FaultInFlow. Если FaultInFlow – это правило RaiseFault, управление переходит в состояние ошибки. Или вы можете вставить правило RaiseFault в поток, чтобы отладить и протестировать правила FaultRules.

Когда правило RaiseFault вызывает ошибку, вы можете использовать следующее правило FaultRule и условие для ее обработки:

<FaultRule name="raisefault_rule">
  <Step>
    <Name>{policy_name}</Name>
  </Step>
  <Condition>(fault.name = "RaiseFault")</Condition>
</FaultRule>

Обратите внимание, что условие проверяет наличие ошибки с названием RaiseFault. Правило RaiseFault всегда задает для переменной fault.name значение RaiseFault.

Специальная обработка кодов ошибок HTTP от целевого сервера

Примеры, приведенные в предыдущих разделах, относятся к ошибкам, вызванным правилами. Однако вы также можете создать собственный ответ для ошибок на уровне транспорта, то есть ошибок HTTP, возвращаемых целевым сервером. Чтобы управлять ответом на ошибку HTTP, настройте TargetEndpoint для обработки кодов ответа HTTP.

По умолчанию Edge рассматривает коды HTTP-ответов в диапазоне 1xx–3xx как успешные, а коды HTTP-ответов в диапазоне 4xx–5xx – как неудачные. Это означает, что любой ответ от внутреннего сервиса с кодом ответа HTTP 4xx-5xx автоматически вызывает состояние ошибки, которое затем возвращает сообщение об ошибке непосредственно запрашивающему клиенту.

Вы можете создать специальные обработчики для любых кодов HTTP-ответа. Например, вы можете не считать все HTTP-ответы в диапазоне 4xx–5xx ошибками, а только 5xx, или возвращать специальные сообщения об ошибках для кодов ответа HTTP 400 и 500.

В следующем примере вы используете свойство success.codes, чтобы настроить TargetEndpoint так, чтобы коды HTTP-ответа 400 и 500 считались успешными наряду с кодами HTTP по умолчанию. Если рассматривать эти коды как успешные, TargetEndpoint будет обрабатывать ответное сообщение, а не вызывать состояние ошибки.

<TargetEndpoint name="default">
  ...
  <HTTPTargetConnection>
    <Properties>
          <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Как видно из этого примера, вы можете использовать подстановочные знаки, чтобы задать для свойства success.codes диапазон значений.

Если задать свойство success.codes, значения по умолчанию будут перезаписаны. Поэтому, если вы хотите добавить код HTTP 400 в список кодов успешного выполнения по умолчанию, задайте для этого свойства следующее значение:

<Property name="success.codes">1xx,2xx,3xx,400</Property>

Если вы хотите, чтобы код HTTP 400 считался кодом успешного выполнения, задайте следующее значение свойства:

<Property name="success.codes">400</Property>

Теперь вы можете задавать собственные обработчики для кодов ответа HTTP 400 и 500, чтобы возвращать приложению, отправившему запрос, специальное сообщение. В следующем TargetEndpoint используется правило ReturnError для обработки кодов ответа HTTP 400 и 500:

<TargetEndpoint name="default">
  <PreFlow name="PreFlow">
    <Request/>
    <Response>
      <Step>
        <Name>ReturnError</Name>
        <Condition>(response.status.code = 400) or (response.status.code = 500)</Condition>
      </Step>
    </Response>
  </PreFlow>

  <HTTPTargetConnection>
    <Properties>
      <Property name="success.codes">1xx,2xx,3xx,400,500</Property>
    </Properties>
    <URL>http://weather.yahooapis.com</URL>
  </HTTPTargetConnection>
</TargetEndpoint>

Эта конфигурация TargetEndpoint приводит к тому, что правило ReturnError обрабатывает HTTP-ответ, когда TargetEndpoint сталкивается с кодом ответа 400 или 500.

Таксономия неисправностей

Сервисы API делят ошибки на следующие категории и подкатегории.

Вместе с ошибкой всегда приводится текстовое описание причины сбоя. Когда система обнаруживает ошибку, заполняется набор атрибутов, которые помогают устранить неполадку. Ошибка содержит следующие сведения:

• Причина
• Настраиваемые атрибуты, заданные пользователем