データストリームアクションおよびページネーション
REST、SOAP、または JDBC 要求を ワークフロースタジオ から API に送信します。この API は、10 MB を超える応答データのストリーム、またはページネーションされた結果を返します。ストリームデータを一連の複合オブジェクト出力に解析して、データピルをフローにある他のアクションで使用します。
利点
データストリーム アクションは以下の利点を提供します。
- 10 MB を超える応答データのストリームを解析してフォーマットします。
- 該当する場合、結果をページネーションする API に複数の要求を自動的に送信します。
- 統合ハブ - インポートで、またデータソースを作成するために使用できます。
- フローデザイナーが、複雑なコーディングや構成を行うことなく、大規模な要求を処理できるようにします。
- フローデザイナーで次のことを実行できます： では、データストリーム内の各オブジェクトを For each フローロジックを使用して処理します。たとえば、サードパーティのサイトからドキュメントデータをインポートする データストリーム アクションを作成できます。アクションをフローに追加すると、ワークフロースタジオ ではアクションが For each フローロジックブロックに自動で追加されます。これにより、フローデザイナーが ServiceNow のレコードをデータストリームの各オブジェクトに対して簡単に作成できるようになります。「フロー内での データストリーム アクションの使用」を参照してください。
- フローデザイナーが、同じデータソースを複数の方法で使用して、複数のフローで データストリーム アクションを再利用できるようにします。
データストリームアクションの実行
データストリーム アクションを実行するには、2 つの方法があります。
- フローから
- ユーザーは次のことを実行できます： では、データストリーム内の各オブジェクトを For each フローロジックを使用して処理します。たとえば、サードパーティのサイトからドキュメントデータをインポートする データストリーム アクションを作成できます。アクションをフローに追加すると、ワークフロースタジオ ではアクションが For each フローロジックブロックに自動で追加されます。これにより、フローデザイナーが ServiceNow のレコードをデータストリームの各オブジェクトに対して簡単に作成できるようになります。「フロー内での データストリーム アクションの使用」を参照してください。
- スクリプトから
- FlowAPI クラスの executeDataStreamAction() メソッドを使用して データストリーム を開始できます。詳細については、「FlowAPI」を参照してください。
アクションアウトライン
データストリーム アクションは設定された構造に従います。プロンプトに従って、アクションアウトラインのステップを追加および削除します。データストリーム アクションに手動でステップを追加することはできません。
アクションエラー評価
エラー評価を使用してステップエラーを検出し、データストリームアクションに追加する各ステップのエラー動作を指定します。アクションがエラーステータスを返すタイミングと、返されるステータスコードとメッセージを指定することで、独自のエラー条件を作成することもできます。
アクションの前処理
アクション前処理カテゴリを使用して、接続と資格情報の詳細を取得したり、前処理スクリプトを実行したりします。
アクションで使用する接続と資格情報の詳細を取得するには、[接続情報を取得 (Retrieve connection info)] を選択します。このオプションを選択すると、アクション前処理の最初のステップとして「接続情報の取得」ステップが追加されます。詳細については、「Get Connection Info step」を参照してください。
アクションが最初の API 要求を送信する前の前処理スクリプトを実行するには、[前処理スクリプトを有効化] を選択します。たとえば、アクション入力を検証するかデフォルト値を設定します。 このオプションを選択すると、スクリプトステップが データストリーム アクションに追加されます。詳細については、「Script step」を参照してください。
前処理は、最初の API 要求の前にアクションごとに 1 回実行されます。
これは、インスタンスまたは MID サーバー のいずれかで実行されるオプションの データストリーム アクションコンポーネントです。
要求
[要求] カテゴリを使用して、アクションが API 要求を送信する方法を設定します。[要求] セクションは、結果のページごとに 1 回実行されます。要求コンポーネントは、次の構成オプションを提供します。
- ページネーションセットアップステップ
次のことを要求します： 結果はバッチで表示されます。データの 1 つのページが処理されると データストリーム アクションによって要求セクションが再実行されて、次の一連の結果が返されます。。ページネーションセットアップステップを使用して、API に必要なページネーションオプションを設定します。ページネーションのセットアップ手順を手動で構成するか、ビルド済みのテンプレートを選択して一般的な構成を適用します。 たとえば、制限/オフセットテンプレートを適用して、ページごとに返されるアイテムの数 (制限) と最初のアイテムの開始番号 (オフセット) を指定します。テンプレートを適用後、値を更新して構成が API の要件に準拠していることを確認します。
注:ライセンスの目的では、各要求は、結果の次のページの各要求を含め、1 つのトランザクションとしてカウントされます。予約済みの読み取り専用
getNextPage変数の値は、結果の別のページを要求するかどうかを決定します。getNextPage変数が true で前のページにデータが含まれている限り、アクションは次のページの要求を送信し続けます。注:スクリプトで値を明示的に true に設定する必要があります。そうしないと、デフォルトで false に設定されます。これは、インスタンスのみで実行されるオプションのアクションコンポーネントです。注:ページネーションは JDBC ステップには適用されません。- スクリプト ステップ
結果の次のページに対してすべての要求の前にスクリプトを実行します。このスクリプトは、ページネーションされた API を呼び出すときにデータの検証と変換に使用します。たとえば、次のページ要求の JSON ペイロードを生成します。 このオプションを選択すると、スクリプトステップが データストリーム アクションに追加されます。詳細については、「Script step」を参照してください。
これは、インスタンスまたは MID サーバー のいずれかで実行されるオプションの要求コンポーネントです。
- REST または SOAP ステップ
REST または SOAP 要求をサードパーティ API に送信します。関連するステップを データストリーム アクションに追加するデータ形式を選択します。詳細については、「REST ステップ」と「SOAP ステップ」を参照してください。
これは、インスタンスまたは MID サーバー のいずれかで実行される必須要求コンポーネントです。
- JDBC ステップ
JDBC 要求をサードパーティ API に送信します。変換スクリプトを使用して、データをフォーマットし、関連するステップを データストリーム アクションに追加します。詳細については、「JDBC ステップ」と「JDBC ステップのテスト」を参照してください。すべてのデータが取得され、ページネーションは必要ありません。
これは、MID サーバー で実行される必須要求コンポーネントです。
REST および SOAP ステップでの解析
- REST または SOAP ステップの応答本文、ストリーム、またはエラーメッセージの出力
- セパレーターステップ出力
複合データの詳細については「複合データ」を参照してください。解析コンポーネントは、これらの構成オプションを提供します。
- スプリッターステップ
次のことを特定します：複合オブジェクトにマップする応答ストリームにある親ノード。たとえば、XML ペイロードのユーザー要素を識別して、応答ストリームのユーザーごとに複合オブジェクトを作成します。
XML または JSON データストリーム内の繰り返しアイテムを識別して区切るためにスプリッタータイプを選択します。
- JSON：JSON データのストリームからのオブジェクトを識別します。JSONPath 式を使用して、繰り返しデータが含まれる JSON アレイを識別します。
- XML：XML データのストリームからのオブジェクトを識別します。XPath 式を使用して、繰り返しデータが含まれる XML 要素を識別します。
これは、インスタンスのみで実行される必須解析コンポーネントです。
- スクリプトパーサーステップ
使用 - JavaScript と ServiceNow API。応答ストリームのアイテムを
targetObjectグローバルオブジェクトによって表される複合オブジェクト出力にマッピングします。たとえば、スプリッターステップで識別されたインシデントレコード要素を、インシデントフィールドを含む複合オブジェクトにマッピングします。データストリームに、複合オブジェクトへマッピングしないスプリッターステップで識別されたアイテムの兄弟アイテムが含まれる場合は、それらのアイテムを除外する条件を含めます。。必要に応じて、[スクリプトパーサー] ステップの [スクリプト] セクションにoutputs.state = 'SKIP'を追加することで、ストリーム内のアイテムをスキップできます。これは、インスタンスのみで実行される必須解析コンポーネントです。
REST ベースのデータストリームアクションの解析フェーズの生成
REST ベースのデータストリームアクションのスプリッターステップ、スクリプトパーサーステップ、および出力を自動的に構成できます。REST ベースのデータストリームの [REST ステップをテスト] アクションは、設定された REST エンドポイントへの要求を実行し、応答ペイロードを分析し、解析コンポーネントと出力コンポーネントを自動的に設定します。
REST ステップがデータストリームアクションの [要求] セクションに追加されると、REST ステップの [ REST ステップをテスト ] ボタンを使用して 、[解析中] セクションと出力を自動生成できます。[解析] セクションには、スプリッターステップとパーサーステップが含まれています。自動生成では、複合オブジェクトの出力も [出力] セクションに配置されます。
JDBC ステップの変換スクリプト
JDBC データストリームアクションはページネーションを必要としません。また、スプリッターステップとパーサーのステップは必要ありません。
SOAP ステップおよび REST ステップでのデータストリーム出力
データストリーム アクションを設計するときは、オブジェクトタイプまたはダイナミックオブジェクトタイプの単一の出力を作成する必要があります。スクリプトパーサーステップは、 targetObject グローバルオブジェクトを使用して、ストリーム内のアイテムをこのオブジェクトにマップします。
実行時に、システムは データストリーム 構成に従って応答データのストリームを分割して解析します。ストリーム内の各アイテムは、スクリプトパーサーステップで定義された複雑なオブジェクト構造とオブジェクト出力にマップされ、結果として一連の複雑なオブジェクトが大量に生成されます。複合データの詳細については「複合データ」を参照してください。
JDBC ステップでのデータストリーム出力
- JDBC データストリームアクションを使用してデータを取得することはできますが、レコードを更新または削除することはできません。
- JDBC ステップで使用可能な [最大行] および [最大ペイロードサイズ (KB)] フィールドは、JDBC データストリームアクションでは使用できません。
REST および SOAP ステップの実行の詳細
データストリーム アクションによって処理された各アイテムの構成と実行時の結果を表示します。レコード番号を選択すると、その構成と実行時の詳細が表示されます。デフォルトでは、実行の詳細には最新の 1000 アイテムの要求が含まれます。実行の詳細のアイテム数を変更するには、 com.snc.process_flow.reporting.datastream.item.lastn システムプロパティを更新します。
- データストリームサマリー
次の情報を含む実行の概要を表示します。
- [ページ数]：ページネーションされた API によって返されるページ数。
- [合計アイテム数]：複合オブジェクト出力にマップされた応答ストリーム内のアイテムの数。
- [エラー数]：発生したエラーの数。
- ページの詳細
データストリーム アクション内の各ステップのランタイムデータを表示します。ページネーションされた API への各要求のランタイムの詳細を表示するページを選択します。デフォルトでは、[実行の詳細] には最後の 5 ページの要求が含まれます。実行の詳細の要求数を変更するには、 com.snc.process_flow.page.reporting.lastn システムプロパティを更新します。値を 0 に設定すると [実行の詳細] からページが削除され、 -1 に設定するとすべてのページが含まれます。
注:すべてのページを含めるとパフォーマンスに影響する可能性があるため、お勧めしません。
JDBC ステップでの実行の詳細
JDBC データストリームアクションでは、出力複合オブジェクトスキーマのビルドは必要ありません。クエリをテストし、クエリ結果を確認できます。詳細については、「JDBC ステップのテスト」を参照してください。要件に従ってデータを取得するように MID サーバー プロパティ mid.jdbc.datastream.max.record.size および mid.jdbc.datastream.fail.when.attachement.limit.exceeded を設定します。詳細については、「MID サーバープロパティ」を参照してください。