REST リクエストを使用した AEM Forms の呼び出し invoking-aem-forms-using-rest-requests

このドキュメントのサンプルと例は、JEE 環境の AEM Forms のみを対象としています。

Representational State Transfer（REST）リクエストで呼び出せるように、Workbench で作成したプロセスを設定できます。REST リクエストは HTML ページから送信されます。つまり、REST リクエストを使用して、Web ページから直接 Forms プロセスを呼び出すことができます。例えば、web ページの新しいインスタンスを開くことができます。次に、Forms プロセスを呼び出し、HTTP POST リクエストで送信されたデータを含む、レンダリングされた PDF ドキュメントを読み込むことができます。

2 種類のHTML クライアントが存在します。最初の HTML クライアントは、JavaScript で記述された AJAX クライアントです。2 つ目のクライアントは、送信ボタンを含む HTML フォームです。HTML ベースのクライアントアプリケーションは、REST クライアントとして使用できる唯一のクライアントではありません。HTTP リクエストをサポートするクライアントアプリケーションは、REST 呼び出しを使用してサービスを呼び出すことができます。例えば、PDF フォームからの REST 呼び出しを使用して、サービスを呼び出すことができます。（Acrobat からの MyApplication／EncryptDocument プロセスの呼び出しを参照。）

REST リクエストを使用する場合は、Forms サービスを直接呼び出さないことをお勧めします。代わりに、Workbench で作成されたプロセスを呼び出します。REST 呼び出し用のプロセスを作成する場合は、プログラム的なスタートポイントを使用します。この場合、REST エンドポイントは自動的に追加されます。Workbench でのプロセスの作成について詳しくは、Workbench の使用を参照してください。

REST を使用してサービスを呼び出すと、AEM Forms のユーザー名とパスワードの入力を求められます。ただし、ユーザー名とパスワードを指定しない場合は、Service Security を無効にできます。

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 値は、呼び出す Forms サービスの名前です。オプションの OperationName 値はサービスの操作の名前です。この値を指定しない場合、この名前はデフォルトで invoke（プロセスを開始する操作の名前）になります。オプションの ServiceVersion の値は、X.Y 形式でエンコードされたバージョンです。この値を指定しない場合は、最新のバージョンが使用されます。enctype 値は application/x-www-form-urlencoded にすることもできます。

サポートされるデータタイプ supported-data-types

REST リクエストを使用してAEM Forms サービスを呼び出す場合、次のデータタイプがサポートされます。

非同期呼び出し asynchronous-invocations

人間中心の長期間有効なプロセスのように、一部の AEM Forms サービスの完了には長い時間が必要です。これらのサービスは、非ブロッキング方式で非同期で呼び出すことができます。（人間中心の長期間有効なプロセスの呼び出しを参照。）

次の例で示されるように、AEM Forms サービスは、URL の呼び出しで services を async_invoke に置き換えることで非同期に呼び出すことができます。

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

この URL は、この呼び出しを行うジョブの識別子の値（「text/plain」形式）を返します。

非同期呼び出しのステータスは、 URLの呼び出しを使用して services を async_status に置き換えることで取得できます。URL は、この呼び出しに関連付けられたジョブの識別子の値を指定する job_id パラメーターを含む必要があります。次に例を示します。

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

この URL は、ジョブマネージャーの仕様に従ってジョブステータスをエンコードする整数値（「text/plain」形式）を返します（例えば、2 は実行、3 は完了、4 は失敗といった意味）。

ジョブが完了した場合、URL は、サービスが同期的に呼び出された場合と同じ結果を返します。

ジョブが完了し、結果が取得されたら、 services を async_dispose で置き換えた呼び出し URL を使用してジョブを破棄できます。URL には、ジョブの識別子の値を指定するパラメーター job_id も含まれます。次に例を示します。

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

ジョブが正常に破棄された場合、この URL は空のメッセージを返します。

エラーレポート error-reporting

サーバーで例外が発生し、同期または非同期の呼び出し要求を完了できない場合、HTTP 応答メッセージの一部として例外がレポートされます。呼び出し URL（または非同期呼び出しの async_result URL の場合）に.xml サフィックスが付かない場合、REST プロバイダーは 500 Internal Server Error HTTP コードを返し、続いて例外メッセージを返します。

呼び出し URL（または非同期呼び出しの async_result URL の場合）に.xml サフィックスが付いている場合、REST プロバイダーは 200 OK HTTP コードを返し、続いて次の形式の例外を説明する 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

REST 呼び出しに安全なトランスポートを提供するために、AEM Forms 管理者は、AEM Forms をホストする J2EE アプリケーションサーバーで HTTPS プロトコルを有効にすることができます。この設定は、J2EE アプリケーションサーバーに固有で、Forms サーバー設定には含まれていません。

REST 呼び出しをサポートする AEM Forms サービス aem-forms-services-that-support-rest-invocation

サービスを直接呼び出すのではなく、Workbench を使用して作成したプロセスを呼び出すことをお勧めしますが、REST 呼び出しをサポートする AEM Forms サービスもいくつかあります。サービスを直接呼び出すよりも、プロセスを呼び出すことをお勧めする理由は、より効率的なためです。次のシナリオについて考えてみます。REST クライアントからポリシーを作成するとします。つまり、ポリシー名、オフラインリース期間などの値を、REST クライアントで定義する必要があります。

ポリシーを作成するには、PolicyEntry オブジェクトのような複雑なデータタイプを定義する必要があります。PolicyEntry オブジェクトは、ポリシーに関連付けられた権限などの属性を定義します。（ポリシーの作成を参照してください。）

ポリシーを作成するための REST リクエストを送信するのではなく（これには PolicyEntry オブジェクトのような複雑なデータタイプを定義することも含まれます）、ポリシーを作成するプロセスを Workbench を使用して作成してください。プロセス名を定義する文字列値や、オフラインリース期間を定義する整数値など、プリミティブな入力変数を受け入れるプロセスを定義します。

これにより、操作で必要になる複雑なデータタイプを含む REST 呼び出しリクエストを作成する必要はなくなります。複雑なデータタイプを定義するのはプロセスであり、REST クライアントから行うのは、プロセスを呼び出してプリミティブなデータタイプを渡すことだけです。REST を使用したプロセスの呼び出しについて詳しくは、REST を使用した MyApplication/EncryptDocument プロセスの呼び出しを参照してください。

REST の直接呼び出しをサポートする AEM Forms サービスのリストは、次のとおりです。

REST 呼び出しの例 rest-invocation-examples

REST 呼び出しの例は、次のとおりです。

プロセスにブール値を渡す

次の HTML の例では、RestTest2 という名前の AEM Forms のプロセスに、2 つの Boolean 値を渡します。呼び出しメソッドの名前は 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 の例では、SOAPEchoService という名前の AEM Forms のプロセスに日付値を渡します。呼び出しメソッドの名前は 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 の例では、PDF ドキュメントを必要とする MyApplication/EncryptDocument という名前の AEM Forms のプロセスを呼び出します。このプロセスについて詳しくは、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 の例では、1 つのドキュメントと 2 つのテキスト値を必要とする、RestTest3 という名前の AEM Forms のプロセスを呼び出します。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 の例では、列挙値を必要とする SOAPEchoService という名前の AEM Forms のプロセスを呼び出します。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 プロセスの呼び出し

REST を使用すると、MyApplication/EncryptDocument という名前の短時間のみ有効な AEM Forms のプロセスを呼び出すことができます。

このプロセスを呼び出すと、次のアクションが実行されます。

Acrobat からの MyApplication/EncryptDocument プロセスの呼び出し

REST リクエストを使用して、Acrobat から Forms プロセスを呼び出すことができます。例えば、MyApplication/EncryptDocument プロセスを呼び出すことができます。Acrobat から Forms プロセスを呼び出すには、Designer 内の XDP ファイルに送信ボタンを配置します。（「Designer ヘルプ」を参照。）

次の図に示すように、ボタンの​ 送信先 URL フィールド内でプロセスを呼び出す URL を指定します。

プロセスを呼び出すための完全な URL は https://hiro-xp:8080/rest/services/MyApplication/EncryptDocument です。

プロセスで PDF ドキュメントを入力値として必要とする場合は、前の図に示すように、必ず PDF としてフォームを送信してください。また、プロセスを正常に呼び出すには、プロセスが PDF ドキュメントを返す必要があります。そうしないと、Acrobat は戻り値を処理できず、エラーが発生します。入力プロセス変数の名前を指定する必要はありません。例えば、MyApplication/EncryptDocument プロセスには、inDoc という入力変数があります。フォームが PDF として送信されている限り、inDoc を指定する必要はありません。

また、フォームデータを XML としても Forms プロセスに送信できます。XML データを送信する場合は Submit As ドロップダウンが XML を指定していることを確認してください。プロセスの戻り値は PDF ドキュメントである必要があるので、PDF ドキュメントは Acrobat に表示されます。