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

Вы можете использовать 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>

Ссылка на ошибку

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Deployment errors

None.

Fault variables

These variables are set when a runtime error occurs. For more information, see What you need to know about policy errors.

Example error response

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

Схема

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

Связанные темы

См. Обработка ошибок.