JavaCallout 정책

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

Apigee Edge 문서 보기

정책 아이콘

소개

자바를 사용하여 Apigee 정책에 의해 즉시 제외된 커스텀 동작을 구현할 수 있습니다. 자바 코드에서 프록시 흐름의 메시지 속성(헤더, 쿼리 매개변수, 콘텐츠) 및 흐름 변수에 액세스할 수 있습니다. 이 정책을 처음 시작하는 경우 자바 콜아웃을 만드는 방법을 참조하세요.

지원되는 Java 버전은 Oracle JDK 11 및 OpenJDK 11입니다.

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

시간

가이드라인은 자바 콜아웃을 만드는 방법의 '자바 콜아웃을 사용해야 하는 경우?'를 참조하세요.

정보

자바 콜아웃 정책을 사용하면 흐름 변수를 가져오고 설정하고, 커스텀 로직을 실행하고, 오류를 처리하고, 요청 또는 응답에서 데이터를 추출하는 등의 작업을 수행할 수 있습니다. 이 정책을 사용하면 다른 표준 Apigee 정책이 적용되지 않는 맞춤 동작을 구현할 수 있습니다.

자바 애플리케이션을 필요한 패키지 JAR 파일로 패키징할 수 있습니다. 자바 콜아웃으로 수행할 수 있는 작업에는 몇 가지 제한사항이 있습니다. 아래의 제한사항에 나열되어 있습니다.

샘플

간단한 예시

자바 콜아웃을 만드는 방법

자바 코드에서 속성 검색

정책의 <Property> 요소를 사용하면 자바 코드에서 런타임에 검색할 수 있는 이름/값 쌍을 지정할 수 있습니다. 속성을 사용하는 작업 예시는 자바 콜아웃에서 속성을 사용하는 방법을 참조하세요.

<Property> 요소의 name 속성을 사용하여 자바 코드에서 속성에 액세스하는 데 사용할 이름을 지정합니다. <Property> 요소의 값(여는 태그와 닫는 태그 사이의 값)은 자바 코드에서 수신하는 값입니다. 이 값은 문자열이어야 합니다. 흐름 변수를 참조하여 값을 가져올 수 없습니다.

  • 속성을 구성합니다. 여기서 속성 값은 변수 이름 response.status.code입니다. 
    <JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
    <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
    <Properties>
        <Property name="source">response.status.code</Property>
    </Properties>
</Javascript>
  • 자바 코드에서 다음과 같이 실행 클래스 구현에 다음 생성자를 구현합니다.
    public class MyJavaCallout implements Execution{
    public MyJavaCallout(Map<string, string> props){
        
            // Extract property values from map.
    }
    ...
}

자바 코드에 흐름 변수 설정

자바 코드의 메시지 컨텍스트(흐름 변수)에서 변수를 설정하는 방법에 대한 자세한 설명은 이 Apigee 커뮤니티 게시물을 참조하세요.

요소 참조

요소 참조는 JavaCallout 정책의 요소 및 속성을 설명합니다.

<JavaCallout name="MyJavaCalloutPolicy">
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
</JavaCallout>

<JavaCallout> 속성

<JavaCallout name="MyJavaCalloutPolicy" enabled="true" continueOnError="false" async="false" >

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

속성 설명 기본값 현재 상태
name

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

 해당 사항 없음 필수
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참고 항목

 false 선택사항
enabled

정책을 시행하려면 true로 설정합니다.

정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

 true 선택사항
async

이 속성은 지원이 중단되었습니다.

 false 지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>
기본값

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
현재 상태 선택사항
유형 문자열

<ClassName> 요소

자바 콜아웃 정책을 실행할 때 실행되는 자바 클래스의 이름을 지정합니다. 클래스는 <ResourceURL>에서 지정된 JAR 파일에 포함되어야 합니다. 자바 콜아웃을 만드는 방법을 참조하세요.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
기본값: 해당 사항 없음
Presence: 필수
유형: 문자열

<Properties> 요소

런타임 시 자바 코드에서 액세스할 수 있는 새 속성을 추가합니다.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
기본값: 없음
현재 상태: 선택사항
유형: 문자열

<Property> 요소

런타임 시 자바 코드에서 액세스할 수 있는 속성을 지정합니다. 각 속성에 리터럴 문자열 값을 지정해야 합니다. 이 요소에서는 흐름 변수를 참조할 수 없습니다. 속성을 사용하는 작업 예시는 자바 콜아웃에서 속성을 사용하는 방법을 참조하세요.

<Properties>
    <Property name="propName">propertyValue</Property>
</Properties>
기본값: 없음
현재 상태: 선택사항
유형: 문자열

속성

속성 설명 기본값 현재 상태
이름

속성 이름을 지정합니다.

 해당 사항 없음 필수

<ResourceURL> 요소

이 요소는 자바 콜아웃 정책을 가동할 때 실행되는 자바 JAR 파일을 지정합니다.

리소스 파일에 설명된 대로 이 파일을 API 프록시 범위(API 프록시 번들의 /apiproxy/resources/java 아래 또는 API 프록시 편집기의 탐색창 중 스크립트 섹션 내)에 저장하거나 여러 API 프록시에서 재사용할 수 있도록 조직 또는 환경 범위에 저장할 수 있습니다.

<JavaCallout name="MyJavaCalloutPolicy">
   <ResourceURL>java://MyJavaCallout.jar</ResourceURL>
   <ClassName>com.example.mypolicy.MyJavaCallout</ClassName>
</JavaCallout>
기본값: 없음
현재 상태: 필수
유형: 문자열

오류 참조

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

런타임 오류

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

오류 코드 HTTP 상태 원인 수정
steps.javacallout.ExecutionError 500 JavaCallout policy 실행 중 자바 코드에서 예외가 발생하거나 null이 반환되면 발생합니다.

배포 오류

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

오류 이름 오류 문자열 HTTP 상태 발생 상황
ResourceDoesNotExist Resource with name [name] and type [type] does not exist 해당 사항 없음 <ResourceURL> 요소에 지정된 파일이 존재하지 않습니다.
JavaCalloutInstantiationFailed Failed to instantiate the JavaCallout Class [classname] 해당 사항 없음 <ClassName> 요소에 지정된 클래스 파일이 jar에 없습니다.
IncompatibleJavaVersion Failed to load java class [classname] definition due to - [reason] 해당 사항 없음 결함 문자열을 참조하세요. 지원되는 자바 버전은 Oracle JDK 7/8 및 OpenJDK 7/8입니다.
JavaClassNotFoundInJavaResource Failed to find the ClassName in java resource [jar_name] - [class_name] 해당 사항 없음 결함 문자열을 참조하세요.
JavaClassDefinitionNotFound Failed to load java class [class_name] definition due to - [reason] 해당 사항 없음 결함 문자열을 참조하세요.
NoAppropriateConstructor No appropriate constructor found in JavaCallout class [class_name] 해당 사항 없음 결함 문자열을 참조하세요.
NoResourceForURL Could not locate a resource with URL [string] 해당 사항 없음 결함 문자열을 참조하세요.

오류 변수

이러한 변수는 이 정책으로 오류가 트리거될 때 설정됩니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

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

오류 응답 예시

{  
   "fault":{  
      "faultstring":"Failed to execute JavaCallout. [policy_name]",
      "detail":{  
         "errorcode":"javacallout.ExecutionError"
      }
   }
}

오류 규칙 예시

<FaultRule name="JavaCalloutFailed">
    <Step>
        <Name>AM-JavaCalloutError</Name>
    </Step>
    <Condition>(fault.name Matches "ExecutionError") </Condition>
</FaultRule>

스키마

컴파일 및 배포

커스텀 자바 코드를 컴파일하고 프록시로 배포하는 방법에 대한 자세한 내용은 자바 콜아웃을 만드는 방법을 참조하세요.

제한사항

다음은 자바 콜아웃을 작성할 때 고려해야 할 제한사항입니다.

  • 대부분의 시스템 호출은 허용되지 않습니다. 예를 들어 내부 파일 시스템을 읽거나 쓸 수 없습니다.
  • 소켓을 통해 네트워크에 액세스합니다. Apigee에서는 sitelocal, anylocal, loopback, linklocal 주소에 대한 액세스를 제한합니다.
  • 콜아웃은 현재 프로세스, 프로세스 목록, 머신의 CPU/메모리 사용률 정보를 가져올 수 없습니다. 이러한 호출의 일부는 작동할 수 있지만 지원되지 않으며 언제든지 사용 중지될 수 있습니다. 이후 버전과의 호환성을 보장하려면 코드에서 이러한 호출을 수행하지 않아야 합니다.
  • Apigee에 포함된 자바 라이브러리에 대한 의존성은 지원되지 않습니다. 이러한 라이브러리는 Apigee 제품 기능에만 사용되며 출시 버전을 갈아탈 때 라이브러리를 사용할 수 있다는 보장은 없습니다.
  • io.apigee 또는 com.apigee를 자바 콜아웃의 패키지 이름으로 사용하면 안 됩니다. 해당 이름은 다른 Apigee 모듈에서 예약 및 사용됩니다.

패키징

JAR을 /resources/java의 API 프록시에 넣습니다. 자바 콜아웃이 독립 JAR 파일로 패키징된 타사 라이브러리를 추가로 사용하는 경우 이 JAR 파일을 /resources/java 디렉터리에 배치하여 런타임에 올바르게 로드되도록 하세요.

관리 UI를 사용하여 프록시를 만들거나 수정하는 경우 새 리소스를 추가하고 추가 종속 JAR 파일을 지정합니다. JAR이 여러 개인 경우 단순히 추가 리소스로 추가하면 됩니다. 추가 JAR 파일을 참조하도록 정책 구성을 수정할 필요는 없습니다. /resources/java 안에 넣기만 하면 됩니다.

자바 JAR 업로드에 대한 자세한 내용은 리소스 파일을 참조하세요.

Maven 또는 javac를 사용하여 자바 콜아웃을 패키징하고 배포하는 방법을 보여주는 자세한 예시는 자바 콜아웃을 만드는 방법을 참조하세요.

JavaDoc

자바 콜아웃 코드를 작성하기 위한 Javadoc는 GitHub에 포함되어 있습니다. HTML을 시스템에 클론하거나 다운로드한 다음 브라우저에서 index.html 파일을 열어야 합니다.

사용 참고사항 및 권장사항

  • 여러 자바 콜아웃을 작업할 때는 일반적인 JAR을 환경 범위 리소스로 업로드하는 것이 좋습니다. 이 권장사항은 동일 환경에 배포할 때 여러 프록시 번들로 동일한 JAR을 패키징하는 것보다 효율적입니다.
  • 하나의 환경에 동일한 JAR 파일의 여러 사본 또는 버전을 패키징하고 배포하지 마세요. 예를 들어 Apigee에서는 다음과 같이 작업하지 않는 것이 좋습니다.
    • 동일한 JAR을 프록시 번들의 일부로 배포하고 환경 리소스로도 배포
    • JAR 파일의 한 버전을 환경 리소스로 배포하고 다른 버전을 프록시 번들의 일부로 배포

    동일한 JAR의 사본을 여러 개 배포하면 잠재적인 ClassLoader 충돌로 인해 런타임 시 비확정적 동작이 발생할 수 있습니다.

  • 자바 콜아웃 정책에는 실제 코드가 없습니다. 대신 자바 콜아웃 정책은 자바 '리소스'를 참조하고 자바 코드가 실행되는 API 흐름의 단계를 정의합니다. 관리 UI 프록시 편집기를 통해 자바 JAR을 업로드하거나 로컬에서 개발하는 API 프록시의 /resources/java 디렉터리에 포함할 수 있습니다.
  • 원격 서비스에 대한 API 호출과 같은 가벼운 작업의 경우 ServiceCallout 정책을 사용하는 것이 좋습니다. 서비스 콜아웃 정책을 참조하세요.
  • HTTP 헤더, 매개변수, 메시지 콘텐츠 수정 또는 추출과 같이 메시지 콘텐츠와 비교적 간단한 상호작용을 원할 경우 Apigee는 자바스크립트 정책을 사용하는 것을 권합니다.