Invocar AEM Forms mediante solicitudes REST invoking-aem-forms-using-rest-requests

Los ejemplos de este documento solo son para AEM Forms en un entorno JEE.

Los procesos creados en Workbench se pueden configurar para que se puedan invocar a través de solicitudes de transferencia de estado representacional (REST). Las solicitudes REST se envían desde páginas del HTML. Es decir, puede invocar un proceso de Forms directamente desde una página web mediante una solicitud REST. Por ejemplo, puede abrir una nueva instancia de una página web. A continuación, puede invocar un proceso de Forms y cargar un documento de PDF procesado con datos enviados en una solicitud de POST HTTP.

Existen dos tipos de clientes HTML. El primer cliente de HTML AJAX es un cliente de escrito en JavaScript. El segundo cliente es un formulario de HTML que contiene un botón de envío. Una aplicación cliente basada en HTML no es el único cliente REST posible. Cualquier aplicación cliente que admita solicitudes HTTP puede invocar un servicio mediante una invocación de REST. Por ejemplo, puede invocar un servicio utilizando una invocación de REST desde un formulario de PDF. (Consulte Invocar el proceso MyApplication/EncryptDocument desde Acrobat.)

Al utilizar solicitudes REST, se recomienda no invocar los servicios de Forms directamente. En su lugar, invoque los procesos creados en Workbench. Cuando cree un proceso diseñado para invocar a REST, utilice un punto de inicio programático. En este caso, el punto final REST se agrega automáticamente. Para obtener información sobre la creación de procesos en Workbench, consulte Uso de Workbench.

AEM Cuando invoca un servicio mediante REST, se le solicita un nombre de usuario y una contraseña de formularios de la aplicación de formularios de la manera más rápida y sencilla. Sin embargo, si no desea especificar un nombre de usuario y una contraseña, puede deshabilitar la seguridad del servicio.

Para invocar un servicio de Forms (un proceso se convierte en servicio cuando se activa el proceso) mediante REST, configure un extremo REST. (Consulte "Administración de puntos finales" en ayuda de administración.)

Una vez configurado un extremo REST, puede invocar un servicio de Forms mediante un método de GET HTTP o un método de POST.

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

La obligatoria ServiceName value es el nombre del servicio de Forms que se va a invocar. El opcional OperationName value es el nombre de la operación del servicio. Si no se especifica este valor, el nombre predeterminado es invoke, que es el nombre de la operación que inicia el proceso. El opcional ServiceVersion es la versión codificada en formato X.Y. Si no se especifica este valor, se utiliza la versión más actual. El enctype el valor también puede ser application/x-www-form-urlencoded.

Tipos de datos admitidos supported-data-types

Se admiten los siguientes tipos de datos al invocar servicios de AEM Forms mediante solicitudes REST:

Invocaciones asincrónicas asynchronous-invocations

Algunos servicios de AEM Forms, como los procesos de larga duración centrados en el ser humano, requieren mucho tiempo para completarse. Estos servicios se pueden invocar asincrónicamente de forma no bloqueante. (Consulte Invocar procesos de larga duración centrados en el ser humano.)

Un servicio de AEM Forms se puede invocar de forma asíncrona sustituyendo services con async_invoke en la URL de invocación, como se muestra en el siguiente ejemplo.

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

Esta URL devuelve el valor del identificador (en formato "text/plain") del trabajo responsable de esta invocación.

El estado de la invocación asincrónica se puede recuperar mediante una URL de invocación con services sustituido por async_status. La dirección URL debe contener un job_id parámetro que especifica el valor del identificador del trabajo asociado a esta invocación. Por ejemplo:

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

Esta URL devuelve un valor entero (en formato "texto/sin formato") que codifica el estado del trabajo según la especificación del Administrador de trabajos (por ejemplo, 2 significa en ejecución, 3 significa completado, 4 significa fallido, etc.).

Si se completa el trabajo, la dirección URL devuelve el mismo resultado que si el servicio se hubiera invocado sincrónicamente.

Una vez finalizado el trabajo y recuperado el resultado, el trabajo se puede eliminar mediante una URL de invocación con services se sustituye por async_dispose. La dirección URL también debe contener un job_id parámetro que especifica el valor de identificador del trabajo. Por ejemplo:

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

Si el trabajo se elimina correctamente, esta dirección URL devuelve un mensaje vacío.

Informes de errores error-reporting

Si no se puede completar una solicitud de invocación sincrónica o asincrónica debido a que se está iniciando una excepción en el servidor, la excepción se comunica como parte del mensaje de respuesta HTTP. Si la URL de invocación (o la async_result La dirección URL (si hay una invocación asincrónica) no tiene un sufijo .xml, el proveedor REST devuelve el código HTTP 500 Internal Server Error seguido de un mensaje de excepción.

Si la URL de invocación (o la async_result La dirección URL (si hay una invocación asincrónica) tiene un sufijo .xml, el proveedor REST devuelve el código HTTP 200 OKseguido de un documento XML que describe la excepción en el siguiente formato.

 <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>

El DSCError es opcional y está presente solo si la excepción es una instancia de com.adobe.idp.dsc.DSCException.

Seguridad y autenticación security-and-authentication

AEM Para proporcionar invocaciones de REST con un transporte seguro, un administrador de formularios de la puede habilitar el protocolo HTTPS en el servidor de aplicaciones J2EE que aloja AEM Forms. Esta configuración es específica del servidor de aplicaciones J2EE; no forma parte de la configuración del servidor de Forms.

Servicios de AEM Forms compatibles con la invocación de REST aem-forms-services-that-support-rest-invocation

Aunque se recomienda invocar directamente los procesos creados con Workbench en lugar de los servicios de, hay algunos servicios de AEM Forms que no admiten la invocación de REST. El motivo por el que se recomienda invocar un proceso directamente en lugar de un servicio es porque es más eficiente invocar un proceso. Considere el siguiente escenario. Supongamos que desea crear una directiva a partir de un cliente REST. Es decir, desea que el cliente REST defina valores como el nombre de la directiva o el período de concesión sin conexión.

Para crear una directiva, debe definir tipos de datos complejos como PolicyEntry objeto. A PolicyEntry define atributos como permisos asociados a la directiva. (Consulte Creación de directivas.)

En lugar de enviar una solicitud REST para crear una directiva (que incluiría la definición de tipos de datos complejos como un PolicyEntry ), cree un proceso que cree una directiva con Workbench. Defina el proceso para aceptar variables de entrada primitivas, como un valor de cadena que defina el nombre del proceso o un entero que defina el período de concesión sin conexión.

De este modo, no es necesario crear una solicitud de invocación de REST que incluya tipos de datos complejos que requiere la operación. El proceso define los tipos de datos complejos y todo lo que hace desde el cliente REST es invocar el proceso y pasar tipos de datos primitivos. Para obtener información sobre cómo invocar un proceso mediante REST, consulte Invocar el proceso MyApplication/EncryptDocument mediante REST.

Las siguientes listas especifican los servicios de AEM Forms que admiten la invocación directa de REST.

Ejemplos de invocación de REST rest-invocation-examples

Se proporcionan los siguientes ejemplos de invocación de REST:

Pasar valores booleanos a un proceso

El siguiente ejemplo de HTML pasa dos Boolean a un proceso de AEM Forms denominado RestTest2. El nombre del método de invocación es invoke y la versión es 1.0. Observe que se utiliza el método Post del HTML.

 <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>

Pasar valores de fecha a un proceso

El siguiente ejemplo de HTML pasa un valor de fecha a un proceso de AEM Forms denominado SOAPEchoService. El nombre del método de invocación es echoCalendar. Observe que el HTML Post método se utiliza.

 <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>

Pasar documentos a un proceso

El siguiente ejemplo de HTML invoca un proceso de AEM Forms denominado MyApplication/EncryptDocument que requiere un documento de PDF. Para obtener información sobre este proceso, consulte Invocar AEM Forms mediante MTOM.

 <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>

Pasar valores de documento y texto a un proceso

El siguiente ejemplo de HTML invoca un proceso de AEM Forms denominado RestTest3 que requiere un documento y dos valores de texto. Observe que se utiliza el método Post del HTML.

 <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>

Paso de valores de enumeración a un proceso

El siguiente ejemplo de HTML invoca un proceso de AEM Forms denominado SOAPEchoService que requiere un valor de enumeración. Observe que se utiliza el método Post del HTML.

 <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>

Invocar el proceso MyApplication/EncryptDocument mediante REST

Puede invocar un proceso de corta duración de AEM Forms denominado MyApplication/EncryptDocument mediante REST.

Cuando se invoca este proceso, realiza las siguientes acciones:

Invocar el proceso MyApplication/EncryptDocument desde Acrobat

Puede invocar un proceso de Forms desde Acrobat mediante una solicitud REST. Por ejemplo, puede invocar el MyApplication/EncryptDocument proceso. Para invocar un proceso de Forms desde Acrobat, coloque un botón de envío en un archivo XDP dentro de Designer. (Consulte Ayuda de Designer).

Especifique la dirección URL para invocar el proceso en el campo del botón Enviar a URL , como se muestra en la siguiente ilustración.

La dirección URL completa para invocar el proceso es https://hiro-xp:8080/rest/services/MyApplication/EncryptDocument.

Si el proceso requiere un documento de PDF como valor de entrada, asegúrese de enviar el formulario como PDF, como se muestra en la ilustración anterior. Además, para invocar correctamente un proceso, el proceso debe devolver un documento de PDF. De lo contrario, Acrobat no podrá controlar el valor devuelto y se producirá un error. No es necesario especificar el nombre de la variable del proceso de entrada. Por ejemplo, la variable MyApplication/EncryptDocument El proceso tiene una variable de entrada denominada inDoc. No es necesario especificar inDoc, siempre y cuando el formulario se envíe como PDF.

También puede enviar datos de formulario como XML a un proceso de Forms. Para enviar datos XML, asegúrese de que la variable Submit As La lista desplegable especifica XML. Dado que el valor devuelto del proceso debe ser un documento de PDF, el documento de PDF se muestra en Acrobat.