이 페이지는 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 |
정책의 내부 이름입니다. 원하는 경우 |
해당 사항 없음 | 필수 |
continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 정책이 실패해도 흐름 실행이 계속되도록 하려면 |
false | 선택사항 |
enabled |
정책을 시행하려면 정책을 중지하려면 |
true | 선택사항 |
async |
이 속성은 지원이 중단되었습니다. |
false | 지원 중단됨 |
<DisplayName> 요소
name
속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.
<DisplayName>Policy Display Name</DisplayName>
기본값 |
해당 사항 없음 이 요소를 생략하면 정책 |
---|---|
현재 상태 | 선택사항 |
유형 | 문자열 |
<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이 반환되면 발생합니다. |
build |
배포 오류
이런 오류는 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.
오류 이름 | 오류 문자열 | 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는 자바스크립트 정책을 사용하는 것을 권합니다.