Chamar o AEM Forms usando solicitações REST invoking-aem-forms-using-rest-requests

Os exemplos e amostras neste documento são somente para AEM Forms no ambiente JEE.

Os processos criados no Workbench podem ser configurados para que você possa chamá-los por meio de solicitações de Transferência de estado representacional (REST). As solicitações REST são enviadas de páginas de HTML. Ou seja, você pode chamar um processo Forms diretamente de uma página da Web usando uma solicitação REST. Por exemplo, você pode abrir uma nova instância de uma página da Web. Em seguida, é possível invocar um processo Forms e carregar um documento PDF renderizado com dados enviados em uma solicitação POST HTTP.

Existem dois tipos de clientes HTML. O primeiro cliente HTML é um cliente AJAX gravado em JavaScript. O segundo cliente é um formulário HTML que contém um botão de envio. Um aplicativo cliente baseado em HTML não é o único cliente REST possível. Qualquer aplicativo cliente que suporte solicitações HTTP pode chamar um serviço usando uma invocação REST. Por exemplo, você pode chamar um serviço usando uma chamada REST de um formulário PDF. (Consulte Chamar o processo MyApplication/EncryptDocument do Acrobat.)

Ao usar solicitações REST, é recomendável não chamar os serviços da Forms diretamente. Em vez disso, chame processos que foram criados no Workbench. Ao criar um processo destinado à invocação REST, use um ponto de partida programático. Nessa situação, o endpoint REST é adicionado automaticamente. Para obter informações sobre como criar processos no Workbench, consulte Uso do Workbench.

Quando você chama um serviço usando REST, é solicitado a fornecer um nome de usuário e senha para formulários AEM. No entanto, se você não quiser especificar um nome de usuário e senha, poderá desativar a segurança do serviço.

Para chamar um serviço Forms (um processo se torna um serviço quando o processo é ativado) usando REST, configure um terminal REST. (Consulte "Gerenciamento de endpoints" em ajuda administrativa.)

Depois que um endpoint REST é configurado, é possível chamar um serviço Forms usando um método GET HTTP ou um método POST.

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

O obrigatório ServiceName value é o nome do serviço Forms a ser chamado. O modelo opcional OperationName value é o nome da operação do serviço. Se esse valor não for especificado, esse nome assumirá como padrão invoke, que é o nome da operação que inicia o processo. O modelo opcional ServiceVersion value é a versão codificada no formato X.Y. Se esse valor não for especificado, a versão mais recente será usada. A variável enctype o valor também pode ser application/x-www-form-urlencoded.

Tipos de dados compatíveis supported-data-types

Os seguintes tipos de dados são suportados ao chamar serviços AEM Forms usando solicitações REST:

Invocações assíncronas asynchronous-invocations

Alguns serviços da AEM Forms, como processos de longa vida centrados no ser humano, exigem um longo tempo para serem concluídos. Esses serviços podem ser chamados de forma assíncrona, sem bloqueio. (Consulte Chamar processos de longa vida centrados no ser humano.)

Um serviço AEM Forms pode ser chamado de forma assíncrona substituindo services com async_invoke no URL de invocação, conforme mostrado no exemplo a seguir.

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

Este URL retorna o valor do identificador (em formato "text/plain") do trabalho responsável por esta invocação.

O status da invocação assíncrona pode ser recuperado usando um URL de invocação com services substituído por async_status. O URL deve conter um job_id parâmetro que especifica o valor do identificador do job associado a esta invocação. Por exemplo:

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

Esse URL retorna um valor inteiro (no formato "texto/simples") codificando o status do job de acordo com a especificação do Gerenciador de Jobs (por exemplo, 2 significa em execução, 3 significa concluído, 4 significa com falha e assim por diante).

Se o trabalho for concluído, o URL retornará o mesmo resultado de se o serviço tiver sido chamado de forma síncrona.

Quando o trabalho for concluído e o resultado for recuperado, o trabalho poderá ser descartado usando um URL de invocação com services é substituída por async_dispose. O URL também deve conter uma job_id parâmetro que especifica o valor do identificador do job. Por exemplo:

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

Se a tarefa for descartada com êxito, esse URL retornará uma mensagem vazia.

Relatório de erros error-reporting

Se uma solicitação de invocação síncrona ou assíncrona não puder ser concluída devido a uma exceção lançada no servidor, a exceção será relatada como parte da mensagem de resposta HTTP. Se o URL de invocação (ou a variável async_result URL se houver uma invocação assíncrona) não tiver um sufixo .xml, o Provedor REST retornará o código HTTP 500 Internal Server Error seguido por uma mensagem de exceção.

Se o URL de invocação (ou a variável async_result URL se houver uma invocação assíncrona) tiver um sufixo .xml, o Provedor REST retornará o código HTTP 200 OKseguido por um documento XML que descreve a exceção no formato a seguir.

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

A variável DSCError elemento é opcional e está presente somente se a exceção for uma instância de com.adobe.idp.dsc.DSCException.

Segurança e autenticação security-and-authentication

Para fornecer invocações REST com um transporte seguro, um administrador de formulários AEM pode ativar o protocolo HTTPS no servidor de aplicativos J2EE que hospeda o AEM Forms. Essa configuração é específica do servidor de aplicativos J2EE; ela não faz parte da configuração do Forms Server.

Serviços AEM Forms que oferecem suporte à invocação REST aem-forms-services-that-support-rest-invocation

Embora seja recomendável chamar processos criados usando o Workbench em vez de serviços diretamente, há alguns serviços da AEM Forms que oferecem suporte à invocação REST. O motivo pelo qual é recomendável chamar um processo em vez de um serviço diretamente é porque é mais eficiente chamar um processo. Considere o cenário a seguir. Suponha que você deseja criar uma política de um cliente REST. Ou seja, você deseja que o cliente REST defina valores como o nome da política, o período de concessão offline.

Para criar uma política, é necessário definir tipos de dados complexos, como um PolicyEntry objeto. A PolicyEntry O objeto define atributos como permissões associadas à política. (Consulte Criação de políticas.)

Em vez de enviar uma solicitação REST para criar uma política (que incluiria a definição de tipos de dados complexos, como um PolicyEntry ), crie um processo que crie uma política usando o Workbench. Defina o processo para aceitar variáveis de entrada primitivas, como um valor de sequência de caracteres que define o nome do processo ou um número inteiro que define o período de concessão offline.

Dessa forma, não é necessário criar uma solicitação de chamada REST que inclua tipos de dados complexos exigidos pela operação. O processo define os tipos de dados complexos e tudo o que você faz do cliente REST é chamar o processo e passar tipos de dados primitivos. Para obter informações sobre como chamar um processo usando REST, consulte Chamar o processo MyApplication/EncryptDocument usando REST.

As listas a seguir especificam os serviços AEM Forms que oferecem suporte à chamada REST direta.

Exemplos de invocação REST rest-invocation-examples

Os seguintes exemplos de invocação REST são fornecidos:

Passagem de valores booleanos a um processo

O exemplo de HTML a seguir passa dois Boolean valores para um processo do AEM Forms chamado RestTest2. O nome do método de invocação é invoke e a versão é a 1.0. Observe que o método HTML Post é usado.

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

Envio de valores de data a um processo

O exemplo de HTML a seguir passa um valor de data para um processo do AEM Forms chamado SOAPEchoService. O nome do método de invocação é echoCalendar. Observe que o HTML Post é usado.

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

Envio de documentos a um processo

O exemplo de HTML a seguir invoca um processo AEM Forms chamado MyApplication/EncryptDocument que requer um documento PDF. Para obter informações sobre esse processo, consulte Chamar o AEM Forms usando 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>

Envio de valores de documento e texto a um processo

O exemplo de HTML a seguir invoca um processo AEM Forms chamado RestTest3 que requer um documento e dois valores de texto. Observe que o método HTML Post é usado.

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

Envio de valores de enumeração a um processo

O exemplo de HTML a seguir invoca um processo AEM Forms chamado SOAPEchoService que requer um valor de enumeração. Observe que o método HTML Post é usado.

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

Chamar o processo MyApplication/EncryptDocument usando REST

Você pode invocar um processo de vida curta do AEM Forms chamado MyApplication/EncryptDocument usando REST.

Quando esse processo é chamado, ele executa as seguintes ações:

Chamar o processo MyApplication/EncryptDocument do Acrobat

Você pode chamar um processo Forms do Acrobat usando uma solicitação REST. Por exemplo, você pode chamar a variável MyApplication/EncryptDocument processo. Para chamar um processo do Forms no Acrobat, coloque um botão de envio em um arquivo XDP no Designer. (Consulte Ajuda do Designer.)

Especifique o URL para chamar o processo no campo Enviar para URL conforme mostrado na ilustração a seguir.

A URL completa para invocar o processo é https://hiro-xp:8080/rest/services/MyApplication/EncryptDocument.

Se o processo exigir um documento PDF como valor de entrada, certifique-se de enviar o formulário como PDF, conforme mostrado na ilustração anterior. Além disso, para invocar um processo com êxito, o processo deve retornar um documento PDF. Caso contrário, o Acrobat não poderá lidar com o valor de retorno e ocorrerá um erro. Não é necessário especificar o nome da variável de processo de entrada. Por exemplo, a variável MyApplication/EncryptDocument o processo tem uma variável de entrada chamada inDoc. Não é necessário especificar inDoc, desde que o formulário seja enviado como PDF.

Também é possível enviar dados de formulário como XML para um processo Forms. Para enviar dados XML, verifique se Submit As lista suspensa especifica XML. Como o valor de retorno do processo deve ser um documento PDF, o documento PDF é exibido no Acrobat.