REST 요청을 사용하여 AEM Forms 호출 invoking-aem-forms-using-rest-requests

Workbench에서 만든 프로세스는 REST(대리 상태 전송) 요청을 통해 호출할 수 있도록 구성할 수 있습니다. REST 요청은 HTML 페이지에서 전송됩니다. 즉, REST 요청을 사용하여 웹 페이지에서 직접 Forms 프로세스를 호출할 수 있습니다. 예를 들어 웹 페이지의 새 인스턴스를 열 수 있습니다. 그런 다음 Forms 프로세스를 호출하고 HTTP POST 요청에서 전송된 데이터로 렌더링된 PDF 문서를 로드할 수 있습니다.

두 가지 유형의 HTML 클라이언트가 있습니다. 첫 번째 HTML 클라이언트는 JavaScript로 작성된 AJAX 클라이언트입니다. 두 번째 클라이언트는 전송 단추가 들어 있는 HTML 양식입니다. HTML 기반 클라이언트 응용 프로그램만 가능한 REST 클라이언트가 아닙니다. HTTP 요청을 지원하는 모든 클라이언트 응용 프로그램은 REST 호출을 사용하여 서비스를 호출할 수 있습니다. 예를 들어 PDF 양식에서 REST 호출을 사용하여 서비스를 호출할 수 있습니다. (자세한 내용은 Acrobat에서 MyApplication/EncryptDocument 프로세스를 호출하는 중)

REST 요청을 사용할 때는 Forms 서비스를 직접 호출하지 않는 것이 좋습니다. 대신 Workbench에서 만든 프로세스를 호출합니다. REST 호출을 위한 프로세스를 만들 때는 프로그래밍 방식의 시작 지점을 사용하십시오. 이 경우 REST 엔드포인트가 자동으로 추가됩니다. Workbench에서 프로세스 만들기에 대한 내용은 Workbench 사용.

REST를 사용하여 서비스를 호출하는 경우 AEM Forms 사용자 이름과 암호를 입력하라는 메시지가 표시됩니다. 그러나 사용자 이름과 암호를 지정하지 않으려면 서비스 보안을 비활성화할 수 있습니다.

REST를 사용하여 Forms 서비스를 호출하려면(프로세스가 활성화되면 프로세스가 서비스가 됨) REST 엔드포인트를 구성합니다. 자세한 내용은 관리 도움말)

REST 엔드포인트가 구성된 후에는 HTTP GET 메서드 또는 POST 메서드를 사용하여 Forms 서비스를 호출할 수 있습니다.

 action="https://hiro-xp:8080/rest/services/[ServiceName]/[OperationName]:[ServiceVersion]" method="post" enctype="multipart/form-data"

필수 ServiceName value는 호출할 Forms 서비스의 이름입니다. 선택 사항입니다 OperationName 값은 서비스 작업 이름입니다. 이 값을 지정하지 않으면 기본적으로 이 이름이 invoke: 프로세스를 시작하는 작업 이름입니다. 선택 사항입니다 ServiceVersion 값은 X.Y 형식으로 인코딩된 버전입니다. 이 값을 지정하지 않으면 최신 버전이 사용됩니다. 다음 enctype 값을 사용할 수도 있습니다 application/x-www-form-urlencoded.

지원되는 데이터 유형 supported-data-types

REST 요청을 사용하여 AEM Forms 서비스를 호출할 때 다음 데이터 유형이 지원됩니다.

비동기 호출 asynchronous-invocations

인간 중심 장기 프로세스와 같은 일부 AEM Forms 서비스는 완료하는 데 오랜 시간이 필요합니다. 이러한 서비스는 비차단 방식으로 비동기식으로 호출할 수 있습니다. (자세한 내용은 인간 중심 장기 프로세스 호출)

AEM Forms 서비스를 대체하여 비동기식으로 호출할 수 있습니다 services with async_invoke 다음 예와 같이 호출 URL에서 검색할 수 있습니다.

 http://localhost:8080/rest/async_invoke/SomeService. SomeOperation?integer_input_variable=123&string_input_variable=abc

이 URL은 이 호출을 담당하는 작업의 식별자 값("text/plain" 형식)을 반환합니다.

비동기 호출의 상태는 services 치환된 async_status. URL에는 job_id 이 호출과 연관된 작업의 식별자 값을 지정하는 매개 변수입니다. 예:

 http://localhost:8080/rest/async_status/SomeService.SomeOperation?job_id=2345353443366564

이 URL은 작업 관리자의 사양에 따라 작업 상태를 인코딩하는 정수 값("text/plain" 형식)을 반환합니다(예: 2는 실행 중임을 의미하며 3은 완료됨을 의미하며 4는 실패함 등).

작업이 완료되면 URL은 서비스가 동기식으로 호출된 것처럼 동일한 결과를 반환합니다.

작업이 완료되고 결과가 검색되면, 작업은 다음과 같은 호출 URL을 사용하여 처리할 수 있습니다. services 로 대체됨 async_dispose. URL에는 job_id 작업의 식별자 값을 지정하는 매개 변수입니다. 예:

 http://localhost:8080/rest/async_dispose/SomeService.SomeOperation?job_id=2345353443366564

작업이 성공적으로 처리되면 이 URL은 빈 메시지를 반환합니다.

오류 보고 error-reporting

서버에서 throw되는 예외로 인해 동기 또는 비동기 호출 요청을 완료할 수 없는 경우 HTTP 응답 메시지의 일부로 예외가 보고됩니다. 호출 URL 또는 async_result 비동기 호출의 경우 URL에 .xml 접미사가 없으면 REST 공급자는 HTTP 코드를 반환합니다 500 Internal Server Error 다음에 예외 메시지가 옵니다.

호출 URL 또는 async_result 비동기 호출의 경우 URL에 .xml 접미사가 있고 REST 공급자는 HTTP 코드를 반환합니다 200 OK뒤에 다음 형식으로 예외를 설명하는 XML 문서가 옵니다.

 <exception>
       <exception_class_name>[
       <DSCError>
          <componentUID>component_UUD</componentUID>
         <errorCode>error_code</errorCode>
         <minorCode>minor_code</minorCode>
         <message>error_message</message>
       </DSCError>
 ]
       <message>exception_message</message>
     <stackTrace>exception_stack_trace</stackTrace>
       </exception_class_name>
     <exception>
       </exception>
 </exception>

다음 DSCError 요소는 선택 사항이며 예외가 의 인스턴스인 경우에만 나타납니다 com.adobe.idp.dsc.DSCException.

보안 및 인증 security-and-authentication

AEM Forms 관리자는 보안 전송을 통해 REST 호출을 제공하기 위해 AEM Forms을 호스팅하는 J2EE 애플리케이션 서버에서 HTTPS 프로토콜을 활성화할 수 있습니다. 이 구성은 J2EE 애플리케이션 서버에만 적용됩니다. 양식 서버 구성의 일부가 아닙니다.

REST 호출을 지원하는 AEM Forms 서비스 aem-forms-services-that-support-rest-invocation

직접 서비스와 비교하여 Workbench를 사용하여 만든 프로세스를 호출하는 것이 좋지만 REST 호출을 지원하는 일부 AEM Forms 서비스가 있습니다. 프로세스를 직접 호출하는 것이 권장되는 이유는 프로세스를 호출하는 것이 더 효율적이기 때문입니다. 다음 시나리오를 고려하십시오. REST 클라이언트에서 정책을 작성한다고 가정합니다. 즉, REST 클라이언트가 정책 이름, 오프라인 임대 기간과 같은 값을 정의하도록 합니다.

정책을 만들려면 다음과 같은 복잡한 데이터 유형을 정의해야 합니다 PolicyEntry 개체. A PolicyEntry 개체는 정책과 연관된 권한과 같은 속성을 정의합니다. (자세한 내용은 정책 만들기)

정책을 만들기 위해 REST 요청을 보내는 대신(예: PolicyEntry 객체)를 사용하여 Workbench를 사용하여 정책을 만드는 프로세스를 만듭니다. 프로세스 이름을 정의하는 문자열 값 또는 오프라인 임대 기간을 정의하는 정수와 같은 기본 입력 변수를 허용하는 프로세스를 정의합니다.

이렇게 하면 작업에 필요한 복잡한 데이터 형식이 포함된 REST 호출 요청을 만들 필요가 없습니다. 이 프로세스는 복잡한 데이터 유형을 정의하며, REST 클라이언트에서 수행하는 모든 작업은 프로세스를 호출하고 기본 데이터 유형을 전달합니다. REST를 사용하여 프로세스를 호출하는 방법에 대한 자세한 내용은 REST를 사용하여 MyApplication/EncryptDocument 프로세스를 호출하는 중.

다음 목록은 직접 REST 호출을 지원하는 AEM Forms 서비스를 지정합니다.

REST 호출 예 rest-invocation-examples

다음 REST 호출 예가 제공됩니다.

프로세스에 부울 값 전달

다음 HTML 예는 두 개를 전달합니다 Boolean 이름이 지정된 AEM Forms 프로세스에 대한 값 RestTest2. 호출 메서드의 이름은 invoke 버전이 1.0입니다. HTML Post 방법이 사용되는지 확인합니다.

 <html>
 <body>

 <form name="input" action="http://localhost:9080/rest/services/RestTest2/invoke/1.0" method="post">

 Boolean 1: <input type="text" name="inBooleanList" value="true">
 Boolean 2: <input type="text" name="inBooleanList" value="false">
 <input type="submit" value="Submit">

 </form>

 </body>
 </html>

프로세스에 날짜 값 전달

다음 HTML 예는 날짜 값을 라는 AEM Forms 프로세스에 전달합니다 SOAPEchoService. 호출 메서드의 이름은 echoCalendar. HTML Post 메서드를 사용합니다.

 <html>
 <body>

 <form name="input" action="http://localhost:9080/rest/services/SOAPEchoService/echoCalendar" method="post">

 Date: <input type="text" name="value-to-echo" value="2009-01-02T12:15:30Z">
 <input type="submit" value="Submit">

 </form>

 </body>
 </html>

프로세스에 문서 전달

다음 HTML 예는 라는 AEM Forms 프로세스를 호출합니다. MyApplication/EncryptDocument PDF 문서가 필요합니다. 이 프로세스에 대한 자세한 내용은 MTOM을 사용하여 AEM Forms 호출.

 <html>
 <body>

 <form name="input" action="http://localhost:9080/rest/services/MyApplication/EncryptDocument/invoke" method="post"
          enctype="multipart/form-data">

 File: <input type="file" name="value-to-echo">
 <input type="submit" value="Submit"/>

 </form>

 </body>
 </html>

프로세스에 문서 및 텍스트 값 전달

다음 HTML 예는 라는 AEM Forms 프로세스를 호출합니다. RestTest3 문서 및 두 개의 텍스트 값이 필요합니다. HTML Post 메서드가 사용됩니다.

 <html>
 <body>

 <form name="input" action="http://localhost:9080/rest/services/RestTest3" method="post"
          enctype="multipart/form-data">

 Doc: <input type="file" name="inDoc">
 String 1: <input type="text" name="inListOfStrings" value="hello">
 String 2: <input type="text" name="inListOfStrings" value="privet">
 <input type="submit" value="Submit"/>

 </form>

 </body>
 </html>

열거형 값을 프로세스에 전달

다음 HTML 예는 라는 AEM Forms 프로세스를 호출합니다. SOAPEchoService 열거형 값이 필요합니다. HTML Post 메서드가 사용됩니다.

 <html>
 <body>

 <form name="input" action="https://hiro-xp:8080/rest/services/SOAPEchoService/echoEnum" method="post">

 Color Enum Value: <input type="text" name="value-to-echo" value="green">
 <input type="submit" value="Submit">

 </form>

 </body>
 </html>

REST를 사용하여 MyApplication/EncryptDocument 프로세스를 호출하는 중

이름이 인 AEM Forms 단기 프로세스를 호출할 수 있습니다 MyApplication/EncryptDocument 사용.

이 프로세스가 호출되면 다음 작업을 수행합니다.

Acrobat에서 MyApplication/EncryptDocument 프로세스를 호출하는 중

REST 요청을 사용하여 Acrobat에서 Forms 프로세스를 호출할 수 있습니다. 예를 들어 MyApplication/EncryptDocument 프로세스. Acrobat에서 Forms 프로세스를 호출하려면 디자이너 내의 XDP 파일에 제출 단추를 놓습니다. (자세한 내용은 디자이너 도움말)

단추의 내에서 프로세스를 호출할 URL을 지정합니다 URL에 제출 필드 를 참조하십시오.

프로세스를 호출하는 전체 URL은 https://hiro-xp:8080/rest/services/MyApplication/EncryptDocument입니다.

프로세스에 PDF 문서가 입력 값으로 필요한 경우, 이전 그림에서 보듯이 양식을 PDF으로 제출하십시오. 또한 프로세스를 성공적으로 호출하려면 PDF 문서를 반환해야 합니다. 그렇지 않으면 반환 값을 처리할 수 없으며 오류가 발생합니다. 입력 프로세스 변수의 이름을 지정하지 않아도 됩니다. 예를 들어* MyApplication/EncryptDocument* 프로세스에는 이름이 인 입력 변수가 있습니다 inDoc. 양식이 PDF으로 제출되는 한 inDoc를 지정할 필요가 없습니다.

양식 데이터를 XML로 Forms 프로세스에 제출할 수도 있습니다. XML 데이터를 제출하려면 Submit As 드롭다운은 XML을 지정합니다. 프로세스의 반환 값은 PDF 문서여야 하므로 PDF 문서가 Acrobat에 표시됩니다.