Java 콜아웃을 만드는 방법

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

Apigee Edge 문서 보기

자바 콜아웃이란 무엇인가요?

Apigee는 보안, 데이터 변환, 트래픽 관리 등과 같은 일반적인 API 관리 요구사항을 해결하는 다양한 정책을 제공합니다.

하지만 표준 정책에 구현되지 않은 커스텀 동작이 API에 필요한 경우가 있습니다. 이러한 경우 Apigee는 맞춤설정된 API 동작을 스크립트화하거나 코딩할 수 있도록 하는 여러 옵션을 제공합니다. 한 가지 방법은 자바에서 원하는 동작을 구현하는 것입니다.

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

프록시에서 자바 코드를 사용하려면 어떻게 해야 하나요?

자바 콜아웃 정책을 사용하면 실행 중인 프록시 흐름 내에서 자바 코드를 호출할 수 있습니다. 자바 코드는 코드와 실행 중인 프록시가 상호작용할 수 있도록 특정 Apigee별 자바 인터페이스를 구현해야 합니다. 예를 들어 자바 메서드는 프록시의 현재 흐름 컨텍스트 내에서 헤더, 쿼리 매개변수, 흐름 변수, 기타 항목을 가져오고 설정하기 위해 존재합니다.

자바 콜아웃은 언제 사용해야 하나요?

자바 콜아웃이 유용한 상황과 다른 접근 방식을 고려해야 하는 상황을 살펴보겠습니다.

첫째, 다른 접근 방식 고려

자바 콜아웃을 사용하기 전에 대신 사용할 수 있는 다른 접근 방식이 있다는 사실을 참고하세요. 예를 들면 다음과 같습니다.

  • 원격 서비스에 대한 HTTP API 호출과 같은 가벼운 작업의 경우 ServiceCallout 정책을 사용하는 것이 좋습니다. 서비스 콜아웃 정책을 참조하세요.
  • HTTP 헤더, 매개변수, 메시지 콘텐츠 수정 또는 추출과 같이 메시지 콘텐츠와 비교적 간단한 상호작용을 원할 경우 자바스크립트 또는 PythonScript 정책을 사용할 수 있습니다.

자바 코드로 수행할 수 있는 작업

자바 콜아웃은 다음과 같은 기본 작업을 지원합니다.

  • 요청 또는 응답 메시지 검사 또는 조작
  • 흐름 변수를 가져오고 설정합니다. 자바 메서드를 사용하여 Apigee 흐름 변수에 액세스할 수 있습니다. 키 값 맵(KVM) 정보에 액세스하려면 KVM 정책을 사용하고 KVM 값을 흐름 변수에 할당한 다음 자바 콜아웃 내에서 흐름 변수에 액세스할 수 있습니다.
  • 외부 서비스 호출
  • 오류 발생
  • 오류 메시지 및 상태 코드 조작

자바 코드로 수행할 수 없는 작업

대부분의 시스템 호출은 허용되지 않습니다. 다음 작업은 수행할 수 없습니다.

  • 내부 파일 시스템 읽기 또는 쓰기. 즉, 자바 패키지를 사용하여 내부 파일 시스템에 대한 읽기/쓰기 작업을 수행할 수 없습니다. 하지만 외부 원격 호출을 실행할 수는 있습니다.
  • 머신의 현재 프로세스, 프로세스 목록 또는 CPU/메모리 사용률에 대한 정보를 가져오기
  • expressions-1.0.0.jar 및 message-flow-1.0.0.jar의 소스 코드에 액세스합니다.

이러한 호출의 일부는 작동할 수 있지만 지원되지 않으며 언제든지 사용 중지될 수 있습니다. 코드에서 이러한 호출을 실행해서는 안 됩니다.

Apigee에 포함된 자바 라이브러리를 사용하거나 의존하지 마세요. 이러한 라이브러리는 Apigee 제품 기능에만 사용되며 출시 버전을 갈아탈 때 라이브러리를 사용할 수 있다는 보장은 없습니다. 이러한 라이브러리를 사용하는 경우 비프로덕션 데모에서만 사용하세요.

Hello 자바 콜아웃

기본적인 hello world 자바 콜아웃 예시를 살펴보겠습니다. 이 예시에서는 'hello world' 응답을 반환하는 자바 콜아웃이 포함된 간단한 프록시를 만듭니다. 프록시는 다음 두 가지 응답 중 하나를 반환할 수 있습니다.

  • 'name' 값이 지정된 'username' 헤더를 전달하면 프록시가 다음을 반환합니다.

    Hello, <name>!
  • 헤더를 생략하면 프록시가 다음을 반환합니다.

    "Hello, Guest!"

시작 프로젝트 다운로드

편의를 위해 GitHub의 Apigee api-platform-samples 저장소에 기본 프로젝트가 준비되어 있습니다.

  1. api-platform-samples를 시스템에 다운로드하거나 복제합니다. 시스템에 이미 api-platform-samples가 있으면 pull을 실행하여 최신 버전이 있는지 확인합니다.
  2. 원하는 터미널 또는 코드 편집기에서 api-platform-samples/doc-samples/java-hello 프로젝트로 이동합니다.

자바 코드 작성

  1. 자바 소스 파일 java-hello/callout/src/main/java/HelloJava.java를 엽니다. 이 파일은 구현할 기본 자바 클래스의 골조 버전입니다. Apigee 자바 콜아웃 코드에는 가져온 패키지가 필요합니다. 이 클래스는 프록시 실행 컨텍스트에 액세스할 수 있도록 하는 메서드를 제공합니다. 잠시 후 이 코드를 컴파일 및 배포하는 단계를 살펴보겠습니다.
    package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;


public class HelloJava implements Execution {

        public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {

                try {

                        // Your code here.

            return ExecutionResult.SUCCESS;

                } catch (Exception e) {
                        return ExecutionResult.ABORT;
                }
        }

}
  2. 주석이 포함된 // Your code here 줄을 다음 코드로 바꿉니다.

    String name = messageContext.getMessage().getHeader("username");

if (name != null && name.length()>0) {
        messageContext.getMessage().setContent("Hello, " + name + "!");
        messageContext.getMessage().removeHeader("username");
} else {
        messageContext.getMessage().setContent("Hello, Guest!");
}
  3. 파일을 저장합니다.


Maven으로 코드 컴파일

  1. Maven이 설치되어 있는지 확인합니다.

    mvn -version
  2. 다음 방법 중 하나를 사용하여 로컬 Maven 저장소에 필요한 JAR 종속 항목을 설치합니다.
    • 다음 스니펫을 pom.xml 파일에 추가하여 Artifact Registry에서 필요한 JAR 종속 항목을 다운로드합니다. 
      <repositories>
  <repository>
    <id>artifact-registry</id>
    <url>https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>com.apigee.gateway.libraries</groupId>
    <artifactId>message-flow</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
  <dependency>
    <groupId>com.apigee.infra.libraries</groupId>
    <artifactId>expressions</artifactId>
    <version>1.0.0</version>
    <scope>compile</scope>
    <type>jar</type>
  </dependency>
</dependencies>
    • 다음 curl 호출을 사용하여 Artifact Registry에서 필요한 JAR 종속 항목을 다운로드합니다. 
      curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/gateway/libraries/message-flow/1.0.0/message-flow-1.0.0.jar" -v -L -o message-flow-1.0-0.jar
        
      curl "https://us-maven.pkg.dev/apigee-release/apigee-java-callout-dependencies/com/apigee/infra/libraries/expressions/1.0.0/expressions-1.0.0.jar" -v -L -o expressions-1.0.0.jar
    • java-hello/buildsetup.sh 스크립트를 실행합니다. 이 스크립트는 Apigee GitHub 저장소에서 필요한 JAR 종속 항목을 다운로드합니다.
  3. cd 명령어로 java-hello/callout 디렉터리로 이동합니다.
  4. Maven을 실행합니다.

    mvn clean package
  5. 원하는 경우 JAR 파일 edge-custom-policy-java-hello.jar가 java-hello/apiproxy/resources/java에 복사되었는지 확인합니다. 프록시로 배포하려는 JAR 파일에 필요한 위치입니다.

프록시 배포 및 호출

API 프록시를 배포하고 테스트하려면 다음 단계를 따르세요.

  1. java-hello 디렉터리로 변경합니다.
  2. API 프록시 번들을 압축합니다. 
    zip apiproxy-bundle.zip -r apiproxy -x \*.\*~
  3. 프록시를 배포하는 가장 간단한 방법은 ZIP 파일로 번들해서 프록시 번들을 Apigee 조직의 환경에 업로드하는 것입니다. API 프록시 만들기를 참조하세요. 프록시 번들 업로드 옵션을 사용해야 합니다. Apigee 커뮤니티의 프록시 번들에 API 프록시 업로드에 대한 도움말 및 유용한 정보를 참조하세요.
  4. 프록시가 배포되면 다음을 호출합니다.
    curl  https://$HOSTNAME/java-hello -H "username:Will"

    그러면 'Hello, Will!'이 반환됩니다.

프록시 정보

이 프록시에서 사용되는 정책을 간략하게 살펴보겠습니다. 정책이 프록시 흐름에서 어디에 있고 그 이유는 무엇인지 유심히 살펴보세요.

메시지 할당 정책

메시지 할당 정책은 ProxyEndpoint 요청 흐름에 연결됩니다. 요청에서 사용자 이름 헤더를 복사하여 응답에 할당합니다. 이 작업을 사용하면 응답 흐름에 연결된 자바 콜아웃 정책을 사용해 사용자 이름 헤더에 액세스하고 이 헤더의 값을 사용해 커스텀 응답 본문을 빌드할 수 있습니다.

<AssignMessage async="false" continueOnError="false" enabled="true" name="CopyHeader">
    <DisplayName>CopyHeader</DisplayName>
    <Copy source="request">
        <Headers>
          <Header name="username"/>
        </Headers>
    </Copy>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
    <AssignTo createNew="false" transport="http" type="response"/>
</AssignMessage>

자바 콜아웃 정책

자바 콜아웃 정책은 응답 흐름에 연결됩니다. 커스텀 자바 코드가 응답 헤더 및 메시지를 변경하기 때문입니다. 정책의 ClassName 요소는 정책에서 실행되는 기본 클래스를 지정합니다. ResourceURL 요소는 프록시의 resources/java 디렉터리에 빌드되어 추가된 JAR 파일의 이름입니다.

<JavaCallout name="hello-java">
    <ClassName>com.apigeesample.HelloJava</ClassName>
    <ResourceURL>java://edge-custom-policy-java-hello.jar</ResourceURL>
</JavaCallout>

자바 콜아웃에 관해 알아야 할 사항

자바 콜아웃을 구현할 때 유의해야 할 중요한 사항은 다음과 같습니다.

  • com.apigee.flow.execution 및 com.apigee.flow.message 패키지에서 클래스를 가져오기합니다. 이러한 패키지는 패키징되어 배포된 JAR 파일에 포함되어야 합니다. 관리 UI 프록시 편집기를 통해 자바 JAR을 업로드하거나 로컬에서 개발하는 API 프록시의 /resources/java 디렉터리에 포함할 수 있습니다.
  • Execution 인터페이스를 구현합니다. API 프록시 내에서 실행되는 모든 자바 코드는 실행을 구현해야 합니다.
  • 자바 콜아웃 정책에는 실제 코드가 없습니다. 대신 자바 콜아웃 정책은 자바 '리소스'를 참조하므로 JAR로 패키징해야 합니다.
  • 피해야 할 패키지 이름: 자바 콜아웃에 io.apigee 또는 com.apigee를 패키지 이름으로 사용하면 안 됩니다. 이는 다른 Apigee 모듈에서 예약 및 사용됩니다.
  • 자바 콜아웃이 독립 JAR 파일로 패키징된 타사 라이브러리를 추가로 사용하는 경우 이 JAR 파일을 /resources/java 디렉터리에 배치하여 런타임에 올바르게 로드되게 하세요.
  • JAR이 여러 개인 경우 단순히 추가 리소스로 추가하면 됩니다. 추가 JAR 파일을 참조하도록 정책 구성을 수정할 필요는 없습니다. /resources/java 안에 넣기만 하면 됩니다.
  • 자바 JAR 업로드에 대한 상세 내용은 리소스 파일을 참조하세요.