記事 (1/23)
このモジュールでは、次のことを学習します。
記事 (2/23)
重要:この学習モジュールの内容は、Quebec ServiceNow リリース用に最後に更新されたもので、Rome リリースでは更新されていません。Rome リリースとこの学習モジュールのコンテンツとの間に違いが見られる場合があります。
Global アプリケーションは、アプリケーション作成の基になる概念とプロセスを紹介し、デモンストレーションするために、この学習モジュール全体で使用されます。受講者は Global アプリケーションを構築しません。
実習では、IPLookup アプリケーションを開発します。
演習は、次の 3 つの方法で示されます。
IPLookup アプリケーションを使用すると、ユーザーは IP アドレスに関する情報を要求できます。
記事 (3/23)
Web サービスにより、アプリケーションはネットワーク経由で他のソフトウェアアプリケーションに接続し、プロバイダー (サーバー) とコンシューマー (クライアント) の間で情報を交換することができます。
Web サービスコンシューマー (クライアント) が Web サービスプロバイダー (サーバー) に情報を要求します。Web サービスプロバイダーが要求を処理し、ステータスコードと応答本文を返します。応答本文が返されると、Web サービスコンシューマーは応答本文から情報を抽出し、抽出されたデータに対してアクションを実行します。
ServiceNow は、サードパーティプロバイダーやその他の ServiceNow インスタンスからの Web サービスを消費できます。
サードパーティの Web サービスは、次のような情報を提供できます。
記事 (4/23)
ServiceNow は、REST を介して外部 Web サービスとやり取りする方法の詳細を REST メッセージレコードに保存します。REST メッセージレコードには次のものが含まれます。
送信 REST メッセージを使用すると、開発者は Web サービスをテストし、応答本文を表示できます。
送信 REST メッセージを構成してテストすると、任意のサーバーサイドスクリプトから呼び出すことができるようになります。
記事 (5/23)
送信 REST メッセージを作成するには、Application Navigator を使用して [システム Web サービス] > [送信] > [REST メッセージ] を開くか、Studio で REST メッセージアプリケーションファイルを追加します。
記事 (6/23)
Web サービスプロバイダーによって必要な認証のタイプは異なります。送信 REST では、次の認証形式がサポートされます。
一部の公開 Web サービスは、認証なしで制約のない情報を配布しています。認証を必要としない公開 Web サービスの場合は、送信 REST メッセージの [認証タイプ] フィールドを [認証なし] に設定します。
基本認証タイプは、ユーザー名とパスワードを Web サービスに渡します。基本認証が必要な Web サービスの場合は、送信 REST メッセージの [認証タイプ] フィールドの値を [基本] に設定してから、[基本認証プロファイル] を選択します。
基本認証プロファイルは、名前、ユーザー名、パスワードで構成されます。
Application Navigator に「sys_auth_profile_basic.list」と入力して、基本認証プロファイルを編集または新規作成します。
OAuth は、ユーザーにパスワードを指定せずに API へのアクセスを提供するインターネット標準です。OAuth のセットアップについては、RESTMessageV2 データ連携の OAuth2 認証の設定方法に関するブログ投稿を参照してください。
相互認証では、Web サービスプロバイダーとコンシューマーが通信する前に互いに認証を行う必要があります。相互認証は、アプリケーションレベルの認証である他の認証オプションとは異なり、プロトコル/ソケットレベルの認証です。相互認証は、他の認証メカニズムと組み合わせて使用できます。相互認証を有効にするには、[相互認証を有効にします] オプションを選択してから、プロトコルプロファイルを選択します。
相互認証プロファイルを定義するには、Application Navigator を使用して [システムセキュリティ] > [プロトコルプロファイル] を開きます。
このオプションは、MID Server を使用する Web サービスでは使用できません。
演習 (7/23)
この演習では、IPLookup と呼ばれるアプリケーションを作成します。ipinfo.io 公開 Web サービスを使用するこのアプリケーションに、送信 REST メッセージも追加します。
注意:PDI が自動的に App Engine Studio を開く場合は、PDI にアクセスするために使用するユーザーロールを変更する必要があります。演習を完了するには、[管理者] ユーザーロールに切り替えます。
ipinfo.io にアクセスし、何が API に送信され、何が返されるのかについて、ドキュメントを確認してください。
注意:ipinfo.io 公開 Web サービスは認証を必要としません。
記事 (8/23)
HTTP メソッドは、情報の取得やレコードの更新など、リソースに対して実行するアクションを定義します。新しい REST メッセージが初めて保存されるときに、ServiceNow は REST メッセージの情報に基づいて HTTP メソッドを作成します。
HTTP メソッド名をクリックして編集するメソッドを開くか、[新規] ボタンをクリックして HTTP メソッドを作成します。利用可能な HTTP メソッドは次のとおりです。
記事 (9/23)
HTTP メソッドのエンドポイントを構成するには、Web サービスプロバイダーの API ドキュメントを参照してください。たとえば、IEX Cloud の API リファレンスには、API のベース URL が記載されています。
iextrading.com の Quote API の場合、ドキュメントに次の構文が記載されています。
送信 REST メッセージの有用性を高めるには、会社の記号をエンドポイントにハードコーディングするのではなく、記号を動的にします。エンドポイントの動的な部分を ${ } で囲みます。
記事 (10/23)
デフォルトの場合、HTTP メソッドは送信 REST メッセージ (親) から認証設定を継承します。親の認証と異なる場合は、認証タイプを変更します。メソッドの認証フィールドは、送信 REST メッセージのフィールドと同じです。
消費する Web サービスが社内ネットワーク上にあり、インターネットを使用してアクセスできない場合は、MID Server を使用して Web サービスに接続します。[MID Server を使用] フィールドで MID Server を選択します。
[HTTP ヘッダー] 埋め込みリストの行をクリックして、ヘッダーの [名前] と [値] を定義します。サポートされるヘッダーや必要なヘッダーは、Web サービスプロバイダーによって決定されます。HTTP ヘッダーフィールドのリストについては、HTTP ヘッダーフィールドのリストを参照してください。
HTTP クエリパラメーターを定義するには、[新規行を挿入...] というテキストをダブルクリックし、パラメーターの [名前] と [値] を指定します。定義するクエリパラメーターについては、API のドキュメントを参照してください。たとえば、IEX Cloud のサイトでは、Quote API のオプションのクエリパラメーターを定義します。
IEX Cloud のサイトでは、API 要求に使用する空きトークンも必要です。このトークンはクエリパラメーターとして渡されます。
クエリパラメーターをエンドポイントに追加します。
HTTP クエリパラメーターは、実行時にエンドポイントに追加されます。構文は「エンドポイント + ? + クエリパラメーター」です。
演習 (11/23)
この演習では、ipinfo.io 公開 Web サービスから IP アドレス情報を取得するように HTTP メソッドを構成します。
注意:ipinfo.io Web サービスは、認証、ヘッダー、クエリパラメーターを必要としません。
記事 (12/23)
送信 REST メッセージの HTTP メソッドを構成したら、テストを実行して、要求が有効であり、応答が期待どおりに返されることを確認できます。
HTTP メソッドで定義された変数には、テストの実行のための値が必要です。[変数の自動生成] 関連リンクをクリックして、変数を [代替変数] リストに自動的に追加します。[代替変数] リストに自動的に追加されない変数の場合は、[新規] ボタンをクリックして変数を手動で定義します。
HTTP メソッドをテストするには、[テスト] 関連リンクをクリックします。
テスト結果は [テスト実行] 関連リストで確認できます。
[応答] で、予期したデータが受信されたことを確認します。
注意:HTTP ステータスはトランザクションのステータスを示すものであり、目的の応答が受信されたことを示すものではありません。
演習 (13/23)
この演習では、GetIPInfo HTTP メソッドをテストし、テスト結果を確認します。
選択した戦略を使用して IP アドレスを決定します。IP アドレスの検索方法がわからない場合は、WhatIsMyIPAddress または IPChicken をお試しください。IP アドレスをメモしておきます。
ここでの課題は、GetIPInfo HTTP メソッドを変更して、このメソッドが ipinfo.io API から特定のフィールドのデータを要求できるようにすることです。『ipinfo.io 開発者ガイド』の応答のフィルタリングに関するセクションを参照してください。GetIPInfo HTTP メソッドは、org、city、geo、または json という値を受け入れる必要があります。[テスト] 関連リンクを使用して、ソリューションをテストします。
課題ソリューション:
記事 (14/23)
REST HTTP メソッドをデバッグするときに最初に確認するのは、テスト結果ページです。示されている例では、[HTTP ステータス] に、エンドポイントが見つからなかったことを示す 404 が返されています。[応答] には、エラーの原因に関する詳細情報が示されています。
より詳細なデバッグが必要な場合は、送信 HTTP 要求のシステムログを使用します。まず、ログに含める情報の量を設定します。HTTP メソッド定義の [HTTP ログレベルを設定] 関連リンクをクリックして、ログレベルを指定します。
ログレベルを設定した後、再度テストしてログを生成します。
Application Navigator を使用して、[システムログ] > [送信 HTTP 要求] を開きます。
この例は [要求] タブを示していますが、デバッグ対象によっては他のタブの方が便利な場合があります。
演習 (15/23)
この演習では、GetIPInfo HTTP メソッドのログレベルを設定し、送信 HTTP 要求のシステムログを確認します。
記事 (16/23)
ほとんどの場合、送信 REST メッセージのメソッドで [テスト] 関連リンクを使用して API を呼び出すことは実用的ではありません。HTTP メソッドを構成し、それが期待どおりに機能することを確認した後の最後の開発ステップは、サーバーサイドスクリプトからメソッドを実行することです。
[スクリプト使用のプレビュー] 関連リンクは、API を呼び出すサーバーサイド JavaScript コードスタブを生成します。
RESTMessageV2 API は、JavaScript を使用して送信 REST メッセージを送信します。
サンプルスクリプトでは、パラメーター名とハードコードされた値を使用して .setStringParameterNoEscape メソッドが渡されます。スクリプトを実装する場合、通常、パラメーターの値は動的に設定されます。例を次に示します。
r.setStringParameterNoEscape('symbol',current.company_ticker);
サンプルスクリプトの構文 sn_ws.RESTMessageV2() は、ServiceNow Express の他のサーバーサイドスクリプトが GlideRecord クラスを表現する場合と同じ方法で RESTMessageV2 を表現しますが、例外があります。GlideRecord クラスは ServiceNow グローバル名前空間の一部であり、スクリプトで名前空間を修飾する必要はありません。
var myObj = new GlideRecord('table_name');
RESTMessageV2 API は sn_ws (Web サービス) 名前空間の一部です。メソッドはすべてのスコープにアクセスできますが、名前空間を先頭に追加せずに RESTMessageV2 を表現しようとすると、グローバル名前空間に API が見つからないためエラーが返されます。名前空間を先頭に追加することで、ServiceNow に API の場所を通知できます。
記事 (17/23)
[スクリプト使用のプレビュー] ページのサンプルスクリプトには、応答本文と HTTP ステータスコードを取得するコードが含まれています。
var response = r.execute(); var responseBody = response.getBody(); var httpStatus = response.getStatusCode();
[スクリプト使用のプレビュー] スクリプトには、応答からデータを抽出するためのサンプルコードは含まれていません。responseBody 変数には、応答が文字列として含まれています。substring()、substr()、indexOf() などの JavaScript 文字列メソッドを使用して、responseBody 変数からデータを抽出します。
json 応答を操作する場合は JSON API を使用します。これにより、JSON フォーマットの文字列が JavaScript オブジェクトに変換されます。グローバルスコープで作業する場合、次のメソッドを使用できます。
プライベートスコープ対象アプリケーションで作業する場合、次のメソッドを使用できます。
これらのメソッドのその他の使用例については、JSON API ドキュメントを参照してください。
プライベートスコープ対象アプリケーションで XML 応答を操作する場合は、XMLDocument2 API を使用して、応答本文からデータを抽出します。
注意:示されている XML の例はデモンストレーション用です。IEX Cloud API の実際のデータに基づくものではありません。
演習 (18/23)
この演習では、レコード内の IP アドレス値に基づいて IPInfo 送信 REST メッセージを呼び出すスクリプトを作成します。Web サービス応答からのデータを解析して、レコードの [市区町村] フィールドの更新も行います。
開発者向けのヒント:Web サービスを呼び出すビジネスルールは非同期である必要があります。
注意:この演習では、エンドポイントの 2 番目のパラメーターを specific_field と呼びます。
記事 (19/23)
一般的な送信データ連携の場合、開発者はこのモジュールに示されている方法で送信 REST メッセージを定義します。送信 REST メッセージの利点は、フォームベースの UI を使用して API インタラクションを構成、テスト、デバッグできることです。
一部の開発者は、送信 REST メッセージを作成せずにデータ連携全体をスクリプト化することを好みます。示されているスクリプトは、送信 REST メッセージを使用せずに iextrading.com Stock Quote API とのインタラクションを定義しています。
// Create an empty RESTMessageV2 object var getQuote = new sn_ws.RESTMessageV2(); // Set the endpoint getQuote.setEndpoint('https://cloud.iexapis.com/v1/stock/${symbol}/quote'); // Set the HTTP method (get, post, put, patch, delete) getQuote.setHttpMethod('get'); // Set HTTP Query Parameters getQuote.setQueryParameter('displayPercent','true'); getQuote.setQueryParameter('token','INSERT_TOKEN_HERE'); // Set values for endpoint variables getQuote.setStringParameterNoEscape('symbol', current.short_description);
RESTMessageV2 API で REST インタラクションをスクリプト化する際に有用なメソッドとして、他に次のようなものがあります。
メソッドの完全なリストについては、RESTMessageV2 API のドキュメントを参照してください。
演習 (20/23)
GitHub リポジトリを使用すると、開発者は個人開発者インスタンス (PDI) の外部で完了した作業を保存できます。後で取得できるように作業を保存するには、ソースコントロールにリンクします。
この演習では、GitHub に新しい IPLookupApp リポジトリを作成し、IPLookupApp アプリケーションを新しいリポジトリに接続して、このモジュールで完了した作業内容を保存します。
記事 (21/23)
ここでは、送信 REST データ連携についての理解度を確認できます。自分の進行状況を評価するには、次の質問が役立ちます。質問ごとに回答を決定し、質問の任意の場所をクリックして回答を表示します。
質問:ServiceNow の送信 REST データ連携とは何かを最も的確に説明している文は次のどれですか?複数の回答が正解の場合があります。
回答:すべての応答が送信 REST データ連携の例です。送信と受信の両方のデータ連携が含まれているため、2 番目の選択肢は特殊です。
質問:REST メッセージレコードの構成に使用される情報で「ない」ものは次のうちどれですか?
回答:正解は 1 です。HTTP メソッドは、Web サービスへの REST 呼び出しを行うために使用される関連レコードです。
質問:REST メッセージレコードでサポートされている認証メソッドは次のうちどれですか?複数の回答が正解の場合があります。
回答:正解は 1、3、5 です。一部の Web サービスではクエリパラメーターとして渡されるトークンを使用しますが、クエリパラメーターは HTTP メソッドレコードで構成されます。基本認証ではユーザー名とパスワードを使用しますが、[ユーザー名とパスワード] は選択可能な認証オプションではありません。
質問:利用可能な HTTP メソッドで「ない」ものは次のどれですか?
回答:正解は 4 です。PATCH は 5 番目の HTTP メソッドです。
質問:収益に関する IEX Cloud API のドキュメントを確認してください。次のうち、有効な HTTP メソッドのエンドポイントはどれですか?複数の回答が正解の場合があります。
回答:正解は 2、4、5 です。API に記述されているパスパラメーター {symbol}、{last}、{field} は、エンドポイントで変数にするために ${} 表記で構成する必要があります。エンドポイントにアクセスするには、エンドポイントの値に完全な URL が必要です。5 番目の選択肢は記号に静的な値を使用しています。これは有効ですが、単一の会社の収益の詳細を取得する場合にのみ役立ちます。
質問:正誤問題?クエリパラメーターは、実行時にエンドポイントの値に追加される名前と値のペアです。たとえば、名前が「last」で値が「2」のクエリパラメーターは、https://cloud.iexapis.com/stable/stock/$\{symbol\}/earnings?last=2 として収益のエンドポイントに追加されます。
回答:正解は正しいです。クエリパラメーターは、実行時にエンドポイントに追加されます。
質問:HTTP ログの作成に使用された HTTP ログレベルは次のどれですか?
回答:正解は 2 です。[なし] および [デバッグ] は HTTP ログレベルではありません。[昇格] には要求ヘッダーの詳細が含まれます。[すべて] には要求ヘッダーと要求本文の詳細が含まれます。
質問:REST メッセージメソッドを実行する方法は次のうちどれですか?複数の回答が正解の場合があります。
回答:正解は 1 と 3 です。REST メッセージのメソッドは、スクリプトからテストおよび実行できます。
質問:開発者が REST Web サービスを呼び出した後、応答本文からデータを抽出する方法を教えてください。複数の回答が正解の場合があります。
回答:正解は 2 と 3 です。JSON API または XMLDocument2 API を使用して、返されたフォーマットから応答本文を変換します。
質問:正誤問題?REST メッセージレコードは、外部 REST Web サービスとやり取りするために必要です。
回答:正解は誤りです。開発者は RESTMessageV2 API を使用して、REST メッセージレコードなしでデータ連携全体をスクリプト化できます。
記事 (22/23)
コアコンセプト:
記事 (23/23)
お疲れさまでした。「送信 REST データ連携」モジュールはこれで完了です。送信 REST への関心に基づいて、さらに次のことも学んでいただけます。