RaiseFault 정책

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

대상

오류 조건에 응하여 커스텀 메시지를 생성합니다. 특정 조건이 발생할 때 요청 측 앱에 반환되는 오류 응답을 정의하려면 RaiseFault를 사용합니다.

이 정책은 표준 정책이며 모든 환경 유형에 배포할 수 있습니다. 정책 유형과 각 환경 유형에서의 가용성에 대한 자세한 내용은 정책 유형을 참조하세요.

오류 처리에 대한 일반적인 정보는 오류 처리를 참조하세요.

샘플

FaultResponse 반환

RaiseFault는 일반적으로 요청 앱에 대한 커스텀 오류 응답을 반환하는 데 사용됩니다. 예를 들어 이 정책은 페이로드가 없는 404 상태 코드를 반환합니다.

<RaiseFault name="404">
 <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
 <FaultResponse>
   <Set>
     <StatusCode>404</StatusCode>
   </Set>
 </FaultResponse>
</RaiseFault>

FaultResponse 페이로드 반환

더 복잡한 예시를 들면 HTTP 헤더 및 HTTP 상태 코드와 함께 커스텀 오류 응답 페이로드 반환이 있습니다. 다음 예시에서 오류 응답은 Apigee가 백엔드 서비스에서 수신한 HTTP 상태 코드가 포함된 XML 메시지와 발생한 오류 유형이 포함된 헤더로 채워집니다.

<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>
   </Set>
   <Add>
     <Headers>
       <Header name="FaultHeader">{fault.name}</Header>
     </Headers>
   </Add>
 </FaultResponse>
</RaiseFault>

FaultResponse 메시지를 동적으로 채울 수 있는 모든 변수의 목록은 변수 참조를 참조하세요.

서비스 콜아웃 오류 처리

RaiseFault 정책 정보

Apigee를 사용하면 RaiseFault 유형의 정책을 사용하여 커스텀 예외 처리를 수행할 수 있습니다. AssignMessage 정책과 비슷한 RaiseFault 정책을 사용하면 오류 조건에 따라 커스텀 오류 응답을 생성할 수 있습니다.

특정 오류 조건이 발생할 때 요청 측 앱에 반환되는 오류 응답을 정의하려면 RaiseFault 정책을 사용합니다. 오류 응답은 HTTP 헤더, 쿼리 매개변수, 메시지 페이로드로 구성될 수 있습니다. 일반 오류 메시지 또는 HTTP 응답 코드보다 커스텀 오류 응답이 앱 개발자 및 앱 최종 사용자에게 더 유용할 수 있습니다.

RaiseFault 정책은 실행되면 현재 흐름에서 오류 흐름으로 제어를 전송하고, 그런 다음 지정된 클라이언트 앱에 지정된 오류 응답을 반환합니다. 메시지 흐름을 오류 흐름으로 전환하면 추가 정책 처리가 발생하지 않습니다. 나머지 모든 처리 단계는 우회되고 오류 응답이 요청 측 앱에 직접 반환됩니다.

ProxyEndpoint 또는 TargetEndpoint에서 RaiseFault를 사용할 수 있습니다. 일반적으로 조건은 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/>
        </Copy>
        <Remove>
            <Headers/>
        </Remove>
        <Set>
            <Headers/>
            <Payload/>
            <StatusCode/>
        </Set>
    </FaultResponse>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>

<RaiseFault> 속성

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

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

속성	설명	기본값	Presence
`name`	정책의 내부 이름입니다. `name` 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 `<DisplayName>` 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.	해당 사항 없음	필수
`continueOnError`	정책이 실패할 경우 오류가 반환되도록 하려면 `false`로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 `true`로 설정합니다. 참조: 오류 규칙은 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 오류 처리	false	선택사항
`enabled`	정책을 시행하려면 `true`로 설정합니다. 정책을 중지하려면 `false`로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	true	선택사항
`async`	이 속성은 지원이 중단되었습니다.	false	지원 중단됨

<DisplayName> 요소

name 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

<DisplayName>Policy Display Name</DisplayName>

기본값

기본값	해당 사항 없음 이 요소를 생략하면 정책 `name` 속성 값이 사용됩니다.
Presence	선택사항
유형	문자열

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.

Presence 선택사항

유형 문자열

<IgnoreUnresolvedVariables> 요소

(선택사항) 흐름에서 확인되지 않은 변수 오류를 무시합니다. 유효한 값: true/false 기본값은 true입니다.

<FaultResponse> 요소

(선택사항) 요청 클라이언트로 반환되는 응답 메시지를 정의합니다. FaultResponse는 AssignMessage 정책과 동일한 설정을 사용합니다.

<FaultResponse><AssignVariable> 요소

대상 흐름 변수에 값을 할당합니다. 흐름 변수가 없으면 AssignVariable이 변수를 만듭니다.

예를 들어 다음 코드를 사용하여 RaiseFault 정책에서 myFaultVar이라는 변수를 설정합니다.

<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>
</AssignMessage>

RaiseFault 정책의 <AssignVariable>은 AssignMessage 정책의 <AssignVariable> 요소와 동일한 문법을 사용합니다.

<FaultResponse><Add>/<Headers> 요소

HTTP 헤더를 오류 메시지에 추가합니다. 빈 헤더 <Add><Headers/></Add>는 헤더를 추가하지 않습니다. 이 예시에서는 request.user.agent 흐름 변수의 값을 헤더에 복사합니다.

<Header> 요소는 메시지 템플릿이라는 동적 문자열 대체 기능을 지원합니다.

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

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열

<FaultResponse><Copy> 요소

source 속성으로 지정된 메시지에서 부터 오류 메시지로 정보를 복사합니다.

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

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열

속성

 <Copy source="response">

속성	설명	Presence	유형
source	사본의 소스 객체를 지정합니다. 소스를 지정하지 않으면 단순 메시지로 취급됩니다. 예를 들어 정책이 요청 흐름에 있는 경우 소스가 기본적으로 요청 객체로 지정됩니다. 정책이 응답 흐름에 있으면 기본적으로 응답 객체로 지정됩니다. 소스를 생략하면 흐름 변수에 대한 절대 참조를 복사본의 소스로 사용할 수 있습니다. 예를 들어 값을 {request.header.user-agent}로 지정합니다. 소스 변수를 확인할 수 없거나 메시지 외의 유형으로 확인되면 <Copy>가 응답하지 않습니다.	선택사항	문자열

속성

설명

Presence

유형

source

사본의 소스 객체를 지정합니다.

소스를 지정하지 않으면 단순 메시지로 취급됩니다. 예를 들어 정책이 요청 흐름에 있는 경우 소스가 기본적으로 요청 객체로 지정됩니다. 정책이 응답 흐름에 있으면 기본적으로 응답 객체로 지정됩니다. 소스를 생략하면 흐름 변수에 대한 절대 참조를 복사본의 소스로 사용할 수 있습니다. 예를 들어 값을 {request.header.user-agent}로 지정합니다.
소스 변수를 확인할 수 없거나 메시지 외의 유형으로 확인되면 <Copy>가 응답하지 않습니다.

선택사항

문자열

<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'에 값이 하나만 있는 경우 복사되지 않습니다.

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열

<FaultResponse><Copy>/<StatusCode> 요소

소스 속성에서 지정한 객체에서 오류 메시지로 복사하는 HTTP 상태 코드입니다.

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

기본값:	false
Presence:	선택사항
유형:	문자열

<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'에 값이 하나만 있으면 삭제되지 않습니다.

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열

<FaultResponse><Set> 요소

오류 메시지에 정보를 설정합니다.

<Set>의 하위 요소는 메시지 템플릿이라는 동적 문자열 대체 기능을 지원합니다.

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

기본값:	해당 사항 없음
Presence:	선택사항
유형:	해당 사항 없음

<FaultResponse>/<Set>/<Headers> 요소

오류 메시지에서 HTTP 헤더를 설정하거나 덮어씁니다. 빈 헤더 <Set><Headers/></Set>는 헤더를 설정하지 않습니다. 이 예시에서는 user-agent 헤더를 <AssignTo> 요소로 지정된 메시지 변수에 설정합니다.

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

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열

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

기본값:
Presence:	선택사항
유형:	문자열

속성

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

속성	설명	Presence	유형
contentType	contentType을 지정하면 값이 `Content-Type` 헤더에 할당됩니다.	선택사항	문자열
variablePrefix	JSON 페이로드가 기본 '{' 문자를 사용할 수 없으므로 필요한 경우 흐름 변수의 선행 구분 기호를 지정합니다.	선택사항	char
variableSuffix	JSON 페이로드가 기본 '}' 문자를 사용할 수 없으므로 필요한 경우 흐름 변수의 후행 구분 기호를 지정합니다.	선택사항	char

<FaultResponse>/<Set>/<StatusCode> 요소

응답의 상태 코드를 설정합니다.

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

기본값:	false
Presence:	선택사항
유형:	불리언

<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(기본값).

기본값:	false
Presence:	선택사항
유형:	불리언

흐름 변수

흐름 변수를 사용하면 HTTP 헤더, 메시지 콘텐츠 또는 흐름 컨텍스트를 기반으로 런타임 시 정책 및 흐름의 동적 동작을 사용 설정할 수 있습니다. RaiseFault 정책이 실행되면 다음과 같은 사전 정의된 흐름 변수를 사용할 수 있습니다. 흐름 변수에 대한 자세한 내용은 변수 참조를 확인하세요.

변수	유형	권한	설명
fault.name	문자열	읽기 전용	RaiseFault 정책이 실행되면 이 변수가 항상 문자열 `RaiseFault`로 설정됩니다.
fault.type	문자열	읽기 전용	오류의 유형을 반환하고 사용할 수 없는 경우 빈 문자열을 반환합니다.
fault.category	문자열	읽기 전용	오류 카테고리를 반환하고 사용할 수 없는 경우 빈 문자열을 반환합니다.

RaiseFault 사용 예시

다음 예시에서는 조건을 사용하여 인바운드 요청에 zipcode라는 queryparam의 존재를 적용합니다. 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의 예시를 보여줍니다.

<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>
    </Set>
  </FaultResponse>
</RaiseFault>

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드	HTTP 상태	원인
`steps.raisefault.RaiseFault`	`500`	오류 문자열을 참조하세요.

배포 오류

없음.

오류 변수

이러한 변수는 런타임 오류가 발생하면 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수	장소	예
`fault.name="fault_name"`	`fault_name`은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다.	`fault.name = "RaiseFault"`
`raisefault.policy_name.failed`	`policy_name`은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	`raisefault.RF-ThrowError.failed = true`

오류 응답 예시

참고: 오류 처리에서 권장사항은 오류 응답의 errorcode 부분을 트래핑하는 것입니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.

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

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.

RaiseFault 정책

대상

샘플

FaultResponse 반환

FaultResponse 페이로드 반환

서비스 콜아웃 오류 처리

RaiseFault 정책 정보

요소 참조

<RaiseFault> 속성

<DisplayName> 요소

<IgnoreUnresolvedVariables> 요소

<FaultResponse> 요소

<FaultResponse><AssignVariable> 요소

<FaultResponse><Add>/<Headers> 요소

<FaultResponse><Copy> 요소

속성

<FaultResponse><Copy>/<Headers> 요소

<FaultResponse><Copy>/<StatusCode> 요소

<FaultResponse><Remove>/<Headers> 요소

<FaultResponse><Set> 요소

<FaultResponse>/<Set>/<Headers> 요소

<FaultResponse>/<Set>/<Payload> 요소

속성

<FaultResponse>/<Set>/<StatusCode> 요소

<ShortFaultReason> 요소

흐름 변수

RaiseFault 사용 예시

오류 참조

런타임 오류

배포 오류

오류 변수

오류 응답 예시

스키마

관련 주제