REST ステップ
送信 REST Web サービス要求を外部システムに送信します。
送信 REST Web サービスは、REST アーキテクチャをサポートする Web サービス サーバー上でデータの取得、作成、更新、または削除を可能にするプラットフォーム機能です。
ロールと使用可用性
ワークフロースタジオ アクションステップとして利用可能です。action_designer ロールを持つユーザーは、1 つ以上のアクションステップを使用してカスタムアクションを作成できます。
フィールド
| フィールド | 説明 |
|---|---|
| 接続 | 使用する接続のタイプ。
接続と資格情報の詳細については、「資格情報、接続、およびエイリアスについて」を参照してください。 |
| 接続エイリアス | アクションステップを実行するために使用される接続および資格情報エイリアスレコード。flow_designer または admin ロールを持つユーザーは、関連する接続レコードを作成または選択できます。エイリアスを使用することで、複数の環境でアクションを使用する場合に、複数の認証情報と接続情報プロファイルを構成する必要がなくなります。また、接続情報が変更された場合に、カスタムアクションを更新する必要がありません。接続と資格情報の詳細については、「資格情報、接続、およびエイリアス」を参照してください。 認証情報の値は、データパネルにパスワード (双方向暗号化) データピルとして表示されます。 注: このフィールドは、接続リストから [接続エイリアスを使用] が選択されている場合に利用可能です。 |
| 認証情報エイリアス | アクションステップを実行するために使用される認証情報エイリアス。flow_designer または admin ロールを持つユーザーは、関連する接続レコードを作成または選択できます。エイリアスを使用することで、複数の環境でアクションを使用する場合に、複数の認証情報を構成する必要がなくなります。また、認証情報が変更された場合に、カスタムアクションを更新する必要がありません。接続と資格情報の詳細については、「資格情報、接続、およびエイリアス」を参照してください。 認証情報の値は、データパネルにパスワード (双方向暗号化) データピルとして表示されます。 注: このフィールドは、接続リストから [インラインで接続を定義] が選択されている場合に利用可能です。 |
| MID を使用 | ServiceNow® MID サーバー を使用して REST ステップ を実行するためのオプション。[MID アプリケーション] フィールドと [機能] フィールドを表示するには、このチェックボックスを選択します。 注: システムは、送信 Web サービスのログ記録と同じ方法で MID サーバー経由で送信された REST 要求、応答、およびパラメーターのランタイムデータをログに記録しません。代わりに、フロー実行の詳細でこのデータを表示できます。 |
| ベース URL | REST 要求のベース URL。
|
| REST ステップをテスト | REST ステップをテストするボタン。テストするには、[REST ステップをテスト] ボタンを選択します。必要な入力値を入力して [テストを実行] ボタンを選択します。テストの実行後、ステップの出力またはエラーメッセージがテストウィンドウの [テスト結果] セクションに表示されます。 |
| 接続タイムアウト | システムがホスト接続の成功を待機するミリ秒数。この間にステップが正常に接続されない場合、接続要求はタイムアウトします。[インラインで接続を定義] を選択した場合は、接続のタイムアウト値を入力します。システムのデフォルトの接続タイムアウト値を使用するには、このフィールドを空のままにします。 |
| MID 選択 |
特定の MID サーバーまたは MID クラスターを選択するオプション。
|
| MID アプリケーション | 選択対象となるために MID サーバー がサポートする必要がある機能です。選択した機能をサポートする MID サーバー からアクションステップが実行されます。 このフィールドは、接続リストから [インラインで接続を定義] が選択されていて、[MID を使用] チェックボックスがオンになっており、MID 選択リストから [MID サーバーの自動選択] が選択されている場合に利用可能です。 |
| できること | 選択対象となるために MID サーバー がサポートする必要がある機能です。選択した機能をサポートする MID サーバー からアクションステップが実行されます。 このフィールドは、接続リストから [インラインで接続を定義] が選択されていて、[MID を使用] チェックボックスがオンになっており、MID 選択リストから [MID サーバーの自動選択] が選択されている場合に利用可能です。 |
| MID サーバー | 必要な MID サーバー のデータピル。このフィールドは、接続リストから [インラインで接続を定義] が選択されていて、[MID を使用] チェックボックスがオンになっており、MID 選択リストから [特定の MID サーバー] が選択されている場合に利用可能です。 |
| MID クラスター | 使用する MID クラスターのデータピル。このフィールドは、接続リストから [インラインで接続を定義] が選択されていて、[MID を使用] チェックボックスがオンになっており、MID 選択リストから [特定の MID クラスター] が選択されている場合に利用可能です。 |
| ビルド要求 | 要求を手動で作成したり、OpenAPI 仕様をインポートしたり、REST メッセージをインポートしたりするオプション。
|
| API ソース | 要求の作成に使用する OpenAPI 仕様を選択するオプション、または [OpenAPI をインポート (Import OpenAPI)] を選択して新しい OpenAPI 仕様をインポートするオプション。YAML または JSON への URL を指定するかコンテンツをコピーして貼り付けて、仕様をインポートできます。 注: このフィールドは、[ビルド要求] リストから [OpenAPI 仕様から] を選択した場合に使用可能です。 |
| API 操作 | 操作をリストから選択するオプション。利用可能な操作は、OpenAPI 仕様の [API ソース (API Source)] フィールドで提供されます。 注: このフィールドは、[ビルド要求] リストから [OpenAPI 仕様から] を選択した場合に使用可能です。 |
| REST メッセージ | インポートする REST メッセージの名前。リストから REST メッセージを選択します。 注: このフィールドは、[ビルド要求] リストから [REST メッセージから] を選択した場合に使用可能です。 |
| REST メッセージ関数 | REST メッセージからインポートする関数の名前。使用可能なオプションは、選択した REST メッセージに関連付けられた HTTP メソッドによって決まります。 注: このフィールドは、[ビルド要求] リストから [REST メッセージから] を選択した場合に使用可能です。 |
| REST メッセージをインポート | REST メッセージをインポートするボタン。 注: このフィールドは、[REST メッセージ] フィールドから REST メッセージを選択する際に使用できます。 |
| リソース パス | リソースのパス |
| HTTP メソッド | 要求を処理するために使用する HTTP メソッド
|
| クエリ パラメーター | REST エンドポイントに渡す名前と値のペア。これらのパラメーターは手動で作成することも、入力変数をパラメーター フィールドにドラッグして値を割り当てることもできます。 重複するクエリパラメーター名を含む REST ステップ要求をサポートします。重複するクエリパラメーター名を含む REST 要求を作成すると、ワークフロースタジオ は定義した順序と同じ順序でクエリパラメーターを要求に追加します。 注: OpenAPI 仕様をインポートする際は、システムは仕様にあるするすべてのパラメーターとヘッダーを REST ステップに追加します。最後の REST ステップの値を確認して、要求に送信しないパラメーターを削除します。たとえば API が JSON と XML の両方のコンテンツタイプヘッダーを受け入れた場合は、システムは両方のヘッダーを REST ステップに追加します。応答で受け取るコンテンツタイプに応じて、いずれかのヘッダーを削除します。 |
| ヘッダー | 要求と一緒に送信するヘッダー。手動でヘッダーを作成するか、入力変数をパラメーター フィールドにドラッグして値を割り当てることもできます。 重複する要求ヘッダーを含む REST ステップ要求をサポートします。重複する要求ヘッダーを含む REST 要求を作成すると、ヘッダーが定義した順序と同じ順序で送信されます。 注: OpenAPI 仕様をインポートする際は、システムは仕様にあるするすべてのパラメーターとヘッダーを REST ステップに追加します。最後の REST ステップの値を確認して、要求に送信しないパラメーターを削除します。たとえば API が JSON と XML の両方のコンテンツタイプヘッダーを受け入れた場合は、システムは両方のヘッダーを REST ステップに追加します。応答で受け取るコンテンツタイプに応じて、いずれかのヘッダーを削除します。 |
| 要求タイプ | 要求の形式。次のオプションがあります。
注: このフィールドは、HTTP メソッド が POST、PUT、PATCH、または DELETE の場合に編集できます。 |
| 要求本体 [テキスト] | JSON 形式または XML 形式の要求の本体。フロー実行の詳細には、応答の本体が、埋め込みテキストビューアーへのリンクか、応答が含まれている添付レコードの sys_id のどちらかとして表示されます。 注: このフィールドは、[要求タイプ] リストから [テキスト] を選択した場合に編集可能です。 |
| 添付ファイル | 要求を含む添付ファイルレコード。前のステップでこのレコードを検索または作成して、入力変数として定義できます。スクリプトステップで JSONStreamingBuilder および XMLStreamingBuilder API を使用して作成します。 注: このフィールドは、[要求タイプ] リストから [バイナリ] を選択した場合に使用できます。 |
| 名前、パートタイプ (Part Type)、値 | マルチパート要求のコンテンツ。パートごとに、フィールドを個別に使用するか、またはすべてのパートでインラインスクリプトを使用して、パートの名前、パートタイプ、および値を指定します。マルチパートの値を指定するには、スクリプト切り替えアイコン (
注: これらのフィールドは、[要求タイプ] リストから [マルチパート] を選択した場合に使用できます。 |
| 名前、値 | URL エンコード フォームの要求のコンテンツ。フィールドを個別に使用するか、またはすべてのパートでインラインスクリプトを使用して、URL エンコードされた要求の各パートを名前と値のペアで指定します。フォーム URL エンコードの値のインラインスクリプトを指定するには、スクリプト切り替えアイコン ( ) をクリックしてスクリプトを編集します。インラインスクリプトの詳細については、「Inline scripts」を参照して ください。注: このフィールドは、[要求タイプ] リストから [フォーム URL エンコード] を選択した場合に使用できます。 |
| 再試行ポリシーを有効化 | 再試行ポリシーを有効にするオプション。詳細については、「再試行ポリシー」を参照してください。 |
| エイリアスのデフォルトポリシーを上書き | デフォルトの再試行ポリシーを上書きするオプション。 接続リストの [インラインで接続を定義] が選択されている場合は、このチェックボックスは適用されません。 |
| 再試行ポリシー | 接続エイリアスに関連付けられているデフォルトの再試行ポリシー。エイリアスのデフォルトポリシーを上書きが選択されている場合は、デフォルトの再試行ポリシーを上書きして要件に基づいて別の既存の再試行ポリシーを選択できます。 |
| 添付ファイルとして保存 | 応答をレコードとして添付ファイル [sys_attachment] テーブルに保存するかどうかを指定するオプション。 |
| 添付ファイル名 | REST 応答によって作成される添付ファイルの名前。たとえば、rest-response.txt などです。 注: このフィールドは、 [添付ファイルとして保存] が選択されている場合に使用できます。 |
| 添付ファイルのレコード | 添付ファイルが関連付けられているターゲットレコード。レコードタイプのデータピルである必要があります。たとえば、特定のインシデント レコードなどです。前のステップでこのレコードを検索するか、レコードを入力変数として定義することができます。フロー実行の詳細には、関連するレコードの sys_id が表示されます。 注: このフィールドは、 [添付ファイルとして保存] が選択されている場合に使用できます。 |
) をクリックして独自の URL を入力します。アクションエラー評価
- このステップが失敗した場合
- データタイプ：Choice
次のステップの実行を続行するか、エラー評価に進むオプション。カスタムアクションのエラー条件のステップのステータスコードやメッセージを使用するには、「Action error evaluation」を参照してください。
REST 応答サイズの制限
デフォルトでは、添付ファイルとして保存されていない REST 応答のサイズが 5 MB に制限されます。この制限を超える直接の REST 応答はエラーとなります。応答のサイズを大きくするには、応答を添付ファイルとして保存するか、応答サイズの上限を glide.pf.rest.response_payload_max_size システムプロパティで増やします。このシステムプロパティは最大値として 10240 KB をサポートしており、これにより REST 応答のサイズが 10 MB に制限されます。
REST 応答を解析中
REST API 呼び出しは、応答本文でデータを返します。応答本文のデータは通常、JSON または XML 形式で構造化されます。Script stepを使用して、構造化データを解析して変数にし、アクションまたはフローの他の場所で使用することができます。XML 形式の応答本文を解析するためのXML パーサーステップもあります 。
- 応答本文を確認して、返すデータを選択します。
- スクリプトステップで入力変数と出力変数を作成します。
- REST ステップから応答本文で渡す入力変数を作成します。
- 応答からデータを返す出力変数を作成します。
- データを解析してマッピングするためのスクリプトを作成します。
- スクリプトステップで
JSON.parse()メソッドを使用して、JSON 応答本文を解析します。 - 解析されたデータを出力変数にマッピングします。
- スクリプトステップで
- 出力変数のアクション出力を作成して、データをフローで使用できるようにします。