記事 (1/32)
このモジュールでは、次のことを学習します。
前提条件:このモジュールは、Flow Designer、カスタムアクション、送信 REST 要求、および IntegrationHub のトピックに精通していることを前提としています。
Flow Designer の基本については、「Flow Designer の使用」モジュール、「Flow Designer の開発」モジュールでのカスタムアクションの作成と使用、「送信 REST データ連携」モジュールでの送信 REST 要求、「IntegrationHub の REST」モジュールでの IntegrationHub について学ぶことができます。
記事 (2/32)
重要:この学習モジュールの内容は、Quebec ServiceNow リリース用に最後に更新されたもので、Rome リリースでは更新されていません。Rome リリースとこの学習モジュールのコンテンツとの間に違いが見られる場合があります。
Rebrickable Spoke アプリケーションは、アプリケーション作成の基になる概念とプロセスを紹介し、デモンストレーションするために、この学習モジュール全体で使用されます。受講者は Rebrickable Spoke アプリケーションを構築しません。
実習では、World Glaciers Spoke アプリケーションを開発します。
演習は、次の 3 つの方法で示されます。
World Glaciers Spoke アプリケーションでは、ユーザーが World Glaciers Web サービスを使用して氷河に関する情報を取得できます。
記事 (3/32)
IntegrationHub には、次の 4 つのサブスクリプションレベルがあります。
サブスクリプションのレベルごとに、追加のスポークと機能が入っています。IntegrationHub サブスクリプションパックには IntegrationHub サブスクリプションが必要です。サブスクリプションパックは ServiceNow 担当者が有効化する必要があります。IntegrationHub サブスクリプションパックには、関連するプラグインがまだ有効になっていない場合のデモデータとアクティベーションが入っています。会社のインスタンスで IntegrationHub を要求する方法については、ドキュメントを参照してください。各サブスクリプションレベルに付属する機能について、ドキュメントに詳しく記載されています。
注意:IntegrationHub を本番インスタンスで使用するには、サブスクリプションが必要です。IntegrationHub を非本番および個人の開発者インスタンスで有効化すれば、サブスクリプションなしでデータ連携を構築およびテストすることは可能です。この学習モジュールでは、エンタープライズパックを使用します。
開発者サイトの [自分のインスタンス (My Instance)] セクションから、Personal Developer Instance (PDI) の ServiceNow IntegrationHub Enterprise Pack Installer プラグインを有効化します。開発者サイトの任意のページから、[アカウント] メニューをクリックし、[プラグインの有効化] インスタンスアクションを選択します。ServiceNow IntegrationHub Enterprise Pack Installer の [有効化] ボタンをクリックして、すべての IntegrationHub プラグインを有効化します。
ServiceNow IntegrationHub Enterprise Pack Installer プラグインでは IntegrationHub 関連の複数のプラグインを有効化するため、完了までに 10 分ほどかかります。プラグインの有効化が完了すると、開発者サイトからメールが送信されます。
演習 (4/32)
この演習では、Personal Developer Instance (PDI) で ServiceNow IntegrationHub Enterprise Pack Installer プラグインを有効化します。
演習 (5/32)
この演習では、World Glaciers Web サービスについて詳しく見ていきます。
World Glaciers Web サービスは、無料で公開されているソースのデータを使用して、地球上の氷河に関する情報を提供します。この Web サービスは、JSON 形式のページネーションされたデータを返します。World Graciers Web サービスは、ServiceNow インスタンスで実行される Scripted REST API です。
記事 (6/32)
データストリームアクションは、REST または SOAP 要求を Flow Designer から次のような API に送信します。
データストリームアクションにより、[For Each] フローロジックを使用してデータストリーム内の各オブジェクトを処理することで、フローが大きな要求を処理できます。
記事 (7/32)
Flow Designer のランディングページの任意のタブからデータストリームアクションを作成するには、[新規] ボタンをクリックして [データストリーム] メニューアイテムを選択します。
または、[フロー、サブフロー、またはアクションの作成] ボタン () をクリックし、[データストリーム] メニューアイテムを選択します。
[アクションプロパティ] ダイアログが開きます。
以下のようにアクションプロパティを構成します。
開発者向けのヒント:アクション名にはスペースを使用できます。アクションには分かりやすい名前を使用します。
記事 (8/32)
データストリームアクションは、5 つのセクションで構成される固定の構造になっています。
[アクションアウトライン] セクションを選択して、データストリームアクションを構成します。[アクションアウトライン] の [アクション前処理]、[要求]、および [解析] セクションでは、特定の構成オプションを選択するとアクションにステップが追加されます。たとえば、[解析中] セクションで、[各レコードをどのように識別しますか] フィールドの値が JSON/XML スプリッターである場合、[解析中] セクションに「分割」ステップ が追加されます。
開発者は構成オプションを使用してデータストリームアクションにステップを追加できますが、それ以外のステップを追加することはできません。開発者がデータストリームアクションにステップを追加できるのは、[アクションアウトライン] の [アクション前処理]、[要求]、および [解析] セクションのオプションを構成した場合のみです。
演習 (9/32)
この演習では、World Glaciers のスポークとデータストリームアクション入力を作成します。
注意:PDI が自動的に App Engine Studio を開く場合は、PDI にアクセスするために使用するユーザーロールを変更する必要があります。演習を完了するには、[管理者] ユーザーロールに切り替えます。
記事 (10/32)
データストリームアクションでのアクションの入力と出力は、Flow Designer や IntegrationHub のアクションの場合と同じように動作します。アクションの入力と出力の詳細については、「Flow Designer の開発」トレーニングモジュールを参照してください。
アクションの入力では、変数をアクションステップと出力に渡します。アクションの入力は、Flow Designer でのアクションの構成オプションです。
アクション出力を使用して、アクション内で使用される変数をフローで使用できるようにします。アクション出力はフロー内のデータピルです。
演習 (11/32)
この演習では、World Graciers API の次のようなアクション入力を作成します。
World Glacier Web サービスには、first_rec と num_recs_per_pageという 2 つの必須のクエリパラメーターがあります。演習のこのセクションでは、Web サービスのクエリパラメータのアクション入力を作成します。
データストリームアクションでは、取得する氷河のレコードのページ数を把握する必要があります。ここでの課題は、取得するページ数のアクション入力を作成することです。「 取得するページ数 (Pages to get)」というラベルを使用します。すでに作成したアクション入力を手本にして、「取得するページ数 (Pages to get)」のアクション入力の残りの部分を構成します。
記事 (12/32)
[アクション前処理] セクションは、データストリームアクション 1 回につき 1 回実行されます。アクション前処理は、最初の API 要求の前に行われます。
データストリームアクションにステップを追加するように [アクション前処理] セクションを構成します。
記事 (13/32)
データストリームを実行する前に入力を検証したり、デフォルト値を設定したり、要求ペイロードを準備したり、その他の必要なタスクを実行したりするには、アクション前処理スクリプトのステップを使用します。
アクション前処理スクリプトでは、inputs と outputs オブジェクトの両方にアクセスできます。[入力変数] セクションで inputs オブジェクトのプロパティを定義し、[スクリプトステップ] フォームの [出力変数] セクションで outputs オブジェクトのプロパティを定義します。
[必須ランタイム] フィールドは、スクリプトの実行場所を決定します。
注意:MID Server については、このトレーニングモジュールでは扱いません。
入力変数を追加するには、[入力変数] セクションの [+ 変数の作成] ボタンをクリックします。
入力変数を設定します。
名前:inputs オブジェクトの [入力変数] のプロパティ名。
値:入力変数の初期値。値は、ハードコーディングされたもの、データピル、またはハードコーディングされたものとデータピルの組み合わせです。
この例では、入力変数の値はアクション入力によって設定されます。
出力変数を追加するには、[出力変数] セクションの [+ 変数の作成] ボタンをクリックします。
出力変数を設定します。
ラベル:人間が判読できるラベル。変数を参照するデータピルで使用します。
名前:outputs オブジェクトの [出力変数] のプロパティ名。
タイプ:outputsオブジェクトの [出力変数] プロパティのデータタイプ。
必須:処理を続行するために、[出力変数] に [データストリームアクション (Data Steam Action)] の値が必要な場合に選択します。
アクション前処理スクリプトの目的は、outputs オブジェクトプロパティの値を設定することです。データピルを介して、後続のすべてのデータストリームアクションが outputs オブジェクトプロパティにアクセスできます。このスクリプト例では、inputs オブジェクトのプロパティ値が、アクションを呼び出すフローまたはユーザーによってアクションに渡された入力に基づいて設定されます。3 つの inputs オブジェクトのプロパティ値がゼロまたはゼロ未満の場合、outputs のプロパティ値は文字列の値 1 に設定されます。inputs オブジェクトのプロパティがゼロより大きい場合、outputs プロパティ値は inputs オブジェクトのプロパティの中から対応する値に設定されます。
演習 (14/32)
この演習では、アクション入力の値を検証する次のアクション前処理スクリプトを作成します。
演習のこのセクションでは、スクリプトステップの入力変数を作成し、アクション入力をスクリプトステップの入力変数にマッピングします。
演習のこのパートでは、出力変数を作成します。まだ記述されていないスクリプトでは、出力変数に値が追加されます。
演習のこのセクションでは、ユーザーが入力したデータを検証するスクリプトを追加します。このスクリプトでは、ユーザー指定の値からマッピングされた input オブジェクトのプロパティを使用して outputs オブジェクトのプロパティ値を設定します。
記事 (15/32)
[要求] セクションでは、データストリームアクションが API 要求を送信する方法を構成します。[要求] セクションは、結果のページごとに 1 回実行されます。
データストリームアクションにステップを追加するように [要求] セクションを構成します。
記事 (16/32)
ページネーション設定ステップを使用すると、API 要求の中で動的に決定される部分の値を指定できます。たとえば、ページネーションされたデータを返す API への要求では、通常、送信するデータのページを指定する必要があります。
ページネーションされた API は、一度に 1 ページずつデータを送信します。ページネーション変数を使用すると、API に必要なオプションの値を設定できます。
getNextPage 変数は読み取り専用で、すべてのページネーション設定ステップに含まれています。getNextPage 変数は、API から別のページを要求するかどうかを決定します。無限ループを回避するため、getNextPage 変数のデフォルト値は false になっています。getNextPage 変数値が true の場合、データストリームアクションは引き続き API 要求を行います。
開発者は、[テンプレートを表示] ボタンをクリックして、limit や offset などの一般的に使用される変数を挿入するページネーション変数テンプレートを適用できます。ページネーション変数を作成するには、[追加] ボタン () をクリックします。
ページネーション変数を構成します。
ページネーション変数スクリプトは、各 API 呼び出しの後にスクリプトロジックが実行されるサーバーサイドスクリプトです。ページネーション変数スクリプトの目的は次のとおりです。
ページネーション変数スクリプトは、次の 2 つのオブジェクトを渡します。
開発者向けのヒント:ページネーション変数、および pageResponse から解析されるものは、すべて文字列です。ページネーション変数スクリプトでは、数学演算またはその他の演算に対して正しいデータタイプを確保するために型キャストが必要になる場合があります。
記事 (17/32)
[要求] セクションでは、結果の次のページに対するすべての要求の前に、スクリプトステップがスクリプトを実行します。ページネーションされた API を呼び出すときは、データの検証と変換にスクリプトステップを使用します。たとえば、次のページの要求に対して JSON ペイロードを生成する場合などです。スクリプトステップはオプションです。
スクリプトステップの構成方法については、このトレーニングモジュールの「アクション前処理:スクリプトステップ」のページを参照してください。
演習 (18/32)
この演習では、[World Glaciers - LatLong] データストリームアクションの [要求] セクションを構成します。[ページネーション設定ステップ] も設定します。
演習のこのセクションでは、ページネーション変数スクリプトで使用するページネーション変数を作成します。
記事 (19/32)
[要求] セクションの構成に応じて、データストリームアクションに REST、SOAP、JDBC ステップのいずれかが含まれます。[データをどのように取得しますか] フィールドによって、挿入するステップが決まります。
このトレーニングモジュールでは、REST ステップを使用します。
REST ステップで、API に接続して情報を要求する方法を指定します。この例では、Rebrickable API を使用して LEGO の色に関する情報を取得します。
注意:REST ステップの設定の詳細については、IntegrationHub の REST トレーニングモジュールを参照してください。
演習 (20/32)
この演習では、[World Glaciers - LatLong] データストリームアクションの REST ステップを構成します。
REST ステップでは、 World Graciers Web サービスへの要求の詳細を設定します。get_glassers_latlong GET メソッドを使用します。World Glaciers Web サービスのドキュメントを使用して、次の質問に回答してください。
質問:すべての World Graciers Web サービス要求のベース URL は何ですか?
回答:ベース URL は https://sndevapiserver.service-now.com です。
質問: get_glassers_latlong GET メソッドのリソースパス (クエリパラメーターを含まない URL) は何ですか?
回答: リソースパスは /api/x_snc_world_glacie/v1/world_glaciers/getglaciers/latlong です。
質問: get_galciers_latlong GET メソッドにはいくつのクエリパラメーターが必要ですか?それらは何ですか?
回答:get_glaciers_latlong メソッドには、first_rec と num_recs_per_page の 2 つのクエリパラメーターが必要です。
記事 (21/32)
[解析中] セクションでは、データストリーム要素をデータオブジェクトに分離する方法を指定します。[解析中] セクションは、ストリーム内のアイテムごとに 1 回実行されます。
データストリームアクションにステップを追加するように [解析中] セクションを構成します。
記事 (22/32)
スプリッターステップは、応答ストリーム内の親ノードを識別します。応答ストリームは、後で複合オブジェクトにマッピングされます。
たとえば、Rebrickable API の colors メソッドは次の JSON を返します。
{ "count": 182, "next": "https://rebrickable.com/api/v3/lego/colors/?page=2&page_size=1", "previous": null, "results": [ { "id": 0, "name": "Black", "rgb": "05131D", "is_trans": false, "external_ids": { "BrickLink": { "ext_ids": [ 11 ], "ext_descrs": [ [ "Black" ] ] }, "BrickOwl": { "ext_ids": [ 38 ], "ext_descrs": [ [ "Black" ] ] }, "LEGO": { "ext_ids": [ 26, 149, 1012 ], "ext_descrs": [ [ "Black", "BLACK" ], [ "Metallic Black", "MET.BLACK" ], [ "CONDUCT. BLACK" ] ] }, "Peeron": { "ext_ids": [ null ], "ext_descrs": [ [ "black" ] ] }, "LDraw": { "ext_ids": [ 0, 256 ], "ext_descrs": [ [ "Black" ], [ "Rubber_Black" ] ] } } } ] }
色の値 name と rgb は、返される JSON の results プロパティの一部であることに注意してください。目的が色の値 name と rgb を取得することである場合は、results プロパティで返された JSON を分割して、results プロパティを親ノードにします。[アイテムパス] フィールドで、JSONPath 表記を使用して分割する場所を指定します。この例では、アイテムパスは $.results です。
分割によって作成された応答ストリームは、スクリプトパーサーステップに渡されます。
注意:ソース形式が XML の場合は、XPath 表記を使用して分割する場所を指定します。
記事 (23/32)
スクリプトパーサーステップは、サーバーサイドスクリプトを使用して、スプリッターステップから受信した応答ストリームからプロパティ値を抽出し、複合オブジェクトに設定します。スクリプトパーサースクリプトの一般的な戦略は次のとおりです。
スクリプトステップの [スクリプトパーサースクリプト] フィールドのコメントで、必要な処理について説明し、XML と JSON 両方の例を示します。
(function parse(inputs, outputs) { // Source item string is available in inputs.sourceItem. // Generate output by setting fields of outputs.targetObject. // // The structure of outputs.targetObject corresponds to the // structure defined in the Data Stream Action output. // // Optionally skip an item in the stream by setting // outputs.state = 'SKIP' // // JSON Example: // var item = JSON.parse(inputs.sourceItem); // outputs.targetObject.ffName = item.firstName; // outputs.targetObject.llName = item.lastName; // outputs.targetObject.address.home.city = item.address.home.city; // // XML Example: // var xmlDoc = new XMLDocument2(); // xmlDoc.parseXML(inputs.sourceItem); // var root = xmlDoc.getDocumentElement(); // if (root.getNodeName() != 'user') { // outputs.state = 'SKIP'; // return; // } // outputs.targetObject.id = xmlDoc.getNodeText('/user/id'); // outputs.targetObject.fname = xmlDoc.getNodeText('/user/person/first_name'); // outputs.targetObject.lname = xmlDoc.getNodeText('/user/person/last_name'); })(inputs, outputs)
inputs オブジェクトは自動的にスクリプトに渡されます。inputs.sourceItem プロパティには、スプリッターステップからのストリームが含まれています。
コメントに示されているように、JSON の場合は JSON.parse() メソッドを使用して inputs.sourceItem から JavaScript オブジェクトを構築します。XML の場合は XMLDocument2 クラスからオブジェクトを作成し、続けて parseXML() メソッドを使用して inputs.sourceItem から JavaScript オブジェクトを構築します。この例では、item JavaScript オブジェクトが inputs.sourceItem から作成されています。
出力オブジェクトは自動的にスクリプトに渡されます。このスクリプトの目的は、outputs.targetObject にプロパティとプロパティ値を追加することです。通常、プロパティ値はストリームから解析されますが、ハードコードされた値や、ハードコードされた値と解析済みの値の組み合わせなど、任意の値にすることができます。この例では、outputs.targetObject.color_name と outputs.targetObject.color_rgb に、item オブジェクトの対応するプロパティの値が設定されています。
演習 (24/32)
この演習では、データストリームアクションの [解析] セクションを構成します。
質問:セパレーターステップの目的は何ですか?
回答:スプリッターステップ の目的は、Web サービス応答からレコードまたはデータを抽出することです。
演習のこのセクションでは、スクリプトを使用して、Web サービスの応答から個々の氷河に関するデータを抽出します。スクリプトを使用して次のデータを抽出します。
注意:すべての氷河について、すべての情報を入手できるわけではありません。たとえば、多くの氷河には、氷河 ID があっても名前がありません。
スクリプトから outputs.targetObject というオブジェクトが返されます。既存のスクリプトを使用すると、outputs.targetObject オブジェクトに次の 3 つのプロパティが含まれます。
[スクリプトパーサースクリプト] にロジックを追加して、output.targetObject オブジェクトに次の 2 つのプロパティを追加します。
課題ソリューション:
(function parse(inputs, outputs) { // Source item string is available in inputs.sourceItem. // Generate output by setting fields of outputs.targetObject. // // The structure of outputs.targetObject corresponds to the // structure defined in the Data Stream Action output. // Parse glacier record properties into the outputs.targetObject // that is passed to the Data Stream Action Outputs. var glacier_rec = JSON.parse(inputs.sourceItem); outputs.targetObject.id = glacier_rec.glacier_id; outputs.targetObject.name = glacier_rec.name; outputs.targetObject.country = glacier_rec.country; outputs.targetObject.latitude = glacier_rec.latitude; outputs.targetObject.longitude = glacier_rec.longitude; })(inputs, outputs);
記事 (25/32)
[出力] セクションには、[解析中] セクションで解析されたデータ変数が含まれています。これらの変数は、フロー内の他のアクションで使用できます。
[出力] セクションでは複合オブジェクトを定義します。オブジェクトとそのプロパティは、フロー内の他のアクションで使用できます。スクリプトパーサースクリプトテンプレートのコメントで説明されているように、outputs.targetObject は [出力] セクションで定義された最上位のオブジェクトにマッピングされます。
// outputs.targetObject の構造はデータストリームアクション出力で定義された構造に対応しています。
[出力] セクションで、[+ 出力を作成] ボタンをクリックします。[出力の作成] ボタンがない場合は、[出力を編集] ボタンをクリックします。
Action Output オブジェクトを構成します。
スクリプトパーサースクリプトの outputs.targetObject オブジェクトは、[アクション出力] の最上位オブジェクトに自動的にマッピングされます。この例では、outputs.targetObject が color_record オブジェクトにマッピングされています。
Action Output オブジェクト構造は、スクリプトパーサースクリプトで定義された outputs.targetObject 構造と一致する必要があります。
(function parse(inputs, outputs) { var item = JSON.parse(inputs.sourceItem); // You must create a color_name Action Output in the Outputs // section to match the outputs.targetObject data structure // from this script outputs.targetObject.color_name = item.name; // You must create a color_rgb Action Output in the Outputs // section to match the outputs.targetObject data structure // from this script outputs.targetObject.color_rgb = item.rgb; })(inputs, outputs)
スクリプトパーサースクリプトスクリプトで定義されたオブジェクト構造と一致させるには、[アクション出力] に同じプロパティと構造を持つオブジェクトが含まれている必要があります。この例では、スクリプトパーサースクリプトスクリプトによって作成されたオブジェクト構造に 2 つのプロパティが含まれています。
var color_record = { color_name: "colorValue", color_rgb: "rgbValue" };
Color record オブジェクトにプロパティを追加するには、 [子アイテムを追加 ] アイコン () をクリックします。
必要な数のプロパティを追加して、outputs.targetObject オブジェクトと同じデータ構造を [アクション出力] に作成します。[アクション出力] の名前を、[スクリプトパーサースクリプト] フィールドの outputs.targetObject オブジェクトのプロパティ名と一致させます。
演習 (26/32)
この演習では、[解析] セクションで解析された以下のデータ変数を含む複合オブジェクトを作成します。
Glacier record オブジェクトへ既に追加したプロパティをモデルとして、さらに 2 つのプロパティを追加します。このプロパティには、スクリプトパーサーのステップで解析された緯度と経度が保存されます。この 2 つのプロパティは必須ではありません。保存後に、[展開] アイコン () をクリックして、Glacier record オブジェクトのプロパティを表示する必要がある場合があります。
課題ソリューション:
演習 (27/32)
この演習では、[World Glaciers - LatLong] データストリームアクションをテストします。
記事 (28/32)
データストリームアクションを作成したら、アクションを公開してすべてのフローで使用できるようにします。[データストリームアクション] フォームヘッダーで [公開] ボタンをクリックします。
他のアクションと同じプロセスを使用して、フローにデータストリームアクションを追加します。
フローで、[アクション、フローロジック、またはサブフローを追加] リンクをクリックします。
データストリームアクションを選択します。
For Each ロジックは、データストリームアクション要求によって返される応答の各レコードに適用されます。ハードコードされた値または動的な値を使用して、データストリームアクションの各フィールドを構成します。
演習 (29/32)
この演習では、フローを作成します。次に、World Glacier - LatLong データストリームアクションを公開し、それをフローに追加します。フローの実行をテストします。
演習 (30/32)
この演習では、このモジュールで行った作業を GitHub リポジトリに保存します。World Graciers Spoke アプリケーションを保存するには、GitHub にリポジトリを作成し、World Graciers Spoke を新しいリポジトリに接続します。
注意:この演習のプロセスの詳細については、または GitHub アカウントで 2 要素認証を有効にしている場合は、『GitHub ガイド』を参照してください。
演習のこのセクションでは、新しいリポジトリを表示して、World Glaciers Spoke アプリケーションを新しいリポジトリにリンクし、コミットされたファイルを含むリポジトリを表示します。
記事 (31/32)
コアコンセプト:
記事 (32/32)
お疲れさまでした。「データストリームアクション」モジュールを完了しました。データストリームアクションへの関心に基づいて、さらに次のことも学んでいただけます。