RESTful サービス アクション
RESTful Web サービスを使用して、フォームを外部アプリケーションと結合します。RESTful Web サービスには、Open API 定義と非 Open API REST サービスを含めることができます。フォームに Open API 定義を持つ REST サービスを使用して、メソッド/パラメータを確認し、サービスを正常に実行できます。
TotalAgility は、単純なタイプの RESTful Web サービスのみをサポートします。したがって、複雑なデータ構造では使用しないでください。
-
フォーム モデリング バーで、[アクション] をクリックし、[新規] をクリックします。
[新しいアクション] ダイアログ ボックスが表示されます。
- [タイプ] リストで、[RESTful サービス] を選択します。
- デフォルトの [名前] (RESTfulService1) を意味のある名前に変更します。
- この項目は任意です。アクションの [説明] を入力します。
- この項目は任意です。[複数言語] を選択して、言語ごとに固有のアクションを個別に構成します。複数言語の設定アクションを参照してください。
-
Web サービスには、Open API 定義と非 Open API REST サービスを持つすべての REST サービス定義が一覧表示されます。[Web サービス] リストで、次のいずれかを実行します。
アクション用に事前構成された RESTful Web サービス参照を選択します。
-
選択した RESTful サービスに応じて、事前構成された [ベース URL] が表示されます。また、RESTful サービスで定義されたカスタム ヘッダーが [カスタム ヘッダー] の下に表示されます。
ベース URL パラメータをコピーして別の RESTful サービスのベース URL パラメータに貼り付けると、ベース URL パラメータを再利用できます。
Web サービス レファレンスをホワイトリストに登録できます。システム設定で「すべて許可」が選択されていない場合は、ホワイトリストに登録された Web サービス レファレンスのみを使用できます。サーバー URL とデータベース接続文字列の構成を参照してください。 -
[URL パラメータ] ルール エディタを右クリックして、文字列型の単一変数 (フォーム変数またはグローバル変数) またはフォーム フィールドを選択するか、静的な値、変数、およびフォーム フィールドを組み合わせて URL を動的に定義します。
URL パラメータは、戻り値に影響する、文字列型のオプション パラメータです。
-
データを取得、削除、挿入、または更新するための RESTful サービス アクションを構成します。
事前構成された RESTful Open API Web サービスを選択します。「Web サービス参照の作成」を参照してください。
-
[パラメータ] の [構成] リンクが使用可能になります。[構成] をクリックします。
[RESTful サービス アクションの構成] に、RESTful サービスの詳細が表示されます。
-
選択した RESTful サービスの統合に事前設定された [ベース URL] が表示されます。
-
[クラス] リストでクラスを選択します。
選択したクラスで使用可能なメソッドが [メソッド] リストに表示されます。
-
[メソッド] を選択して、インライン値/フォーム コントロール/変数 (フォームまたはグローバル) をパラメータにマッピング可能なパラメータとパラメータ タイプを表示します。
- [OK] をクリックします。
- また、RESTful サービスで定義されたカスタム ヘッダーが [カスタム ヘッダー] の下に表示されます。
-
- RESTful サービス アクションを構成して、次のような操作を実行できます。
- エラーが見つかった場合にジョブの一時停止を許可するには、[エラーで停止] を選択します。(デフォルト: オフ。エラーが発生してもジョブを完了することを意味します。)
-
[追加] をクリックします。
新たに作成されたアクションがテーブルに追加されます。
-
このアクションをトリガーするため、アクションにコントロールを関連付けます。フォーム コントロール イベント用のアクションの構成を参照してください。または、フォーム イベントに対してこのアクションを呼び出すには、アクションをフォームに関連付けます。フォームへのアクションの関連付けを参照してください。
このアクションがトリガーされると、RESTful Web サービスが実行され、出力と応答ステータスが構成したとおりに処理されます。
データを取得するための RESTful サービス アクションの構成
RESTful サービス アクションを構成してデータを取得できます。
- [メソッド] リストで、[GET] を選択してデータを取得します。
- 情報を取得する要求により、JSON または XML 形式のいずれかで応答が返されます。応答を XML 形式または JSON 形式のどちらで返すかを指定するには、[タイプ] を [XML] あるいは [JSON] として選択します。(デフォルト: XML)
- Web サービス参照の作成時に定義したカスタム ヘッダーとそのデフォルト値は、[カスタム ヘッダー] の下に表示されます。カスタム ヘッダーのデフォルト値を編集するには、行をダブルクリックするか、カスタム ヘッダーを選択して、 をクリックします。次に、動的変数を選択するか、 をクリックして静的な値を入力し、[OK] をクリックします。
-
RESTful サービスから返されるステータス コードに基づいて Web サービスからの応答を処理するには、[応答] に対して次の操作を実行します。
-
をクリックします。
[応答] ダイアログ ボックスが表示されます。
-
[最初の HTTP ステータス コード] と [最後の HTTP ステータス コード] でステータス コードの範囲を指定します。
-
範囲は包括的です。たとえば、100 ～ 199 の範囲により、100 ～ 199 のステータス コードに対する応答が処理されます。
-
範囲を 1 つの数値として定義することで、特定のコードの応答マッピングを定義できます。たとえば、200 ～ 200 の範囲により、前述の範囲内のステータス コードに対する応答が処理されます。
-
- [説明] ボックスに、範囲などの説明を入力します。
-
RESTful サービスから受信した応答をフォーム変数、フォーム コントロール、グローバル変数のいずれに保存するかを指定するには、[応答タイプ] リストで次のいずれかを選択します。
[変数] (デフォルト) 出力全体を、[値] リストのフォーム変数、フォーム コントロール、またはグローバル変数の形式で単一の変数にマッピングします。データ オブジェクト変数を使用して、サービスからの応答を受信し、それを変数に格納できます。 応答が JSON の場合は、データ オブジェクト変数をマッピングして戻り値を保持できます。
アクションを実行すると、RESTful サービスから返された JSON 文字列を使用して、基になるデータ モデルに基づいて変数にデータが入力されます。
データ オブジェクト変数を使用しているフォームをデバッグする場合、表示される値は JSON 文字列となります。
式 次の操作を実行します。
-
をクリックします。
-
式から抽出する要素を定義するには、正しい [パス] を指定します。
-
応答が XML の場合は xPath を使用します。
-
応答が JSON の場合は JSONPath を使用します。
-
-
[値] リストで、フォーム変数、フォーム コントロール、またはグローバル変数を選択します。
-
[追加] をクリックします。
-
-
をクリックします。
-
RESTful サービスによって返される応答ヘッダーにアクセスし、応答ヘッダーのリストをキーまたは値のペアとして定義するには、[応答ヘッダー] に対して次の操作を実行します。
- をクリックします。
- ヘッダーの [名前] を入力します。
- [値] リストで、戻り値を保持するフォーム変数、フォーム コントロール、またはグローバル変数を選択します。
- [追加] をクリックします。
- [ステータス コード] を表示するには、グローバル変数、フォーム変数、またはフォーム コントロールを選択します。エラーが検出された場合でもアクションは完了し、選択したステータス コードが実行時に表示されます。これは、ユーザーがエラーを手動で処理するのに役立ちます。
データを挿入するための RESTful サービス アクションの構成
RESTful サービス アクションを構成してデータを挿入できます。
- [メソッド] リストで、[POST] を選択してデータを挿入します。
-
[XML] に [タイプ] または [JSON] を選択して、応答を XML 形式または JSON 形式のどちらで返すかを指定します。(デフォルト: XML)
[リクエスト] ルール エディタを右クリックして、プロセス、サーバー変数、またはフォーム コントロールを選択します。
- Web サービス参照の作成時に定義したカスタム ヘッダーとそのデフォルト値は、[カスタム ヘッダー] の下に表示されます。カスタム ヘッダーのデフォルト値を編集するには、行をダブルクリックするか、カスタム ヘッダーを選択して、 をクリックします。次に、動的変数を選択するか、 をクリックして静的な値を入力し、[OK] をクリックします。
-
RESTful サービスから返されるステータス コードに基づいて Web サービスからの応答を処理するには、[応答] に対して次の操作を実行します。
-
をクリックします。
[応答] ダイアログ ボックスが表示されます。
-
[最初の HTTP ステータス コード] と [最後の HTTP ステータス コード] でステータス コードの範囲を指定します。
-
範囲は包括的です。たとえば、100 ～ 199 の範囲により、100 ～ 199 のステータス コードに対する応答が処理されます。
-
範囲を 1 つの数値として定義することで、特定のコードの応答マッピングを定義できます。たとえば、200 ～ 200 の範囲により、前述の範囲内のステータス コードに対する応答が処理されます。
-
- [説明] ボックスに、範囲などの説明を入力します。
-
RESTful サービスから受信した応答をフォーム変数、フォーム コントロール、グローバル変数のいずれに保存するかを指定するには、[応答タイプ] リストで次のいずれかを選択します。
[変数] (デフォルト) 出力全体を、[値] リストのフォーム変数、フォーム コントロール、またはグローバル変数の形式で単一の変数にマッピングします。データ オブジェクト変数を使用して、サービスからの応答を受信し、それを変数に格納できます。 応答が JSON の場合は、データ オブジェクト変数をマッピングして戻り値を保持できます。
アクションを実行すると、RESTful サービスから返された JSON 文字列を使用して、基になるデータ モデルに基づいて変数にデータが入力されます。
データ オブジェクト変数を使用しているフォームをデバッグする場合、表示される値は JSON 文字列となります。
式 次の操作を実行します。
-
をクリックします。
-
式から抽出する要素を定義するには、正しい [パス] を指定します。
-
応答が XML の場合は xPath を使用します。
-
応答が JSON の場合は JSONPath を使用します。
-
-
[値] リストで、フォーム変数、フォーム コントロール、またはグローバル変数を選択します。
-
[追加] をクリックします。
-
-
をクリックします。
-
RESTful サービスによって返される応答ヘッダーにアクセスし、応答ヘッダーのリストをキーまたは値のペアとして定義するには、[応答ヘッダー] に対して次の操作を実行します。
- をクリックします。
- ヘッダーの [名前] を入力します。
- [値] リストで、戻り値を保持するフォーム変数、フォーム コントロール、またはグローバル変数を選択します。
- [追加] をクリックします。
- [ステータス コード] を表示するには、グローバル変数、フォーム変数、またはフォーム コントロールを選択します。エラーが検出された場合でもアクションは完了し、選択したステータス コードが実行時に表示されます。これは、ユーザーがエラーを手動で処理するのに役立ちます。
データを更新するための RESTful サービス アクションの構成
RESTful サービス アクションを構成してデータを更新できます。
- [メソッド] リストで、[PUT] を選択します。
- 手順 2 からは、「データを挿入するための RESTful サービス アクションの構成」と同じ手順を実行します。
データを削除するための RESTful サービス アクションの構成
RESTful サービス アクションを構成してデータを削除できます。
- [メソッド] リストで、[DELETE] を選択します。
- 手順 2 からは、「データを取得するための RESTful サービス アクションの構成」と同じ手順を実行します。