Aufrufen von AEM Forms mithilfe von REST-Anforderungen invoking-aem-forms-using-rest-requests

Die Beispiele in diesem Dokument gelten nur für eine AEM Forms on JEE-Umgebung.

In Workbench erstellte Prozesse können so konfiguriert werden, dass sie über Representational State Transfer-Anforderungen (REST) aufgerufen werden können. REST-Anfragen werden von HTML-Seiten gesendet. Das heißt, Sie können mithilfe einer REST-Anforderung einen Forms-Prozess direkt von einer Web-Seite aufrufen. Sie können beispielsweise eine neue Instanz einer Web-Seite öffnen. Anschließend können Sie einen Forms-Prozess aufrufen und ein gerendertes PDF-Dokument mit Daten laden, die in einer HTTP-POST-Anfrage gesendet wurden.

Es gibt zwei Arten von HTML-Clients. Der erste HTML-Client ist ein AJAX Client, der in JavaScript geschrieben ist. Der zweite Client ist ein HTML-Formular mit einer Senden-Schaltfläche. Ein HTML-basiertes Client-Programm ist nicht der einzige mögliche REST-Client. Jedes Client-Programm, das HTTP-Anforderungen unterstützt, kann einen Service mithilfe eines REST-Aufrufs aufrufen. Beispielsweise können Sie einen Service aufrufen, indem Sie einen REST-Aufruf aus einem PDF-Formular verwenden. (Siehe Aufrufen des Prozesses MyApplication/EncryptDocument aus Acrobat.)

Bei der Verwendung von REST-Anfragen wird empfohlen, Forms-Services nicht direkt aufzurufen. Rufen Sie stattdessen Prozesse auf, die in Workbench erstellt wurden. Verwenden Sie beim Erstellen eines Prozesses, der für den REST-Aufruf vorgesehen ist, einen programmgesteuerten Startpunkt. In diesem Fall wird der REST-Endpunkt automatisch hinzugefügt. Informationen zum Erstellen von Prozessen in Workbench finden Sie unter Verwenden von Workbench.

Wenn Sie einen Service mithilfe von REST aufrufen, werden Sie zur Angabe eines Benutzernamens und Kennworts für AEM Forms aufgefordert. Wenn Sie jedoch keinen Benutzernamen und kein Kennwort angeben möchten, können Sie für den Service die Sicherheit deaktivieren.

Um einen Forms-Service (ein Prozess wird zu einem Service, wenn der Prozess aktiviert wird) mithilfe von REST aufzurufen, konfigurieren Sie einen REST-Endpunkt. (Siehe „Verwalten von Endpunkten“ in der Administration-Hilfe.)

Nachdem ein REST-Endpunkt konfiguriert wurde, können Sie einen Forms-Service mithilfe einer HTTP-GET-Methode oder einer POST-Methode aufrufen.

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

Der obligatorische Wert für ServiceName ist der Name des aufzurufenden Forms-Services. Der optionale Wert für OperationName ist der Name des Service-Vorgangs. Wenn dieser Wert nicht angegeben ist, wird für diesen Namen standardmäßig invoke verwendet, der Name des Vorgangs, der den Prozess startet. Der optionale Wert von ServiceVersion ist die Version im Format „X.Y“. Wenn dieser Wert nicht angegeben ist, wird die neueste Version verwendet. Die Wert von enctype kann auch application/x-www-form-urlencoded sein.

Unterstützte Datentypen supported-data-types

Beim Aufrufen von AEM Forms-Services mithilfe von REST-Anfragen werden die folgenden Datentypen unterstützt:

Asynchrone Aufrufe asynchronous-invocations

Einige AEM Forms-Services, z. B. am Menschen orientierte langlebige Prozesse, benötigen viel Zeit, bis sie abgeschlossen sind. Diese Services können asynchron, auf nicht blockierende Weise aufgerufen werden. (Siehe An Menschen orientierte langlebige Prozesse aufrufen.)

Ein AEM Forms-Service kann auf asynchrone Weise aufgerufen werden, indem in der Aufruf-URL services durch async_invoke ersetzt wird, wie im folgenden Beispiel gezeigt.

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

Diese URL gibt den Bezeichnerwert (im Format „text/plain“) des für diesen Aufruf verantwortlichen Auftrags zurück.

Mithilfe einer Aufruf-URL, bei der services durch async_status ersetzt ist, kann der Status des asynchronen Aufrufs abgerufen werden. Die URL muss einen job_id-Parameter enthalten, der den Kennungswert des mit diesem Aufruf verknüpften Auftrags angibt. Beispiel:

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

Diese URL gibt einen ganzzahligen Wert (im „text/plain“-Format) zurück, der den Auftragsstatus gemäß der Spezifikation von Job Manager codiert (beispielsweise bedeutet 2 „wird ausgeführt“, 3 bedeutet „abgeschlossen“ und 4 bedeutet „fehlgeschlagen“).

Wenn der Auftrag abgeschlossen ist, gibt die URL das gleiche Ergebnis zurück, wie wenn der Service synchron aufgerufen worden wäre.

Sobald der Auftrag abgeschlossen ist und das Ergebnis abgerufen wurde, kann der Auftrag mithilfe einer Aufruf-URL, bei der services durch async_dispose ersetzt wurde, verworfen werden. Die URL sollte auch einen job_id-Parameter enthalten, der den Kennungswert des Auftrags angibt. Beispiel:

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

Wenn das Verwerfen des Auftrags gelungen ist, gibt diese URL eine leere Nachricht zurück.

Fehlerberichterstattung error-reporting

Wenn eine synchrone oder asynchrone Aufrufanforderung aufgrund einer auf dem Server ausgelösten Ausnahme nicht abgeschlossen werden kann, wird die Ausnahme als Teil der HTTP-Antwortnachricht gemeldet. Wenn die Aufruf-URL (oder die async_result-URL bei einem asynchronen Aufruf) kein Suffix „.xml“ aufweist, gibt der REST-Provider den HTTP-Code 500 Internal Server Error gefolgt von einer Ausnahmemeldung zurück.

Wenn die Aufruf-URL (oder die async_result-URL bei einem asynchronen Aufruf) das Suffix „.xml“ aufweist, gibt der REST-Provider den HTTP-Code 200 OK gefolgt von einem XML-Dokument zurück, das die Ausnahme im nachfolgend angegebenen Format beschreibt.

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

Die DSCError-Element ist optional und nur vorhanden, wenn die Ausnahme eine Instanz von com.adobe.idp.dsc.DSCException ist.

Sicherheit und Authentifizierung security-and-authentication

Um REST-Aufrufe bereitzustellen, deren Übermittlung sicher ist, können AEM Forms-Admins das HTTPS-Protokoll auf dem J2EE-Anwendungs-Server aktivieren, der als Host für AEM Forms dient. Diese Konfiguration ist spezifisch für den J2EE-Anwendungs-Server. Sie ist kein Bestandteil der Formular-Server-Konfiguration.

AEM Forms-Services, die REST-Aufrufe unterstützen aem-forms-services-that-support-rest-invocation

Es wird zwar empfohlen, Prozesse, die mit Workbench erstellt wurden, und nicht direkt Services aufzurufen, dennoch gibt es einige AEM Forms-Services, die REST-Aufrufe unterstützen. Es wird empfohlen, einen Prozess im Gegensatz zu einem Service direkt aufzurufen, da es effizienter ist, einen Prozess aufzurufen. Betrachten Sie das folgende Szenario. Angenommen, Sie möchten aus einem REST-Client eine Richtlinie erstellen. Das heißt, Sie möchten, dass der REST-Client Werte wie den Richtliniennamen und die Offline-Nutzungsdauer definiert.

Um eine Richtlinie zu erstellen, müssen Sie komplexe Datentypen definieren, z. B. ein PolicyEntry-Objekt. Ein PolicyEntry-Objekt definiert Attribute wie Berechtigungen, die mit der Richtlinie verknüpft sind. (Siehe Erstellen von Richtlinien.)

Anstatt eine REST-Anfrage zu senden, um eine Richtlinie zu erstellen (was das Definieren komplexer Datentypen wie eines PolicyEntry-Objekts beinhalten würde), erstellen Sie einen Prozess, der eine Richtlinie mithilfe von Workbench erstellt. Definieren Sie den Prozess so, dass er primitive Eingabevariablen akzeptiert, z. B. einen Zeichenfolgenwert, der den Prozessnamen definiert, oder eine Ganzzahl, die die Offline-Nutzungsdauer definiert.

Auf diese Weise müssen Sie keine REST-Aufrufanforderung erstellen, die komplexe Datentypen enthält, die für den Vorgang erforderlich sind. Der Prozess definiert die komplexen Datentypen und alles, was Sie vom REST-Client aus tun müssen, ist, den Prozess aufzurufen und primitive Datentypen zu übergeben. Informationen zum Aufrufen eines Prozesses mithilfe von REST finden Sie unter Aufrufen des Prozesses MyApplication/EncryptDocument mithilfe von REST.

In der folgenden Liste sind die AEM Forms-Services aufgeführt, die einen direkten REST-Aufruf unterstützen.

Beispiele für REST-Aufrufe rest-invocation-examples

Die folgenden Beispiele für REST-Aufrufe werden bereitgestellt:

Übergeben von booleschen Werten an einen Prozess

Im folgenden HTML-Beispiel werden zwei Boolean-Werte an einen AEM Forms-Prozess namens RestTest2 übergeben. Der Name der Aufrufmethode lautet invoke, und die Version ist 1.0. Beachten Sie, dass die HTML-Post-Methode verwendet wird.

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

Übergeben von Datumswerten an einen Prozess

Im folgenden HTML-Beispiel wird ein Datumswert an einen AEM Forms-Prozess namens SOAPEchoService übergeben. Der Name der Aufrufmethode lautet echoCalendar. Beachten Sie, dass die HTML-Post-Methode verwendet wird.

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

Übergeben von Dokumenten an einen Prozess

Im folgenden HTML-Beispiel wird ein AEM Forms-Prozess namens MyApplication/EncryptDocument aufgerufen, für den ein PDF-Dokument erforderlich ist. Weitere Informationen zu diesem Prozess finden Sie unter Aufrufen von AEM Forms mithilfe von 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>

Übergeben von Dokument- und Textwerten an einen Prozess

Im folgenden HTML-Beispiel wird ein AEM Forms-Prozess namens RestTest3 aufgerufen, für den ein Dokument und zwei Textwerte erforderlich sind. Beachten Sie, dass die HTML-Post-Methode verwendet wird.

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

Übergeben von Auflistungswerten an einen Prozess

Im folgenden HTML-Beispiel wird ein AEM Forms-Prozess mit dem Namen SOAPEchoService aufgerufen, für den ein Auflistungswert erforderlich ist. Beachten Sie, dass die HTML-Post-Methode verwendet wird.

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

Aufrufen des Prozesses MyApplication/EncryptDocument mithilfe von REST

Sie können einen kurzlebigen AEM Forms-Prozess namens MyApplication/EncryptDocument mithilfe von REST aufrufen.

Wenn dieser Prozess aufgerufen wird, führt er die folgenden Aktionen aus:

Aufrufen des Prozesses MyApplication/EncryptDocument aus Acrobat

Sie können einen Forms-Prozess über Acrobat mithilfe einer REST-Anfrage aufrufen. Sie können beispielsweise den Prozess MyApplication/EncryptDocument aufrufen. Um einen Forms-Prozess aus Acrobat aufzurufen, platzieren Sie eine Senden-Schaltfläche in einer XDP-Datei in Designer. (Weitere Informationen finden Sie in der Designer-Hilfe.)

Geben Sie im Feld Absenden an URL der Schaltfläche die URL zum Aufrufen des Prozesses an, wie in der folgenden Abbildung gezeigt.

Die vollständige URL zum Aufrufen des Prozesses lautet https://hiro-xp:8080/rest/services/MyApplication/EncryptDocument.

Wenn für den Vorgang ein PDF-Dokument als Eingabewert erforderlich ist, stellen Sie sicher, dass Sie das Formular als PDF übermitteln, wie in der vorherigen Abbildung dargestellt. Um einen Prozess erfolgreich aufzurufen, muss der Prozess außerdem ein PDF-Dokument zurückgeben. Andernfalls kann Acrobat den Rückgabewert nicht verarbeiten und es tritt ein Fehler auf. Sie brauchen den Namen der Eingabeprozessvariablen nicht anzugeben. Der Prozess MyApplication/EncryptDocument hat beispielsweise eine Eingabevariable mit dem Namen inDoc. Sie brauchen inDoc nicht anzugeben, solange das Formular als PDF übermittelt wird.

Sie können Formulardaten auch als XML an einen Forms-Prozess übermitteln. Um XML-Daten zu übermitteln, stellen Sie sicher, dass in der Dropdown-Liste Submit As XML angegeben ist. Da der Rückgabewert des Prozesses ein PDF-Dokument sein muss, wird das PDF-Dokument in Acrobat angezeigt.