データストリームアクションの作成

リリースバージョン: Zurich

更新日 2025年07月31日

所要時間：14分

フロー内の応答データのストリームを処理する再利用可能なアクションを作成します。

始める前に

ガイド付きアプリケーションクリエーターでアプリケーションを設定してワークフロースタジオコンテンツを保存します。
アクションを作成する前に、競合するビジネスルールまたはワークフローを無効にします。
必要なロール：action_designer または admin

このタスクについて

カスタムアプリケーションを作成してワークフロースタジオのコンテンツを格納することで、アプリケーションリポジトリまたは ServiceNow Store を使用してコンテンツを展開することができます。

注:

設定ページのオプションを消去すると手順がデータストリームアウトラインから削除されて、関連付けられるすべてのデータが削除されます。

手順

移動先すべて > フローデザイナー > デザイナー.
[アクション] タブをクリックし、[データストリーム] を選択します。

アクションのプロパティを入力し、[送信] をクリックします。


フィールド	説明
アクション名	データストリームアクションの一意の名前を入力します。
Description (説明)	データストリームアクションの説明。
アプリケーション	データストリームアクションのアプリケーションスコープ。
ドメイン	データストリームアクションのドメインスコープ。ドメインセパレーションの詳細については、「Domain separation explained」を参照してください。
追加のプロパティ
アクセス可能	スコープ対象のすべてのアプリケーションから、または指定したアプリケーションスコープ内のみから、アクセス可能です。
カテゴリ	アクションのアプリケーションスコープ内で定義されたカテゴリ。Xanadu リリース以降、カスタムカテゴリを作成してデータストリームアクションを整理できます。
保護	データストリームアクションを読み取り専用にするかどうかを選択します。自分が所有するアプリケーションスコープでデータストリームアクションを作成する場合にのみ、値を選択できます。デフォルト値は「なし」です。
アクションの注釈	ワークフロースタジオのデータストリームアクションのタイトルの下に表示されるヘルプテキストで、データストリームアクションの作成者がフローで使用されるときにデータストリームアクションが何を行うかを理解できるようにします。

空のデータストリームアクションが開きます。

アクションステップでデータを利用できるように、アクションの入力を定義します。
1. [+ 入力の作成] を選択し、フィールドに入力します。
  入力は右側のペインにデータピルとして表示されます。
アクション入力の詳細については、次を参照してください。ワークフロースタジオ - カスタムアクションのビルド.
データストリームアウトラインの [アクション前処理] をクリックし、必要なオプションを設定します。
1. [接続情報を取得 (Retrieve connection info)] を選択し、アクション前処理の最初のステップとして「接続情報の取得」ステップを追加します。
  「接続情報の取得」ステップを使用すると、アクションで使用する接続と資格情報の詳細を取得できるようになります。詳細については、「Get Connection Info step」を参照してください。
2. [前処理スクリプトを有効化] を選択して次のことを実行します：アクションが最初の API 要求を送信する前の前処理スクリプト。たとえば、アクション入力を検証するかデフォルト値を設定します。前処理は、最初の API 要求の前にアクションごとに 1 回実行されます。
  
  このオプションを選択すると、スクリプトステップがデータストリームアクションに追加されます。詳細については、「Script step」を参照してください。
  
  重要:
  データストリームアクションでは、応答ストリームへの常時接続が必要です。アクションを一時停止して MID サーバーを呼び出したり、アクションを一時停止して条件や期間を待機したりする前処理スクリプトはサポートされていません。何らかの理由でアクションを一時停止する前処理スクリプトは、エラーメッセージを返します。
データストリームアウトラインの [要求] をクリックし、必要なオプションを設定します。
1. [データの取得方法] フィールドで [REST ステップ]、[SOAP ステップ]、または [JDBC ステップ] を選択し、関連するステップをデータストリームアクションに追加します。
  詳細については、「REST ステップ」、「SOAP ステップ」、「JDBC ステップ」を参照してください。
  
  このセクションは、MID サーバーまたはインスタンスのいずれかで実行できます。環境は、関連する接続 [sys_connection] レコードの [MID サーバーを使用] フィールドによって決定されます。
  注:
  JDBC ステップを使用している場合は、それをテストする必要があります。正常に実行されると、その結果を使用してステップ出力とデータストリームアクション出力を作成できます。
  
  REST ステップまたは SOAP ステップを使用している場合は、データストリームアクション出力を手動で作成する必要があります。
2. [ページネーションを有効化] を選択して次のことを要求します：結果はバッチで表示されます。データの 1 つのページが処理されるとデータストリームアクションによって要求セクションが再実行されて、次の一連の結果が返されます。。このオプションは、データストリームアウトラインにページネーションのセットアップステップを追加します。
  
  注:
  JDBC ステップの場合、ページネーションは適用されません。各ページは最大 1 GB のデータを取得でき、1 つの要求は最大 8 GB のデータを取得できます。
3. ページネーションされた API を呼び出すときに次のページのすべての要求の前にスクリプトを実行するには、[各要求の前にスクリプトを実行] を選択します。
  たとえば、次のページの要求を送信する前に、最初の応答から変数データタイプを変換するスクリプトを作成します。
  
  このオプションを選択すると、スクリプトステップがデータストリームアクションに追加されます。詳細については、「Script step」を参照してください。
  
  注:
  JDBC ステップの場合、これは適用されません。
  
  このセクションは、MID サーバーまたはインスタンスのいずれかで実行できます。環境は、スクリプトステップの [必須ランタイム] フィールドによって決定されます。
  
  重要:
  インスタンスと MID サーバーを複数回実行する環境間への移行は避けてください。たとえば、要求スクリプトステップを MID サーバーで実行するように構成できますが、REST 手順はインスタンスで実行されます。この場合、システムはデータのすべてのページについてインスタンスと MID サーバー間で環境を移行します。これにより、パフォーマンスが低下する可能性があります。
オプション: ページネーションが有効になっている場合は、ページネーションのセットアップ手順を設定します。
ページネーションのセットアップ手順を手動で構成するか、ビルド済みのテンプレートを選択して一般的な構成を適用します。たとえば、制限/オフセットテンプレートを適用して、ページごとに返されるアイテムの数 (制限) と最初のアイテムの開始番号 (オフセット) を指定します。テンプレートを適用後、値を更新して構成が API の要件に準拠していることを確認します。
1. ページネーション変数を作成します。
  たとえば、サードパーティ API が要求で limit パラメーターを受け取る場合は、 limit 変数を作成し、初期値を設定してページあたりの結果数を制限します。初期値は最初の要求でのみ使用されます。getNextPage は予約済みの読み取り専用変数です。 getNextPage 変数が true で前のページにデータが含まれている限り、アクションは次のページの要求を送信し続けます。
2. [次の値取得元] フィールドで、ページネーション変数が後続の要求の値を受け取る方法を定義します。
  以下から選択します。
  - [スクリプト]：ページネーション変数スクリプトを記述して、変数の入力方法を定義します。ページネーション変数は、文字列データ型のみをサポートします。数式演算を実行するには、値を整数に変換して必要な操作を実行し、文字列に変換する必要があります。
  - [応答本文]：前の要求からの応答の値を使用して変数を設定します。応答が JSON 形式の場合は、[値の抽出に使用] を JSONPath Expression に設定し、[式] フィールドに値へのパスを指定します。応答が XML 形式の場合は、[値の抽出に使用] を XPath Expression に設定し、値へのパスを指定します。
この例では、 getNextPage 変数は、 nextOffset 変数が API 応答ヘッダーに返される合計数の値に達するまで true です。getNextPage 変数が true で前のページにデータが含まれている限り、アクションは次のページの要求を送信し続けます。この例には、一般的な制限/オフセットページネーション構成が含まれています。データストリームアクションがやり取りするサードパーティ API は、ページトークンまたはその他のメソッドを使用する場合があります。

重要:
getNextPage 変数を false に設定する条件を作成することで、無限ループがページネーション要求で発生することを回避します。長実行時間のフローをキャンセルします。データストリームアクションは、本番環境で使用する前に常にテストしてください。
データストリームアウトラインの [解析] をクリックし、必要なオプションを設定します。

注:
JDBC ステップの場合、これは適用されません。
1. [各レコードを識別する方法] フィールドで [JSON/XML スプリッター] を選択し、Splitter ステップをデータストリームアウトラインに追加します。
2. [各アイテムをオブジェクトに解析する方法 (How will you parse each item into an object)] フィールドで [スクリプトパーサー] を選択し、スクリプトパーサーステップをデータストリームアウトラインに追加します。
スプリッターステップを設定します。

このステップでは、次のことを特定します：複合オブジェクトにマップする応答ストリームにある親ノード。たとえば、XML ペイロードのユーザー要素を識別して、応答ストリームのユーザーごとに複合オブジェクトを作成します。

注:
JDBC ステップの場合、これは適用されません。
1. [ソース形式] フィールドで、[要求] セクションから返される形式を選択します。
  - JSON：JSON データのストリームからのオブジェクトを識別します。JSONPath 式を使用して、繰り返しデータが含まれる JSON アレイを識別します。
  - XML：XML データのストリームからのオブジェクトを識別します。XPath 式を使用して、繰り返しデータが含まれる XML 要素を識別します。
2. [アイテムパス] フィールドで、オブジェクトにマッピングするデータストリーム内のアイテムへの絶対パスを定義します。
  
  JSON
  
  オブジェクトのアレイへの絶対パスを JSONPath 式として識別します。たとえば、JSON の result アレイ内の各アイテムを result オブジェクトに分割するには、$ .result を使用します。
  注:
  JSON データストリームのルートノードでアレイを選択すると、実行の詳細とエラーメッセージに絶対パスが $.* として表示されます。
  
  XML
  
  繰り返しデータオブジェクトへの絶対パスを XPath 式として識別します。たとえば、result XML 要素の各インスタンスを result オブジェクトに分割するには、/result を使用します。
  注:
  スプリッターステップは、XML 名前空間を無視します。
  たとえば、REST ステップが JSON データのストリームを返すとします。アイテムパス $.response.result.companies は、companies アレイの各アイテムを返します。
```
{
  "response": {
    "result": {
      "companies": [
        {
          "name": "company1"
        },
        {
          "name": "company2"
        },
        {
          "name": "company3"
        }
      ],
      "metadata": {
        "token": 1558666526
      }
    }
  }
} 
```
  たとえば、REST ステップが XML データのストリームを返すとします。アイテムパス /response/result/companies/company は、XML データから各 company 要素を返します。
```
<response>
  <result>
    <companies>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <company>
        
      </company>
      <batch>10645C53D4BED73YQ</batch> 
    </companies>
    <metadata>
      <timestamp>1558666526</timestamp>
    </metadata>
  </result>
</response>
```
スクリプトパーサーステップで JavaScript と ServiceNow API を使用して、応答ストリームのアイテムを、targetObject グローバルオブジェクトによって表される複合オブジェクト出力にマッピングします。
たとえば、スプリッターステップで識別されたインシデントレコード要素を、インシデントフィールドを含む複合オブジェクトにマッピングします。データストリームに、複合オブジェクトへマッピングしないスプリッターステップで識別されたアイテムの兄弟アイテムが含まれる場合は、それらのアイテムを除外する条件を含めます。

注:
JDBC ステップの場合、これは適用されません。
fd_data オブジェクトを使用して、データストリームアクションの前のステップの出力にアクセスできます。ただし、次のものは除きます。
- REST または SOAP ステップの応答本文、ストリーム、またはエラーメッセージの出力。
- セパレーターステップ出力。
JSON 応答を解析するスクリプト例。
```
(function parse(inputs, outputs) {
    var record = JSON.parse(inputs.sourceItem);
    outputs.targetObject.id=record.number;
    outputs.targetObject.name=record.short_description;
})(inputs, outputs)
```
XML 応答を解析するスクリプト例。
```
(function parse(inputs, outputs) {
    var xmlDoc = new XMLDocument(inputs.sourceItem, false);
    outputs.targetObject.id = xmlDoc.getNodeText("/result/number");
    outputs.targetObject.name = xmlDoc.getNodeText("/result/short_description");
})(inputs, outputs)
```
オプション: ユーザーが JDBC ステップを選択した場合は、[Transform] をクリックします。
JDBC ステップを正常にテストした後、[結果の使用] をクリックして、ステップ出力とデータストリームアクション出力を作成します。この結果を使用することも、変換スクリプトを使用してカスタマイズすることもできます。
1. デフォルトのデータストリーム出力を変換およびカスタマイズするには、[変換スクリプトを有効にする] チェックボックスをオンにします。
複雑なオブジェクト出力を作成します。

注:
JDBC ステップの場合、これは適用されません。
1. [アクションのアウトライン] で [出力] を選択し、[+] をクリックして出力を作成します。
2. [ラベル] フィールドを更新して、オブジェクトを表します。
  たとえば、アクションが会社レコードのストリームを解析する場合は、会社ラベルを追加します。
3. [タイプ] フィールドを [Object] に更新します。
  これは、スクリプトパーサーステップの targetObject グローバルオブジェクトによって表される複合オブジェクト出力です。
4. [+] アイコンを使用して複合オブジェクトに子フィールドを追加します。
5. スクリプト内で意味のある参照ができるように、それぞれの子フィールドの名前を分かりやすくします。
  
  [名前] フィールドの値は、スクリプトパーサーステップで使用される内部名です。たとえば、スクリプトパーサーステップで市の出力を参照するには、 outputs.targetObject.city を使用します。
  
  警告:
  データストリームアクションを保存した後は、[名前] フィールドの値を変更できません。
[保存] をクリックします。
ワークフロースタジオによってアクションのドラフトが保存されます。

次のタスク

データストリームアクションのテスト。