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

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

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

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

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

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

Видео

Посмотрите следующие видеоролики, чтобы узнать больше об обработке ошибок.

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

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

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

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

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

Для получения более подробной информации об этих ошибках см. раздел «Классификация ошибок» в этой теме.

Пользовательские ошибки

В ситуациях, когда автоматическая ошибка не возникает, вы можете сгенерировать пользовательскую ошибку; например, если ответ содержит слово «unavailable» или если код состояния HTTP больше 201. Для этого добавьте политику RaiseFault в соответствующее место в потоке API-прокси.

Добавить политику RaiseFault в поток API-прокси можно так же, как и любую другую политику. В следующем примере конфигурации прокси политика Raise-Fault-1 прикреплена к ответу TargetEndpoint. Если в ответе от целевой службы присутствует слово "unavailable", политика 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-прокси не может возобновить обработку в обычном конвейере.

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

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

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

Проверьте правила обработки ошибок (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-заголовки, такие как код состояния и фраза причины. Политика AssignMessage идеально подходит для этого. Она позволяет управлять полезной нагрузкой сообщения, устанавливать другой код состояния HTTP, другую фразу причины HTTP и добавлять HTTP-заголовки.

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

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

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

• Возвращает сообщение в формате JSON.
• Устанавливает код состояния HTTP (911, который, очевидно, является несуществующим кодом состояния, просто чтобы проиллюстрировать имеющуюся у вас гибкость). Код состояния отображается в заголовке HTTP.
• Задает фразу причины HTTP (для замены стандартной фразы "Unauthorized" в случае ошибки отсутствия ключа 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> , чтобы обеспечить отображение общего сообщения об ошибке, если ни одно из ваших правил обработки ошибок (FaultRules) не выполняется.

Пример

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

Основные моменты:

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

• <Condition> - Edge оценивает условие и выполняет политику только в том случае, если условие истинно. Если несколько правил обработки ошибок (FaultRules) оцениваются как истинные, Edge выполняет первое из них. ( Важно : порядок оценки правил обработки ошибок, сверху вниз или снизу вверх, различается для TargetEndpoint и ProxyEndpoint, как описано в разделе «Несколько правил обработки ошибок и логика выполнения» .) Если вы не указываете условие, правило обработки ошибки автоматически становится истинным. Но это не является лучшей практикой. Каждое правило обработки ошибки должно иметь свое собственное условие.

• <DefaultFaultRule> - Если пользовательское правило обработки ошибок не выполняется, выполняется <DefaultFaultRule> , отправляя более общее пользовательское сообщение вместо загадочного сообщения, генерируемого Edge по умолчанию. <DefaultFaultRule> также может содержать <Condition> , но в большинстве случаев вы его не будете включать, поскольку хотите, чтобы оно выполнялось в любом случае в качестве крайней меры.

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

Множество правил обработки ошибок и логика выполнения.

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

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

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

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

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

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

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

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

Выполнение ProxyEntpoint

Оценка правил обработки ошибок ProxyEndpoint производится снизу вверх, поэтому начните чтение с последнего правила обработки ошибок в следующем примере и двигайтесь вверх. Правило обработки ошибок 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 производится сверху вниз, поэтому начните чтение с первого правила обработки ошибок в следующем примере и двигайтесь вниз. Правило обработки ошибок 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 в поток ответа. Это будет выглядеть примерно так:

  <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)
• Политика проверки API-ключа : 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> ). Правила обработки ошибок без внешнего условия автоматически оцениваются как истинные. «Внутренние» условия шага не используются для определения истинности или ложности правила обработки ошибок. Условия шага оцениваются только после того, как Edge выполнит содержащее их правило обработки ошибок. В правиле обработки ошибок обычно содержится несколько шагов с политиками назначения сообщения (или другими), каждый из которых имеет условие шага.

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

  Затем используйте внутренние условия Step, если вам требуется более точный контроль ошибок. Например, если вы применяете как индивидуальную квоту для разработчиков, так и глобальную квоту с помощью двух политик в потоке запросов, настройте ваше «внешнее» условие FaultRule так, чтобы оно срабатывало при ошибке QuotaViolation (которая возникает при превышении квоты в любом случае). Затем настройте условия Step для оценки переменных 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 Community .

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

  <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 можно выполнять любые политики, которые могут возвращать сообщения клиентскому приложению. Политика AssignMessage идеально подходит для этого. Также рассмотрите возможность записи сообщений в журнал с помощью политики MessageLogging, если вы хотите отслеживать ошибки.
• При использовании политик RaiseFault совместно с правилами FaultRules необходимо согласовывать данные ответа, отправляемые как политикой RaiseFault, так и правилом FaultRule. Например, если ваша политика RaiseFault сбрасывает код состояния HTTP, не следует использовать правило FaultRule для сброса этого кода состояния. В худшем случае клиентскому приложению будет возвращен код состояния по умолчанию.
• Выполнение <DefaultFaultRule> :
  • Если вы хотите, чтобы правило <DefaultFaultRule> всегда выполнялось, когда никакое другое правило FaultRule не выполняется, не добавляйте к нему <Condition> .
  • Если вы хотите, чтобы правило <DefaultFaultRule> всегда выполнялось, даже если уже выполнилось другое правило FaultRule, добавьте дочерний элемент <AlwaysEnforce>true</AlwaysEnforce> .

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

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

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

Создание правил обработки ошибок

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

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

Добавление политик в 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). Обратите внимание, как вы ссылаетесь на политику 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 имеет тип 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>

Include the <AlwaysEnforce> element in the <DefaultFaultRule> tag to execute the DefaultFaultRule for every error, even if another FaultRule has already been executed. The DefaultFaultRule is always the last FaultRule to execute:

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

One use of the DefaultFaultRule is to determine the type of error that occurs when you otherwise cannot determine it. For example, your API proxy is failing for an error that you cannot determine. Use the DefaultFaultRule to invoke the following AssignMessage policy. This policy writes the fault.name value to a header named DefaultFaultHeader in the response:

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

You can then view the header in the Edge trace tool or on the response to see what caused the error.

Adding message logging to the PostClientFlow

The PostClientFlow is the only flow that executes after the proxy enters the error state. Only the MessageLogging policy can be attached to this flow, which is executed after the response is sent back to the client. Although attaching the MessageLogging policy to this flow is technically not error handling, you can use it to log information in the event of an error. Because it is executed regardless of whether the proxy succeeded or failed, you can put Message Logging policies in the PostClientFlow and be guaranteed that they always execute.

Handling policy faults within the current flow

The examples shown so far all use a FaultRule on the ProxyEndpoint or TargetEndpoint to handle any policy errors as part of the error state. That is because the default value of the continueOnError element of a policy is false , meaning that when an error occurs in a policy, control is directed to the error state. Once in the error state, you cannot return control back to the normal pipeline and you typically return some form of error message to the calling app.

However, if you set the continueOnError element to true for a policy, control stays in the current flow and the next policy in the pipeline executes after the policy that caused the error. The advantage to handling the error in the current flow is that you might have a way to recover from the error to complete processing of the request.

Shown below is a VerifyAPIKey policy named verify-api-key with the continueOnError element set to true:

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

If the API key is missing or invalid, then the VerifyAPIKey policy sets the oauthV2.verify-api-key.failed variable to true , but processing continues in the current flow.

You then add VerifyAPIKey policy as a step in the PreFlow of the 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>

Notice how the next step in the PreFlow uses a condition to test for the existence of an error. If an error occurred in the VerifAPIKey policy, then the policy named FaultInFlow policy executes. Otherwise, the FaultInFlow policy is skipped. The FaultInFlow policy can do many things, such as logging the error, attempting to fix the error, or performing some other action.

Triggering an error by using the RaiseFault policy

You can use the RaiseFault policy at any time in a flow to trigger an error. When a RaiseFault policy executes, it terminates the current flow and transfers control to the error state.

One use of the RaiseFault policy is to test for a specific condition that another policy might not detect. In the example above, you added a <Condition> tag to a PreFlow <Step> tag that caused the policy FaultInFlow to execute if the condition is met. If FaultInFlow is a RaiseFault policy, then control transfers to the error state. Or, you might insert a RaiseFault policy in a flow to debug and test your FaultRules.

When a RaiseFault policy triggers an error, you can use the following FaultRule and condition to process it:

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

Note that the condition tests for a fault named RaiseFault . The RaiseFault policy always sets the value of fault.name to RaiseFault .

Custom handling of HTTP error codes from the target server

The examples shown in the previous sections apply to errors created by policies. However you can also create a custom response for transport-level errors, meaning HTTP errors returned from the target server. To control the response from an HTTP error, configure a TargetEndpoint to process HTTP response codes.

By default, Edge treats HTTP response codes in the 1xx-3xx range as 'success', and HTTP response codes in the range 4xx-5xx as 'failure'. That means any response from the backend service with an HTTP response code 4xx-5xx automatically invokes the error state, which then returns an error message directly to the requesting client.

You can create custom handlers for any HTTP response codes. For example, you might not want to treat all HTTP response codes in the range 4xx-5xx as 'failure' but only 5xx, or you might want to return custom error messages for HTTP response codes 400 and 500.

In the next example, you use the success.codes property to configure the TargetEndpoint to treat HTTP response codes 400 and 500 as a success, along with the default HTTP codes. By treating those codes as a success, the TargetEndpoint takes over the processing of the response message, instead of invoking the error state:

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

As you can see in this example, you can use wildcards to set the success.codes property to a range of values..

Setting the success.codes property overwrites the default values. Therefore, if you want to add HTTP code 400 to the list of default success codes, set this property as:

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

But, if you only want HTTP code 400 to be treated as a success code, set the property as:

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

You can now define custom handlers for HTTP response codes 400 and 500 to return a customized response message to the requesting app. The following TargetEndpoint uses the policy named ReturnError to handle HTTP 400 and 500 response codes:

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

This TargetEndpoint configuration causes the policy called ReturnError to handle the response whenever the TargetEndpoint encounters an HTTP response code of 400 or 500.

Fault taxonomy

API Services organizes faults into the following categories and subcategories.

An error is always accompanied by a text description of the reason for the failure. When the system raises a fault, a set of attributes are populated to assist in troubleshooting. A fault includes the following information:

• Причина
• User-defined custom attributes