ServiceCallout 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

내용

서비스 콜아웃 정책을 사용하면 API 프록시 흐름에서 다른 서비스를 호출할 수 있습니다. 외부 서비스(예: 외부 RESTful 서비스 엔드포인트) 또는 내부 서비스(예: 동일한 조직 및 환경의 API 프록시)에 콜아웃을 만들 수 있습니다.

• 외부 사용 사례에서는 프록시 외부의 타사 API에 대한 콜아웃을 만듭니다. 타사 API의 응답은 파싱되어 API의 응답 메시지에 삽입되고 앱 최종 사용자를 위한 데이터를 보강하고 '매시업'합니다. 요청 흐름에서 Service Callout 정책을 사용하여 요청을 보낸 다음 응답의 정보를 API 프록시의 TargetEndpoint로 전달할 수도 있습니다.
• 또 다른 사용 사례에서는 호출을 보내는 동일한 조직 및 환경에 있는 프록시를 호출합니다. 예를 들어 하나 이상의 다른 프록시가 소비하는 개별 하위 수준 기능을 사용하는 프록시가 있는 경우 이 방법이 유용할 수 있습니다. 예를 들어 백엔드 데이터 저장소와 함께 생성/읽기/업데이트/삭제 작업을 노출하는 프록시는 클라이언트에 데이터를 노출하는 다른 여러 프록시의 대상 프록시가 될 수 있습니다.

이 정책은 HTTP 및 HTTPS를 통한 요청을 지원합니다.

샘플

<LocalTargetConnection>
    <APIProxy>data-manager</APIProxy>
    <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<HTTPTargetConnection>
    <URL>http://example.com/{request.myResourcePath}</URL>
</HTTPTargetConnection>

<ServiceCallout name="ServiceCallout-GeocodingRequest1">
    <DisplayName>Inline request message</DisplayName>
    <Request variable="authenticationRequest">
      <Set>
        <QueryParams>
          <QueryParam name="address">{request.queryparam.postalcode}</QueryParam>
          <QueryParam name="region">{request.queryparam.country}</QueryParam>
          <QueryParam name="sensor">false</QueryParam>
        </QueryParams>
      </Set>
    </Request>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout name="ServiceCallout-GeocodingRequest2">
    <Request clearPayload="false" variable="GeocodingRequest"/>
    <Response>GeocodingResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
      <URL>http://maps.googleapis.com/maps/api/geocode/json</URL>
    </HTTPTargetConnection>
</ServiceCallout>

<ServiceCallout async="false" continueOnError="false" enabled="true" name="service-callout">
    <DisplayName>service-callout</DisplayName>
    <Properties/>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    </Request>
    <Response>myResponse</Response>
    <HTTPTargetConnection>
        <LoadBalancer>
            <Algorithm>RoundRobin</Algorithm>
            <Server name="httpbin"/>
            <Server name="yahoo"/>
        </LoadBalancer>
        <Path>/get</Path>
    </HTTPTargetConnection>
</ServiceCallout>

Service Callout 정책 정보

API 프록시에서 Service Callout 정책을 사용할 수 있는 사례는 다양합니다. 예를 들어 외부 서비스에 호출을 수행하여 Geolocation 데이터, 고객 리뷰, 파트너의 소매 카탈로그 항목 등을 전달하기 위해 API 프록시를 구성할 수 있습니다.

콜아웃은 일반적으로 두 가지 정책 즉, Assign Message 및 Extract Variables와 함께 사용됩니다.

• 요청: Assign Message는 원격 서비스로 전송된 요청 메시지를 채웁니다.

• 응답: Extract Variables는 응답을 파싱하고 특정 콘텐츠를 추출합니다.

일반적인 Service Callout 정책 구성에는 다음이 포함됩니다.

1. Assign Message 정책: 요청 메시지를 만들고, HTTP 헤더 및 쿼리 매개변수를 채우고, HTTP 동사 설정 등을 수행합니다.
2. Service Callout 정책: Assign Message 정책으로 생성된 메시지를 참조하여 외부 호출의 대상 URL을 정의하고, 대상 서비스가 반환하는 응답 객체의 이름을 정의합니다.
   
   성능 향상을 위해 Apigee 커뮤니티 스레드(https://community.apigee.com/questions/34110/how-can-i-store-the-results-of-the-servicecallout.html)에 설명된 대로 Service Callout 응답을 캐시할 수도 있습니다.
3. Extract Variables 정책: 일반적으로 Service Callout으로 생성된 메시지를 파싱하는 JSONPath 또는 XPath 표현식을 정의합니다. 그런 다음 정책은 Service Callout 응답에서 파싱된 값이 포함된 변수를 설정합니다.

Assign Message 및 Extract Variables 정책과 함께 Service Callout 정책을 사용하는 전체 샘플 API 프록시는 정책 구성 사용을 참조하세요.

커스텀 오류 처리

요소 참조

이 정책에 구성할 수 있는 요소와 속성은 다음과 같습니다.

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">
    <DisplayName>Custom label used in UI</DisplayName>
    <Request clearPayload="true" variable="myRequest">
        <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
        <Remove>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
         </Remove>
         <Copy>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Copy>
        <Add>
            <Headers/>
            <QueryParams/>
            <FormParams/>
        </Add>
        <Set>
            <Headers/>
            <QueryParams/>
            <FormParams/>
            <Payload/>
            <ReasonPhrase/>
            <StatusCode/>
            <Path/>
            <Version/>
            <Verb/>
        </Set>
    </Request>
    <Response>calloutResponse</Response>
    <Timeout>30000</Timeout>
    <HTTPTargetConnection>
        <URL>http://example.com</URL>
        <LoadBalancer/>
        <SSLInfo/>
        <Properties/>
    </HTTPTargetConnection>
    <LocalTargetConnection>
        <APIProxy/>
        <ProxyEndpoint/>
        <Path/>
    </LocalTargetConnection>
</ServiceCallout>

<ServiceCallout> 속성

<ServiceCallout async="false" continueOnError="false" enabled="true" name="Service-Callout-1">

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<Request> 요소

API 프록시에서 다른 서비스로 전송되는 요청 메시지가 포함된 변수를 지정합니다. 이 변수는 흐름의 이전 정책에 의해 생성되거나 Service Callout 정책에서 인라인으로 만들 수 있습니다.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
    <Remove>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Remove>
    <Copy>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Copy>
    <Add>
        <Headers/>
        <QueryParams/>
        <FormParams/>
    </Add>
    <Set>
        <Headers/>
        <QueryParams/>
        <FormParams/>
        <Payload/>
        <ReasonPhrase/>
        <StatusCode/>
        <Path/>
        <Version/>
        <Verb/>
    </Set>
</Request>

<Remove>, <Copy>, <Add>, <Set> 태그의 구문은 Assign Message 정책과 동일합니다.

요청 메시지를 확인할 수 없거나 잘못된 요청 메시지 유형인 경우 정책이 오류를 반환합니다.

가장 간단한 예시에서는 API 프록시의 흐름 초반부에 채워진 요청 메시지가 포함된 변수를 전달합니다.

<Request clearPayload="true" variable="myRequest"/>

또는 Service Callout 정책 자체에서 외부 서비스로 전송된 요청 메시지를 채울 수 있습니다.

<Request>
  <Set>
    <Headers>
      <Header name="Accept">application/json</Header>
    </Headers>
    <Verb>POST</Verb>
    <Payload contentType="application/json">{"message":"my test message"}</Payload>
  </Set>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request>

특성

<Request>/<IgnoreUnresolvedVariables> 요소

true로 설정하면 정책은 요청에서 해결되지 않은 변수 오류를 무시합니다.

<Request clearPayload="true" variable="myRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
</Request> 

<Response> 요소

API 프록시 로직이 추가 처리를 위해 원격 호출의 응답이 필요한 경우 이 요소를 포함합니다.

이 요소가 있는 경우 외부 서비스에서 수신한 응답 메시지를 포함할 변수의 이름을 지정합니다. 대상의 응답은 정책에서 전체 응답을 성공적으로 읽는 경우에만 변수에 할당됩니다. 어떠한 이유로든 원격 호출이 실패하면 정책에서 오류를 반환합니다.

이 요소를 생략하면 API 프록시가 응답을 기다리지 않으며, API 프록시 흐름 실행은 모든 후속 흐름 단계를 통해 계속 진행됩니다. 또한 명확히 하자면 Response 요소가 없으면 대상의 응답을 후속 단계에 따라 처리할 수 없으며, 프록시 흐름에서 원격 호출의 실패를 감지할 방법이 없습니다. ServiceCallout을 사용할 때 Response 요소를 생략하는 것의 일반적인 용도는 외부 시스템에 로깅하기 위함입니다.

 <Response>calloutResponse</Response> 

<Timeout> 요소

Service Callout 정책이 대상의 응답을 대기하는 시간(밀리초)입니다. 런타임 시 이 값을 동적으로 설정할 수 없습니다. Service Callout이 제한 시간에 도달하면 오류 처리에 설명된 대로 HTTP 500이 반환되고, 정책이 실패하며, API 프록시는 오류 상태가 됩니다.

<Timeout>30000</Timeout>

<HTTPTargetConnection> 요소

URL, TLS/SSL, HTTP 속성과 같은 전송 세부정보를 제공합니다. <TargetEndpoint> 구성 참조를 확인하세요.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <LoadBalancer/>
    <SSLInfo/>
    <Properties/>
</HTTPTargetConnection>

<HTTPTargetConnection>/<URL> 요소

호출되는 서비스의 URL입니다.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
</HTTPTargetConnection>

변수를 통해 URL의 일부를 동적으로 제공할 수 있습니다. 그러나 아래의 URL http://의 프로토콜 부분은 변수로 지정될 수 없습니다. 다음 예시에서는 변수를 사용하여 쿼리 매개변수의 값을 지정합니다.

<URL>http://example.com/forecastrss?w=${request.header.woeid}</URL>

또는 변수를 사용하여 URL 경로의 일부를 설정합니다.

<URL>http://example.com/{request.resourcePath}?w=${request.header.woeid}</URL>

변수를 사용하여 URL의 도메인과 포트를 지정하려면 도메인 및 포트에만 첫 번째 변수를 사용하고 URL의 다른 부분에 두 번째 변수를 사용합니다.

<URL>http://{request.dom_port}/{request.resourcePath}</URL>

<HTTPTargetConnection>/<SSLInfo> 요소

백엔드 서비스에 대한 TLS/SSL 구성입니다. TLS/SSL 구성에 대한 도움말은 API 프록시 구성 참조의 에지에서 백엔드로 TLS 구성 (클라우드 및 프라이빗 클라우드) 및 'TLS/SSL TargetEndpoint 구성'을 참조하세요.

<HTTPTargetConnection>
    <URL>https://example.com</URL>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://mykeystoreref</KeyStore>  ## Use of a reference is recommended
        <KeyAlias>myKey</KeyAlias>
        <TrustStore>myTruststore</TrustStore>
        <Ciphers/>
        <Protocols/>
    </SSLInfo>
</HTTPTargetConnection>

백엔드 서비스로의 HTTP 전송 속성입니다. 자세한 내용은 엔드포인트 속성 참조를 확인하세요.

<HTTPTargetConnection>
    <URL>http://example.com</URL>
    <Properties>
        <Property name="allow.http10">true</Property>
        <Property name="request.retain.headers">
          User-Agent,Referer,Accept-Language
        </Property>
    </Properties>
</HTTPTargetConnection>

<HTTPTargetConnection>/<LoadBalancer> 요소

하나 이상의 대상 서버를 호출하고 서버에서 부하 분산을 수행합니다. 샘플 섹션에서 호출 대상 서버 샘플을 참조하세요. 백엔드 서버 간 부하 분산도 참조하세요. 또한 Service Callout 정책과 Route Rule(라우팅 규칙)을 사용하여 대상 서버를 호출하는 방법은 이 커뮤니티 게시물을 참조하세요.

<HTTPTargetConnection> <LoadBalancer> <Algorithm>RoundRobin</Algorithm> <Server name="httpbin"/> <Server name="yahoo"/> </LoadBalancer> <Path>/get</Path> </HTTPTargetConnection>

<LocalTargetConnection> 요소

로컬 프록시(즉, 동일한 조직 및 환경의 프록시)를 서비스 콜아웃의 대상으로 지정합니다.

타겟을 추가로 지정하려면 <APIProxy> 또는 <ProxyEndpoint> 요소를 사용하거나 <Path> 요소를 사용합니다.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
   <Path/>
</LocalTargetConnection>

<LocalTargetConnection>/<APIProxy> 요소

로컬 호출의 타겟인 API 프록시의 이름입니다. 프록시는 호출을 수행하는 프록시와 동일한 조직 및 환경에 있어야 합니다.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<APIProxy> 요소와 함께 <ProxyEndpoint> 요소를 포함하여 호출의 대상이어야 하는 프록시 엔드포인트의 이름을 지정합니다.

<LocalTargetConnection>
   <APIProxy/>
   <ProxyEndpoint/>
</LocalTargetConnection> 

<LocalTargetConnection>/<ProxyEndpoint> 요소

호출 대상이어야 하는 프록시 엔드포인트의 이름입니다. 이는 <APIProxy> 요소로 지정된 API 프록시의 프록시 엔드포인트입니다.

<LocalTargetConnection>
   <APIProxy>data-manager</APIProxy>
   <ProxyEndpoint>default</ProxyEndpoint>
</LocalTargetConnection>

<LocalTargetConnection>/<Path> 요소

대상이 되는 엔드포인트의 경로입니다. 엔드포인트는 호출을 수행하는 프록시와 동일한 조직 및 환경의 프록시를 참조해야 합니다.

프록시 이름을 모르거나 의존할 수 없는 경우 <APIProxy>/<ProxyEndpoint> 쌍 대신 이를 사용하세요. 경로가 안정적인 대상일 수 있습니다.

<LocalTargetConnection>
   <Path>/data-manager</Path>
</LocalTargetConnection>

스키마

흐름 변수

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

Service Callout에는 자체 요청과 응답이 있으며 변수를 통해 해당 데이터에 액세스할 수 있습니다. 기본 메시지는 request.* 및 response.* 변수 프리픽스를 사용하므로 myrequest.* 및 calloutResponse.* 프리픽스(Service Callout 구성의 기본값)를 사용하여 Service Callout 관련 메시지 데이터를 가져옵니다. 다음 표의 첫 번째 예시는 Service Callout에서 HTTP 헤더를 가져오는 방법을 보여줍니다.

오류

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

런타임 오류

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

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 변수

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

오류 응답 예시

{  
   "fault":{  
      "detail":{  
         "errorcode":"steps.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

오류 규칙 예시

<faultrule name="VariableOfNonMsgType"></faultrule><FaultRule name="RequestVariableNotMessageType">
    <Step>
        <Name>AM-RequestVariableNotMessageType</Name>
    </Step>
    <Condition>(fault.name = "RequestVariableNotMessageType")</Condition>
</FaultRule>

관련 주제

• 메시지 생성 또는 수정: Assign Message 정책
• 변수 추출: Extract Variables 정책
• 변수: 변수 참조
• TLS/SSL 구성
  • Edge에서 백엔드로 TLS 구성 (클라우드 및 프라이빗 클라우드)
  • API 프록시 구성 참조의 'TLS/SSL TargetEndpoint 구성'
• HTTP 전송 속성: 엔드포인트 속성 참조
• 서비스 콜아웃의 대안: 자바스크립트로 작성된 HTTPClient, JavaScript 객체 모델 참고