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

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

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

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

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

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

Видео

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

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

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

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

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

• Политика выдает ошибку. Например, если вызов API отправляет ключ с истекшим сроком действия, политика VerifyAPIKey автоматически выдает ошибку; или если количество вызовов API превышает определенный предел, политика квот или политика 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 переходит в состояние ошибки, он не может вернуть обработку обратно в нормальный конвейер потока.

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

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

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

Это позволяет создать политику, не привязывая ее к потоку в прокси-сервере 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> чтобы предоставить собственное общее сообщение об ошибке, если ни один из ваших 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. Это важно. Подробнее о размещении FaultRules в ProxyEndpoint и TargetEndpoint позже.
• <Name> — имя выполняемой политики. Имя берется из атрибута name политики в родительском элементе, как показано в примере политики ранее.

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

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

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

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

В разделе «Пример простой обработки ошибок» мы использовали простой пример одного правила FaultRule и условия. В реальном проекте API со всеми возможными ошибками у вас, скорее всего, будет несколько FaultRules и 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 начинается с верхнего <FaultRule> в XML-файле конфигурации и движется вниз, оценивая <Condition> каждого <FaultRule> («внешнее» условие, а не «внутреннее» условие <Step> ).
2. Выполняет первое FaultRule, условие которого истинно. Если FaultRule не имеет условия, по умолчанию оно истинно.
   • При выполнении FaultRule все шаги внутри FaultRule оцениваются по порядку, сверху вниз в конфигурации XML. Шаги без условий выполняются автоматически (политики выполняются), а шаги с <Condition> , имеющим значение «истина», выполняются (условия, имеющие значение «ложь», не выполняются).

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

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

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

Выполнение ProxyEndpoint

Оценка ProxyEndpoint FaultRules осуществляется снизу вверх, поэтому начните читать с последнего 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

Оценка TargetEndpoint FaultRules выполняется сверху вниз, поэтому начните читать с первого 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 оценивается как true, оно не сработает, если прокси-сервер не находится в состоянии ошибки.

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

<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 обычно имеется несколько шагов с политиками назначения сообщений (или другими), каждый из которых имеет условие шага.

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

  Затем используйте внутренние условия 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 .

• Чтобы обрабатывать ошибки при использовании одной политики одного типа, рассмотрите одно правило сбоя, которое выполняется в случае сбоя этой одной политики, и включите несколько шагов, которые соответствуют каждой возможной ошибке. Это обеспечивает эффективность вашего XML за счет использования одного правила FaultRule, а не нескольких правил 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> :
  • Если вы хотите, чтобы <DefaultFaultRule> всегда выполнялся, когда не выполняется другой FaultRule, не включайте в него <Condition> .
  • Если вы хотите, чтобы <DefaultFaultRule> всегда выполнялся даже при выполнении другого FaultRule, добавьте дочерний элемент <AlwaysEnforce>true</AlwaysEnforce> .

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

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

https://community.apigee.com/articles/23724/an-error-handling-pattern-for-apigee-proxies.html

Создание правил сбоя

Чтобы добавить FaultRule, вам необходимо отредактировать конфигурацию XML ProxyEndpoint или TargetEndpoint. Вы можете использовать пользовательский интерфейс Edge, чтобы внести это изменение на панели «Код» представления «Разработка» для прокси-сервера API или отредактировать XML-файл, который определяет ProxyEndpoint или TargetEndpoint.

Если вы создаете FaultRule в пользовательском интерфейсе управления, сначала создайте политики, которые хотите выполнять, а затем добавьте их в конфигурацию 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. Обратите внимание, как вы ссылаетесь на политику AssignMessage по имени в FaultRule:

<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 всегда выполняется последним FaultRule:

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

Одним из использования DefaultFaultrule является определение типа ошибки, которая возникает, когда вы не можете ее определить. Например, ваш прокси API не удается для ошибки, которую вы не можете определить. Используйте DefaultFaultrule, чтобы вызвать следующую политику назначения. Эта политика записывает 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>

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

Добавление журнала сообщений в PostClientFlow

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

Обработка ошибок политики в рамках текущего потока

Примеры, показанные до настоящего времени, используют Faultrule на ProxyendPoint или TargetendPoint для обработки любых ошибок политики как часть состояния ошибки. Это связано с тем, что значение по умолчанию элемента continueOnError политики является false , а это означает, что, когда в политике возникает ошибка, управление направлено на состояние ошибки. Оказавшись в состоянии ошибки, вы не можете вернуть управление обратно в обычный трубопровод, и вы обычно возвращаете какую -то форму сообщения об ошибке в приложение Calling.

Однако, если вы установите элемент 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 в качестве шага в предварительном положении 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>  

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

Запуск ошибки с помощью политики Mastfault

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

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

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

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

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

Пользовательская обработка кодов ошибок HTTP с целевого сервера

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

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

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

Но, если вы хотите, чтобы HTTP Code 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 400 или 500.

Ошибка таксономии

API Services организует недостатки в следующие категории и подкатегории.

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

• Причина
• Пользовательские пользовательские атрибуты