Unterstützte Datentypen
Beim Aufrufen von AEM Forms-Services mithilfe von REST-Anfragen werden die folgenden Datentypen unterstützt:
-
Primitive Java-Datentypen, z. B. Zeichenfolgen und Ganzzahlen
-
Datentyp
com.adobe.idp.Document
-
XML-Datentypen wie
org.w3c.Document
undorg.w3c.Element
-
Sammlungsobjekte wie
java.util.List
undjava.util.Map
Diese Datentypen werden gemeinhin als Eingabewerte für in Workbench erstellte Prozesse akzeptiert.
Wenn ein Forms-Service mithilfe der HTTP-POST-Methode aufgerufen wird, werden die Argumente innerhalb des Inhalts der HTTP-Anfrage übergeben. Wenn die Signatur des AEM Forms-Service über einen Zeichenfolgeneingabeparameter verfügt, kann der Anfragetext den Textwert des Eingabeparameters enthalten. Wenn die Service-Signatur mehrere Zeichenfolgenparameter definiert, kann die Anfrage der HTTP-Schreibweise
application/x-www-form-urlencoded
folgen, wobei die Namen der Parameter als Feldnamen des Formulars verwendet werden.Wenn ein Forms-Service einen Zeichenfolgenparameter zurückgibt, ist das Ergebnis eine textuelle Darstellung des Ausgabeparameters. Wenn ein Service mehrere Zeichenfolgenparameter zurückgibt, ist das Ergebnis ein XML-Dokument, das die Ausgabeparameter im folgenden Format codiert:
<result> <output-paramater1>output-parameter-value-as-string</output-paramater1> . . . <output-paramaterN>output-parameter-value-as-string</output-paramaterN> </result>
HINWEIS
Der Wertoutput-paramater1
steht für den Namen des Ausgabeparameters.Wenn ein Forms-Service einen Parameter
com.adobe.idp.Document
benötigt, kann der Service nur mithilfe der HTTP-POST-Methode aufgerufen werden. Wenn der Service einen Parametercom.adobe.idp.Document
erfordert, wird der Textkörper der HTTP-Anfrage zum Inhalt des Eingabedokumenobjekts.Wenn für einen AEM Forms-Service mehrere Eingabeparameter erforderlich sind, muss der Textkörper der HTTP-Anfrage eine mehrteilige MIME-Nachricht gemäß RFC 1867 sein. (RFC 1867 ist ein Standard, der von Webbrowsern zum Hochladen von Dateien auf Websites verwendet wird.) Jeder Eingabeparameter muss als separater Teil der mehrteiligen Nachricht gesendet werden und im
multipart/form-data
Format codiert sein. Der Name jedes Teils muss mit dem Namen des Parameters übereinstimmen.Listen und Zuordnungen werden auch als Eingabewerte für AEM Forms-Prozesse verwendet, die in Workbench erstellt wurden. Daher können Sie diese Datentypen bei Verwendung einer REST-Anfrage verwenden. Java-Arrays werden nicht unterstützt, da sie nicht als Eingabewert für einen AEM Forms-Prozess dienen.
Wenn eine Liste als Eingabeparameter dient, kann ein REST-Client diese senden, indem er den Parameter mehrmals (für jedes Element der Liste einmal) angibt. Wenn beispielsweise A eine Liste von Dokumenten ist, muss die Eingabe eine mehrteilige Nachricht sein, die aus mehreren Teilen namens A besteht. In diesem Fall wird jeder Teil mit dem Namen A zu einem Element der Eingabeliste. Wenn B eine Liste von Zeichenfolgen ist, kann die Eingabe eine
application/x-www-form-urlencoded
-Nachricht sein, die aus mehreren Feldern namens B besteht. In diesem Fall wird jedes Formularfeld mit dem Namen B zu einem Element der Eingabeliste.Wenn eine Zuordnung als Eingabeparameter dient und es sich dabei um den einzigen Eingabeparameter der Services handelt, wird jeder Teil/jedes Feld der Eingabemeldung zu einem Schlüssel/Wert-Datensatz der Zuordnung. Der Name jedes Teils/Feldes wird zum Schlüssel des Datensatzes. Der Inhalt jedes Teils/Feldes wird zum Wert des Datensatzes.
Wenn eine Eingabezuordnung nicht der einzige Eingabeparameter für die Dienste ist, kann jeder Schlüssel/Wert-Datensatz, der zu der Zuordnung gehört, mithilfe eines Parameters gesendet werden, dessen Benennung eine Verkettung des Parameternamens und des Datensatzschlüssels ist. Beispielsweise kann eine Eingabezuordnung namens
attributes
mit einer Liste der folgenden Schlüssel/Werte-Paare gesendet werden:attributesColor=red
attributesShape=box
attributesWidth=5
Dies ergibt eine Zuordnung von drei Datensätzen:
Color=red
,Shape=box
undWidth=5
.Die Ausgabeparameter der Listen- und Zuordnungstypen werden Teil der resultierenden XML-Nachricht. Die Ausgabeliste wird in XML als eine Serie von XML-Elementen dargestellt, wobei für jedes Element der Liste genau ein XML-Element vorhanden ist. Jedes Element erhält den gleichen Namen wie der Ausgabelistenparameter. Der Wert jedes XML-Elements repräsentiert eine von zwei verschiedenen Möglichkeiten:
-
eine Textdarstellung des Elements der Liste (wenn die Liste aus Zeichenfolgentypen besteht)
-
eine URL, die auf den Inhalt des Dokuments verweist (wenn die Liste aus
com.adobe.idp.Document
-Objekten besteht)Im folgenden Beispiel wird eine XML-Nachricht von einem Service zurückgegeben, der einen einzigen Ausgabeparameter namens Liste, hier eine Liste von Ganzzahlen, aufweist.
<result> <list>12345</list> . . . <list>67890</list> </result>
Ein ausgegebener Zuordnungsparameter wird in der resultierenden XML-Nachricht als Serie von XML-Elementen mit genau einem Element für jeden Datensatz in der Zuordnung dargestellt. Jedes Element erhält den gleichen Namen wie der Schlüssel des Zuordnungseintrags. Der Wert jedes Elements ist entweder eine Textdarstellung des Zuordnungseintragswerts (wenn die Zuordnung aus Einträgen mit einem Zeichenfolgenwert besteht) oder eine URL, die auf den Inhalt des Dokuments verweist (wenn die Zuordnung aus Einträgen mit dem Wertcom.adobe.idp.Document
besteht). Nachfolgend finden Sie ein Beispiel für eine XML-Nachricht, die von einem Service zurückgegeben wird, der einen einzigen Ausgabeparameter namensmap
aufweist. Dieser Parameterwert ist eine Zuordnung, die aus Datensätzen besteht, die Briefe mitcom.adobe.idp.Document
-Objekten verknüpfen.<result> http://localhost:8080/DocumentManager/docm123/4567 . . . <Z>http://localhost:8080/DocumentManager/docm987/6543</Z> </result>
Asynchrone Aufrufe
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
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
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
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.
- Distiller-Dienst
- Rights Management-Dienst
- GeneratePDF-Service
- Generate3dPDF-Service
- FormDataIntegration