記事 (1/18)
このモジュールでは、次のことを学習します。
記事 (2/18)
重要:この学習モジュールの内容は、Quebec ServiceNow リリース用に最後に更新されたもので、Rome リリースでは更新されていません。Rome リリースとこの学習モジュールのコンテンツとの間に違いが見られる場合があります。
Global アプリケーションは、アプリケーション作成の基になる概念とプロセスを紹介し、デモンストレーションするために、この学習モジュール全体で使用されます。受講者は Global アプリケーションを構築しません。
演習は、次の 3 つの方法で示されます。
記事 (3/18)
Web サービスにより、アプリケーションはネットワーク経由で他のソフトウェアアプリケーションに接続し、プロバイダー (サーバー) とコンシューマー (クライアント) の間で情報を交換することができます。
Web サービスコンシューマー (クライアント) が Web サービスプロバイダー (サーバー) に情報を要求します。Web サービスプロバイダーが要求を処理し、ステータスコードと応答本文を返します。応答本文が返されると、Web サービスコンシューマーは応答本文から情報を抽出し、抽出されたデータに対してアクションを実行します。
受信要求では、サードパーティアプリケーションが ServiceNow API を介してアクションを要求します。ServiceNow API の例は次のとおりです。
ServiceNow REST APIs の完全なセットは、docs.servicenow.com サイトで文書化されています。[次のトピック (Next Topic)] ボタンと [前のトピック (Previous Topic)] ボタンを使用すると、API 間を移動できます。
REST API 機能は、すべてのインスタンスでデフォルトで有効になっています。
記事 (4/18)
Web サービスとデータ連携する場合、開発者は次の情報を把握している必要があります。
ServiceNow の REST API Explorer は、ServiceNow インスタンスへの API 要求を作成してテストするためのアプリケーションです。
REST API Explorer は、rest_api_explorer ロールまたは admin ロールを持つユーザーが使用できます。REST API Explorer を開くには、Application Navigator で [REST] > [REST API Explorer] を開きます。
初めて REST API Explorer を起動する場合、ServiceNow のようこそ画面が表示されます。
REST API Explorer の構成要素は次のとおりです。
記事 (5/18)
REST API Explorer フォームの [要求を準備] セクションのフィールドは、選択されている名前空間、API 名、API バージョン、REST メソッドによって決まります。
集計 API の場合、使用できるメソッドは 1 つだけです。
REST API Explorer に、選択した項目に関する情報が表示されます。詳細については、REST API Explorer メニューの [API ドキュメント] メニューアイテムを選択してください。
記事 (6/18)
要求パラメーターは次の要素から構成されています。
パスパラメーターのリストは、エンドポイント URL によって異なります。パスパラメーターは、エンドポイント URL の中の中括弧で囲まれた部分です。要求が送信されたときに、パスパラメーターフィールドに設定された値がエンドポイント URL に挿入されます。
重要:要求によって参照されるテーブルがデータベースビューである場合、結果を返すメソッドは GET のみです。データベースビューは読み取り専用です。
要求パラメーターは、要求が送信されたときに REST API Explorer によってエンドポイント URL に追加されます。クエリパラメーターは、選択した API メソッドに固有のものです。
API のデフォルトのクエリパラメーターのセットが表示されます。クエリパラメーターを追加するには、[クエリパラメーターを追加] ボタンを使用して、新しいパラメーターをクエリに追加します。API のクエリパラメーターの完全なリストと詳細な説明については、REST API Explorer メニューの [API ドキュメント] メニューアイテムを選択してください。
要求ヘッダーは、要求と応答の形式を定義します。
[ヘッダーを追加] ボタンを使用して、要求にヘッダーを追加します。ServiceNow API の場合、次の 2 つのヘッダーパラメーターを追加すると便利です。
重要:要求ヘッダーでは、開発者が現在ログインしているユーザーとして要求を構成する必要があります。ユーザーは、要求されているレコードにアクセスする権限を持っている必要があります。権限がない場合、要求は拒否されます。
記事 (7/18)
クエリパラメーターには、次のようなさまざまなタイプの値を含めることができます。
sysparm_query や sysparm_having などの一部のクエリパラメーターは、エンコードクエリを値として受け入れます。エンコードクエリは、手動で簡単に作成することはできません。エンコードクエリの構文は文書化されていないため、ServiceNow でエンコードクエリを構築します。ServiceNow ブラウザーのメインウィンドウで、Application Navigator を使用して対象のテーブルのリストを開きます。リストを開くモジュールが存在しない場合は、Application Navigator のフィルターナビゲーターで「<table_name>.list」と入力します。
フィルターを使用してクエリ条件を作成します。
[実行] ボタンをクリックして、クエリを実行します。ブレッドクラムを右クリックして、[クエリのコピー] を選択します。
注意:コピーされたクエリには、右クリックした条件と左側のすべての条件が含まれます。クエリ全体をコピーするには、<右端の条件> を右クリックします。
REST API Explorer に戻り、エンコードクエリをクエリパラメーターに貼り付けます。
sysparm_group_by などの一部のクエリパラメーターは、フィールド名またはカンマで区切られたフィールド名のリストを受け入れます。開発者は、フィールドラベルではなくフィールド名を渡す必要があります。
スラッシュバケットからフィールドを選択するには、フィールドの [編集] ボタン () をクリックします。
フィールド名ではドット連結が許可されています (caller_id.title など)。
REST 呼び出しがテーブルから参照フィールドを返す場合、開発者は戻り値の形式を選択できます。
記事 (8/18)
REST メソッドを構成したら、[送信] ボタンをクリックして、要求を API に送信します。
REST API Explorer は、要求がサードパーティアプリケーションからのものであるかのように応答します。
記事 (9/18)
REST API Explorer は、開発者が指定した設定を使用して ServiceNow API に送信する要求を作成します。
[要求] セクションには、ServiceNow Web サービスに送信する HTTP メソッド / URI が表示されます。メソッドは、選択した API からのものです。パスパラメーター値は、要求を構成するときに設定されます。
クエリパラメーターは URI に追加されます。次の例では、スペースの制限により URI が切り捨てられています。REST API Explorer で完全な URI を表示するには、水平方向にスクロールします。
REST ヘッダーは、API 要求と応答に関連付けられたメタデータです。要求ヘッダー設定が要求に表示されます。
記事 (10/18)
ServiceNow API 応答は次の要素から構成されています。
ServiceNow API は、標準的な HTTP ステータスコードを返します。一般的には次のとおりです。
HTTP ステータスコードは、REST サービスプロバイダーとのやり取りを参照します。ステータスコードは、要求されたデータに関する情報は一切提供しません。データが返されない場合でも、REST トランザクション要求は正常に完了します。
[ヘッダー] セクションには、返されたヘッダーとその値が表示されます。
応答本文は、ServiceNow Web サービスプロバイダーから返されるデータオブジェクトです。応答本文は、選択した API によって異なります。この例では、集計 API は、重大または高の優先度を持つ過去 1 年間の未解決インシデントレコードの数を返します。結果は、[アサイン先] フィールドでユーザー別にグループ化されます。
Beth Anglin には、重大または高の優先度を持つ未解決のインシデントが過去 1 年間で 3 件あります。この場合、assigned_to フィールドに値 (sys_id) と display_value の両方が含まれていることに注意してください。
演習 (11/18)
この演習では、REST API Explorer を使用して ServiceNow テーブル API に対する要求を準備します。[簡単な説明] フィールドに「メール (email)」という文字列を含むすべてのアクティブなインシデントテーブルレコードを返す要求を作成します。API 要求もテストします。
注意:PDI が自動的に App Engine Studio を開く場合は、PDI にアクセスするために使用するユーザーロールを変更する必要があります。演習を完了するには、[管理者] ユーザーロールに切り替えます。
質問:[sysparm_fields] リストのフィールド名がスラッシュバケットで選択したものと異なるのはなぜですか?
回答:スラッシュバケットにはフィールドラベルが表示されます。[sysparm_fields] リストにはフィールド名が表示されます。
質問:この演習の準備セクションで、クエリによって返されるレコードの数を確認しました。この API 要求によって同じ数のレコードが返されると思いますか。理由を説明してください。
回答:REST API Explorer は、構成に応じて最大 10 件のインシデントレコードを返します。クエリが返すレコードが 10 件未満の場合、REST クエリはそのクエリのすべてのレコードを返します。クエリが 10 件を超えるレコードを返した場合、一部のレコードは表示されません。
質問:sysparm_exclude_reference_link を true に設定した場合、応答本文はどのように変更されましたか?
回答:返されるレコードオブジェクトの caller_id プロパティが、オブジェクトではなく文字列になりました。
質問:sysparm_fields クエリパラメーターに値がない場合、[インシデント] テーブルレコードのいずれかのフィールドが返されますか?その場合、どのフィールドですか?
回答:sysparm_fields クエリパラメーターに値がない場合、レコードのすべてのフィールドが返されます。
演習 (12/18)
この演習では、X-WantSessionDebug ヘッダーを [インシデント] テーブルの GET 要求に追加します。
記事 (13/18)
受信 API 要求にセキュリティを追加するための戦略は次のとおりです。
ユーザーレコードに [Web サービスへのアクセスのみ] オプションが設定されているユーザーは、ServiceNow UI にログインできません。このオプションでは、ユーザー資格情報を API 接続の許可にのみ使用できます。このオプションを設定するには、[ユーザー管理] > [ユーザー] モジュールを使用して編集するユーザーレコードを開きます。
API 要求ユーザーには、API 要求によって要求されたレコードにアクセスするために必要なロールが付与されている必要があります。
管理者は、テーブルへの Web サービスのアクセスを無効にすることができます。テーブルレコードで [アプリケーションアクセス] セクションを開き、[Web サービスでのやり取りを許可] オプションの選択を解除します。このオプションが選択されて (オンになって) いない限り、テーブルでは REST 要求が受け入れられません。このオプションを設定するには、[システム定義] > [テーブル] モジュールを使用して編集するテーブルレコードを開きます。
重要:REST API Explorer はこの設定を無視します。REST API Explorer は、[Web サービスでのやり取りを許可] オプションを無効にした状態でテーブルを操作できます。
記事 (14/18)
クロスオリジンリソース共有 (CORS) ルールは、特定の REST API エンドポイントにアクセスできるドメインを制御します。CORS ルールを作成するには、Application Navigator を使用して [システム Web サービス] > [REST] > [CORS ルール] を開きます。
この例では、リソース https://www.test-cors.org は GET メソッドを使用してのみテーブル API にアクセスできます。
ドメインを指定する場合、次のような多数の要件があります。
docs.servicenow.com サイトで CORS ドメインの要件の完全なリストを確認してください。
重要:CORS ルールは REST API Explorer ではテストできません。
記事 (15/18)
REST API Explorer は、ServiceNow API とデータ連携するためのコードサンプルを、一般的な複数の言語で作成します。
コードサンプルを作成するには、REST API Explorer のリンクをクリックします。
コピーするコードサンプルを強調表示するには、[スニペットの選択] ボタンをクリックします。
コードサンプルを強調表示した後、コードサンプルをクリップボードにコピーします。
すべてのコードサンプルで、本物ではない資格情報が使用されています。アプリケーションでスクリプトを使用して ServiceNow とデータ連携する前に、有効な資格情報を使用するようにコードを更新してください。
記事 (16/18)
ここでは、受信 REST データ連携についての理解度を確認できます。自分の進行状況を評価するには、次の質問が役立ちます。質問ごとに回答を決定し、質問の任意の場所をクリックして回答を表示します。
質問:正誤問題?受信 REST データ連携では、ServiceNow が Web サービスプロバイダーです。
回答:正解は正しいです。
質問:ServiceNow インスタンスに対する API 要求を作成してテストするために使用する ServiceNow のアプリケーションは次のどれですか?
回答:正解は 2. REST API Explorer です。
質問:REST API Explorer の [要求を準備] セクションで使用できるフィールドを決定する際に選択「しない」のは次のどれですか?
回答:正解は 1. パスパラメーターです。名前空間、API 名、API バージョン、メソッドを選択して、[要求を準備] セクションで使用できるフィールドを決定します。
質問:強調表示されたアイテムは、どの値タイプの例ですか?
回答:正解は 4. パスパラメーターです。
質問:正誤問題?すべてのクエリパラメーターは、エンコードクエリを値として受け入れます。
回答:正解は誤りです。クエリパラメーターには、エンコードクエリ、フィールド名、true/false/all など、さまざまなタイプの値を含めることができます。
質問:ServiceNow インスタンスに対する構成済みの Web サービス呼び出しをテストするプロセスについて説明しているのは次のうちどれですか。
回答:正解は 1 です。REST API Explorer は [送信] ボタンを使用してテストを開始します。
質問:一般に「成功」を意味する HTTP ステータスコードはどれですか?
回答:正解は 2. 2xx です。一般的には次のとおりです。
質問:応答のフォーマット方法のオプションは次のうちどれですか?複数の回答が正解の場合があります。
回答:正解は 1、3、4 です。
質問:受信 REST 要求にセキュリティを追加するための戦略は、次のうちどれですか?複数の回答が正解の場合があります。
回答:正解は 2、3、4 です。
質問:REST API Explorer は、次のどの言語のコードサンプルを作成しますか?複数の回答が正解の場合があります。
回答:すべて正解です。リストされている言語に加えて、REST API Explorer は ServiceNow スクリプトと Ruby でコードサンプルを生成できます。
記事 (17/18)
コアコンセプト:
記事 (18/18)
お疲れさまでした。「受信 REST データ連携」モジュールはこれで完了です。受信 REST への関心に基づいて、さらに次のことも学んでいただけます。