Политика 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>

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

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

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

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

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

Никто.

Переменные неисправности

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

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

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

Схема

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

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

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