ServiceCallout 정책

<ph type="x-smartling-placeholder"></ph> 현재 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 구성에 관한 도움말은 다음을 참고하세요. TLS 구성 에지에서 백엔드 (클라우드 및 프라이빗 클라우드)로 전송 및 'TLS/SSL TargetEndpoint 구성' 자세한 내용은 API 프록시 구성 참조를 참고하세요.

<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 헤더를 가져오는 방법을 보여줍니다.

오류

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

These errors can occur when you deploy a proxy containing this policy.

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.servicecallout.RequestVariableNotMessageType"
      },
      "faultstring":"ServiceCallout[ServiceCalloutGetMockResponse]: 
            request variable data_str value is not of type Message"
   }
}

Example fault rule

<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 구성
  • 구성 에지에서 백엔드로의 TLS (클라우드 및 프라이빗 클라우드)
  • API 프록시 구성 참조의 'TLS/SSL TargetEndpoint 구성'
• HTTP 전송 속성: 엔드포인트 속성 참조
• 서비스 콜아웃의 대안: JavaScript로 작성된 HTTPClient. 자세한 내용은 JavaScript 객체 모델