Правило RaiseFault

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

Что

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

Общую информацию об обработке ошибок можно найти в разделе Обработка ошибок.

Примеры

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
     <ReasonPhrase>The resource requested was not found</ReasonPhrase>
   </Set>
 </FaultResponse>
</RaiseFault>

<RaiseFault name="ExceptionHandler">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <Payload contentType="text/xml">
       <root>Please contact support@company.com</root>
     </Payload>
     <StatusCode>{response.status.code}</StatusCode>
     <ReasonPhrase>Server error</ReasonPhrase>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

Правило RaiseFault

Apigee Edge позволяет выполнять обработку исключений с помощью правила типа RaiseFault. Правило RaiseFault, похожее на AssignMessage, позволяет создавать собственные ответы об ошибках.

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

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

Элемент RaiseFault можно использовать в ProxyEndpoint или TargetEndpoint. Обычно к правилу RaiseFault прикрепляется условие. После выполнения RaiseFault Apigee выполнит стандартную обработку ошибок, оценивая FaultRules, или, если правила обработки ошибок не определены, завершит обработку запроса.

Сведения об элементах

В справочнике по элементам описаны элементы и атрибуты правила RaiseFault.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">
    <DisplayName>RaiseFault 1</DisplayName>
    <FaultResponse>
        <AssignVariable>
          <Name/>
          <Value/>
        </AssignVariable>
        <Add>
            <Headers/>
        </Add>
        <Copy source="request">
            <Headers/>
            <StatusCode/>
            <ReasonPhrase/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

Атрибуты элемента <RaiseFault>

<RaiseFault async="false" continueOnError="false" enabled="true" name="Raise-Fault-1">

В следующей таблице описаны атрибуты, общие для всех родительских элементов политики:

Элемент <DisplayName>

Используйте в дополнение к атрибуту name , чтобы пометить политику в редакторе прокси-сервера пользовательского интерфейса управления другим именем на естественном языке.

<DisplayName>Policy Display Name</DisplayName>

Элемент <IgnoreUnresolvedVariables>

(Необязательно) Игнорирует все неразрешенные ошибки переменных в потоке. Допустимые значения: true/false. true по умолчанию.

Элемент <FaultResponse>

Необязательное поле, в котором определяется сообщение ответа, возвращаемое клиенту, отправившему запрос. В FaultResponse используются те же настройки, что и в правиле AssignMessage (недоступно в Apigee Edge для частного облака).

Элемент <FaultResponse><AssignVariable>

Назначает значение переменной целевого потока. Если переменной потока не существует, AssignVariable создает ее.

Например, чтобы задать переменную myFaultVar в правиле RaiseFault, используйте следующий код:

<FaultResponse>
  <AssignVariable>
    <Name>myFaultVar</Name>
    <Value>42</Value>
  </AssignVariable>
  ...
</FaultResponse>

Затем вы можете ссылаться на эту переменную в шаблонах сообщений в правиле RaiseFault. Кроме того, правило, прикрепленное к FaultRule, может получить доступ к переменной. Например, в следующем правиле AssignMessage используется переменная, заданная в RaiseFault, чтобы задать заголовок в ответе об ошибке:

<AssignMessage enabled="true" name="Assign-Message-1">
  <Add>
    <Headers>
      <Header name="newvar">{myFaultVar}</Header>
    </Headers>
  </Add>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

<AssignVariable> в правиле RaiseFault использует тот же синтаксис, что и элемент <AssignVariable> в правиле AssignMessage. Обратите внимание, что эта функция в настоящее время недоступна в Apigee Edge для частного облака.

Элемент <FaultResponse><Add>/<Headers>

Добавляет HTTP-заголовки в сообщение об ошибке. Обратите внимание, что пустой заголовок <Add><Headers/></Add> не добавляет никакого заголовка. В этом примере значение переменной потока request.user.agent копируется в заголовок.

<Add>
    <Headers>
        <Header name="user-agent">{request.user.agent}</Header>
    </Headers>
</Add>

Элемент <FaultResponse><Copy>

Копирует информацию из сообщения, указанного в атрибуте source, в сообщение об ошибке.

    <Copy source="request">
        <Headers/>
        <StatusCode/>
        <ReasonPhrase/>
    </Copy>

Атрибуты

 <Copy source="response">

Элемент <FaultResponse><Copy>/<Headers>

Копирует указанный заголовок HTTP из источника в сообщение об ошибке. Чтобы скопировать все заголовки, укажите <Copy><Headers/></Copy>..

<Copy source='request'>
    <Headers>      
        <Header name="headerName"/>
    </Headers> 
</Copy>

Если есть несколько заголовков с одинаковым названием, используйте следующий синтаксис:

<Copy source='request'>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Copy>

В этом примере копируются элементы "h1", "h2" и второе значение элемента "h3". Если у заголовка h3 только одно значение, оно не копируется.

Элемент <FaultResponse><Copy>/<StatusCode>

Код статуса HTTP, который нужно скопировать из объекта, указанного в атрибуте источника, в сообщение об ошибке.

<Copy source='response'>
    <StatusCode>404</StatusCode>      
</Copy>

Элемент <FaultResponse><Copy>/<ReasonPhrase>

Описание причины, которое нужно скопировать из объекта, указанного в атрибуте источника, в сообщение об ошибке.

<Copy source='response'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>     
</Copy>

Элемент <FaultResponse><Remove>/<Headers>

Удаляет из сообщения об ошибке указанные HTTP-заголовки. Чтобы удалить все заголовки, укажите <Remove><Headers/></Remove>. В этом примере из письма удаляется заголовок user-agent.

<Remove>     
    <Headers>      
        <Header name="user-agent"/>     
    </Headers> 
</Remove>

Если есть несколько заголовков с одинаковым названием, используйте следующий синтаксис:

<Remove>
    <Headers>
      <Header name="h1"/>
      <Header name="h2"/>
      <Header name="h3.2"/>
    </Headers>
</Remove>

В этом примере удаляются элементы h1, h2 и второе значение h3. Если у элемента h3 только одно значение, оно не удаляется.

Элемент <FaultResponse><Set>

Задает информацию в сообщении об ошибке.

    <Set>
        <Headers/>
        <Payload> </Payload>
        <StatusCode/>
        <ReasonPhrase/>
    </Set>

Элемент <FaultResponse>/<Set>/<Headers>

Устанавливает или перезаписывает заголовки HTTP в сообщении об ошибке. Обратите внимание, что пустой заголовок <Set><Headers/></Set> не задает никакого заголовка. В этом примере заголовок user-agent задается для переменной сообщения, указанной в элементе <AssignTo>.

<Set>
    <Headers>
        <Header name="user-agent">{request.header.user-agent}</Header>     
    </Headers>
</Set>

Элемент <FaultResponse>/<Set>/<Payload>

Задает полезную нагрузку сообщения об ошибке.

<Set>
    <Payload contentType="text/plain">test1234</Payload>
</Set>

Задайте полезную нагрузку JSON:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"bar"}
    </Payload>
</Set>

В полезной нагрузке JSON можно вставлять переменные, используя атрибуты variablePrefix и variableSuffix с символами-разделителями, как показано в следующем примере.

<Set>
    <Payload contentType="application/json" variablePrefix="@" variableSuffix="#">
        {"name":"foo", "type":"@variable_name#"}
    </Payload>
</Set>

или, начиная с облачной версии 16.08.17, фигурные скобки для вставки переменных:

<Set>
    <Payload contentType="application/json">
        {"name":"foo", "type":"{variable_name}"}
    </Payload>
</Set>

Как задать смешанную полезную нагрузку в XML:

<Set>
    <Payload contentType="text/xml">
        <root>
          <e1>sunday</e1>
          <e2>funday</e2>
          <e3>{var1}</e3>
    </Payload>
</Set>

Атрибуты

 
<Payload contentType="content_type" variablePrefix="char" variableSuffix="char">

Элемент <FaultResponse>/<Set>/<StatusCode>

Задает код статуса ответа.

<Set source='request'>
    <StatusCode>404</StatusCode>
</Set>

Элемент <FaultResponse>/<Set>/<ReasonPhrase>

Задает фразу причины ответа.

<Set source='request'>     
    <ReasonPhrase>The resource requested was not found.</ReasonPhrase>
</Set>

Элемент <ShortFaultReason>

Указывает, что в ответе должна быть показана краткая причина ошибки:

<ShortFaultReason>true|false</ShortFaultReason>

По умолчанию в ответе правила указывается следующая причина ошибки:

"fault":{"faultstring":"Raising fault. Fault name : Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Чтобы сделать сообщение более читабельным, можно задать для элемента <ShortFaultReason> значение true, чтобы сократить faultstring до названия правила:

"fault":{"faultstring":"Raise-Fault-1","detail":{"errorcode":"errorCode"}}}

Допустимые значения: true/false(по умолчанию).

Переменные процесса

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

Пример использования RaiseFault

В приведенном ниже примере условие используется для того, чтобы обеспечить наличие в входящем запросе объекта queryparam с именем zipcode. Если queryparam отсутствует, поток вызовет ошибку с помощью RaiseFault:

<Flow name="flow-1">
  <Request>
    <Step>
        <Name>RF-Error-MissingQueryParam</Name>
        <Condition>request.queryparam.zipcode = null</Condition>
    </Step>
   ...
   </Request>
   ...
   <Condition>(proxy.pathsuffix MatchesPath "/locations") and (request.verb = "GET")</Condition>
</Flow>

<RaiseFault name='RF-Error-MissingQueryParam'>
  <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
  <FaultResponse>
    <Set>
      <Payload contentType='application/json'>{
  "error" : {
    "code" : 400.02,
    "message" : "invalid request. Pass a zipcode queryparam."
  }
}
</Payload>
      <StatusCode>400</StatusCode>
      <ReasonPhrase>Bad Request</ReasonPhrase>
    </Set>
  </FaultResponse>
</RaiseFault>

Справочник по ошибкам

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые задаются Edge, когда это правило вызывает ошибку. Эта информация важна, если вы разрабатываете правила обработки ошибок. Подробнее о том, что нужно знать об ошибках в правилах и как устранять неполадки…

Ошибки времени выполнения

Эти ошибки могут возникать при выполнении правил.

Ошибки развертывания

Нет.

Переменные ошибок

Эти переменные задаются при возникновении ошибки выполнения. Подробнее о нарушениях правил…

Пример ответа об ошибке

{
   "fault":{
      "detail":{
         "errorcode":"steps.raisefault.RaiseFault"
      },
      "faultstring":"Raising fault. Fault name: [name]"
   }
}

Схема

Каждый тип правил определяется схемой XML (.xsd). Схемы правил доступны на GitHub.

Статьи по теме

Подробнее об обработке ошибок…