IntegrationCallout 정책

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

개요

IntegrationCallout 정책을 사용하면 API 트리거가 있는 Apigee 통합을 실행할 수 있습니다. 하지만 통합을 실행하기 전에 SetIntegrationRequest 정책을 실행해야 합니다. SetIntegrationRequest 정책은 요청 객체를 만들고 이 객체를 IntegrationCallout 정책에 흐름 변수로 제공합니다. 요청 객체에는 API 트리거 이름, 통합 프로젝트 ID, 통합 이름, SetIntegrationRequest 정책에 구성된 기타 세부정보 등의 통합 세부정보가 있습니다. IntegrationCallout 정책은 요청 객체의 흐름 변수를 사용하여 통합을 실행합니다. 흐름 변수에 통합 실행 응답을 저장하도록 IntegrationCallout 정책을 구성할 수 있습니다.

IntegrationCallout 정책은 프록시 흐름 중에 통합을 실행하려는 경우에 유용합니다. 또는 IntegrationCallout 정책을 구성하는 대신 통합 엔드포인트를 대상 엔드포인트로 지정하여 통합을 실행할 수도 있습니다. 자세한 내용은 IntegrationEndpoint를 참조하세요.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

참고: IntegrationCallout 정책을 실행하려면 인증 토큰이 필요합니다. 하지만 정책 정의에는 명시적 Authentication 요소가 없습니다. Apigee는 내부적으로 인증 토큰을 추가합니다. IntegrationCallout 정책이 성공적으로 인증하려면 통합을 실행하는 데 필요한 IAM 역할이 있는 서비스 계정으로 API 프록시를 배포해야 합니다. 필요한 역할에 대한 자세한 내용은 통합에 대한 IAM 역할을 참조하세요. API 프록시 배포에 대한 자세한 내용은 Apigee에 배포를 참조하세요.

<IntegrationCallout>

IntegrationCallout 정책을 지정합니다.

기본값	해당 사항 없음
필수 여부	필수
유형	복합 유형
상위 요소	해당 사항 없음
하위 요소	<DisplayName> <AsyncExecution> <Request> <Response>

다음 표에서는 <IntegrationCallout>의 하위 요소를 간략하게 설명합니다.

하위 요소	필수 여부	설명
<DisplayName>	선택사항	정책의 커스텀 이름입니다.
<AsyncExecution>	선택사항	통합을 동기 모드 또는 비동기 모드로 실행해야 하는지 여부를 지정합니다.
<Request>	필수	SetIntegrationRequest 정책에 의해 생성된 요청 객체가 있는 흐름 변수입니다.
<Response>	선택사항	통합 응답을 저장할 흐름 변수입니다.

<IntegrationCallout> 요소는 다음 구문을 사용합니다.

구문

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="[true|false]" enabled="[true|false]" name=POLICY_NAME>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  <AsyncExecution>BOOLEAN_ASYNC_EXECUTION</AsyncExecution>
  <Request clearPayload="[true|false]">REQUEST_FLOW_VARIABLE_NAME</Request>
  <Response>RESPONSE_FLOW_VARIABLE_NAME</Response>
</IntegrationCallout>

예

다음 예시는 IntegrationCallout 정책 정의를 보여줍니다.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<IntegrationCallout continueOnError="false" enabled="true" name="Integration-Callout">
  <DisplayName>Integration-Callout-1</DisplayName>
  <AsyncExecution>true</AsyncExecution>
  <Request clearPayload="true">my_request_flow_var</Request>
  <Response>my_response_flow_var</Response>
</IntegrationCallout>

이 요소에는 다음과 같이 모든 정책에 공통된 속성이 있습니다.

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

하위 요소 참조

이 섹션에서는 <IntegrationCallout>의 하위 요소를 설명합니다.

<DisplayName>

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

<DisplayName> 요소는 모든 정책에 공통으로 적용됩니다.

기본값	해당 사항 없음
필수 여부	선택사항. <DisplayName>을 생략하면 정책의 name 속성 값이 사용됩니다.
유형	문자열
상위 요소	<PolicyElement>
하위 요소	없음

<DisplayName> 요소는 다음 구문을 사용합니다.

구문

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

예시

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

<DisplayName> 요소에 속성 또는 하위 요소가 없습니다.

<AsyncExecution>

통합을 실행할 모드를 지정합니다. 동기식 또는 비동기식으로 통합을 실행할 수 있습니다.

true로 설정하면 통합이 비동기식으로 실행됩니다. false로 설정하면 통합이 동기식으로 실행됩니다.

• 비동기 모드: 통합 실행 요청이 엔드포인트에 도달하면 엔드포인트가 즉시 통합 실행 ID를 반환하지만 <ScheduleTime> 요소에서 지정한 시간에 통합 실행을 시작합니다. <ScheduleTime> 요소를 설정하지 않으면 통합이 즉시 실행되도록 예약됩니다. 통합이 즉시 실행되도록 예약되지만 몇 초 후에 실행이 시작될 수 있습니다. 통합이 시작되면 다음 두 작업이 수행됩니다.
  • 호출자가 처리를 계속할 수 있도록 통합이 HTTP 200 OK 상태 코드를 반환합니다.
  • IntegrationCallout 정책이 완료됩니다.
  통합이 시작되면 실행을 완료하는 데 최대 50분으로 시간이 제한됩니다.
• 동기 모드: 통합 실행 요청이 엔드포인트에 도달하면 엔드포인트가 즉시 통합 실행을 시작하고 응답을 기다립니다. 실행을 완료하는 데 걸리는 최대 시간은 2분입니다. 실행이 완료되면 엔드포인트는 실행 ID와 기타 응답 데이터가 포함된 응답을 반환합니다.

기본값	false
필수 여부	선택사항
유형	부울
상위 요소	<IntegrationCallout>
하위 요소	없음

<AsyncExecution> 요소는 다음 구문을 사용합니다.

구문

<AsyncExecution>BOOLEAN</AsyncExecution>

예

다음 예시에서는 비동기 실행을 true로 설정합니다.

<AsyncExecution>true</AsyncExecution>

<Request>

SetIntegrationRequest 정책에 의해 생성된 요청 객체가 있는 흐름 변수를 지정합니다. IntegrationCallout 정책은 통합을 실행하기 위해 이 요청 객체를 Apigee Integration으로 보냅니다.

기본값	해당 사항 없음
필수 여부	필수
유형	문자열
상위 요소	<IntegrationCallout>
하위 요소	없음

<Request> 요소는 다음 구문을 사용합니다.

구문

<Request clearPayload="true">FLOW_VARIABLE_NAME</Request>

예

다음 예시에서는 요청 객체를 my_request_flow_var 흐름 변수에서 사용할 수 있음을 지정합니다.

<Request clearPayload="true">my_request_flow_var</Request>

다음 표는 <Request>의 속성을 설명합니다.

속성	필수 여부	유형	설명
clearPayload	선택사항	부울	통합 실행 요청을 전송한 후 요청 객체를 메모리에서 지워야 하는지 여부를 지정합니다. true로 설정하면 Apigee가 요청 객체를 삭제합니다. false로 설정하면 Apigee가 요청 객체를 삭제하지 않습니다. 이 속성을 지정하지 않으면 기본값은 true이고 요청 객체가 메모리에서 삭제됩니다.

<Response>

통합 응답을 저장할 흐름 변수를 지정합니다.

이 요소를 지정하지 않으면 정책은 integration.response 흐름 변수에 응답을 저장합니다.

기본값	integration.response
필수 여부	선택사항
유형	문자열
상위 요소	<IntegrationCallout>
하위 요소	없음

<Response> 요소는 다음 구문을 사용합니다.

구문

<Response>FLOW_VARIABLE_NAME</Response>

예

다음 예시에서는 통합 실행 응답을 my_response_flow_var 흐름 변수에 저장합니다.

<Response>my_response_flow_var</Response>

오류 코드

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

런타임 오류

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

오류 코드	HTTP 상태	원인
entities.UnresolvedVariable	500	이 오류는 Apigee가 integration.project.id 또는 integration.name 변수를 확인할 수 없는 경우에 발생합니다.
steps.integrationcallout.ExecutionFailed	500	이 오류는 백엔드 대상 서비스가 4xx 또는 5xx와 같은 HTTP 오류 상태를 반환하면 발생할 수 있습니다. 가능한 원인은 다음과 같습니다. 프록시로 배포된 서비스 계정에 통합을 실행할 수 있는 잘못된 권한이 있습니다. 통합 또는 API 트리거가 존재하지 않습니다. Google Cloud 프로젝트에 Apigee 통합이 사용 설정되지 않았습니다. SetIntegrationRequest 정책에서 <ScheduleTime> 요소를 구성했고 IntegrationCallout 정책의 AsyncExecution이 false로 설정되었습니다.
steps.integrationcallout.NullRequestVariable	500	이 오류는 <Request>에 지정된 흐름 변수가 null인 경우에 발생합니다.
steps.integrationcallout.RequestVariableNotMessageType	500	이 오류는 Request 요소로 지정된 흐름 변수가 메시지 유형이 아닌 경우에 발생합니다.
steps.integrationcallout.RequestVariableNotRequestMessageType	500	이 오류는 Request 요소로 지정된 흐름 변수가 요청 메시지 유형이 아닌 경우에 발생합니다.
messaging.adaptors.http.filter.GoogleTokenGenerationFailure	500	이 오류는 잘못된 서비스 계정 구성으로 인해 발생할 수 있습니다. 가능한 원인은 다음과 같습니다. 프로젝트에 프록시로 배포된 서비스 계정이 없습니다. 프록시로 배포된 서비스 계정이 중지됩니다.

오류 변수

정책에 실행 오류가 발생할 때마다 Apigee는 오류 메시지를 생성합니다. 오류 응답에서 이러한 오류 메시지를 볼 수 있습니다. 시스템에서 생성된 오류 메시지가 제품의 컨텍스트와 관련이 없을 경우가 많습니다. 메시지를 보다 의미 있게 만들기 위해 오류 유형에 따라 오류 메시지를 맞춤설정할 수 있습니다.

오류 메시지를 맞춤설정하려면 오류 규칙 또는 RaiseFault 정책을 사용하면 됩니다. 오류 규칙과 RaiseFault 정책의 차이점에 대한 자세한 내용은 FaultRules와 RaiseFault 정책 비교를 참조하세요. 오류 규칙과 RaiseFault 정책 모두에서 Condition 요소를 사용하여 조건을 확인해야 합니다. Apigee는 각 정책에 고유한 오류 변수를 제공하며 정책이 런타임 오류를 트리거할 때 오류 변수 값이 설정됩니다. 이러한 변수를 사용하여 특정 오류 조건을 확인하고 적절한 조치를 취할 수 있습니다. 오류 조건 확인에 대한 자세한 내용은 빌드 조건을 참조하세요.

다음 표에서는 이 정책과 관련된 오류 변수를 설명합니다.

변수	각 항목의 의미는 다음과 같습니다.	예
fault.name	fault.name은 런타임 오류 표에 나열된 오류 중 하나와 일치할 수 있습니다. 오류 이름은 오류 코드의 마지막 부분입니다.	fault.name Matches "UnresolvedVariable"
IntegrationCallout.POLICY_NAME.failed	POLICY_NAME은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	IntegrationCallout.integration-callout-1.failed = true

정책 오류에 대한 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

관련 주제

Apigee의 통합 기능에 대한 자세한 내용은 Apigee Integration이란 무엇인가요?를 참조하세요.