Политика RaiseFault

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

Что

Генерирует пользовательское сообщение в ответ на ошибку. Используйте 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, который необходимо скопировать из объекта, указанного атрибутом source, в сообщение об ошибке.

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

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

См. раздел «Обработка ошибок».