ブログ

  1. ホーム
  2. ブログ一覧
  3. 外部システムとのAPI連携！RESTメッセージの使い方

外部システムとのAPI連携！RESTメッセージの使い方

技術

連携 Scripting

この記事は ServiceNow Advent Calendar 2024 の12月15日分の記事として執筆しています。
ServiceNow Advent Calendar 2024

社内業務に関するシステムを一元化して運用・管理できるクラウドサービス「ServiceNow」。
株式会社ＫＹＯＳＯでは、これまでの豊富な運用経験をもとに、ServiceNowの企画立案から運用・保守、内製化までトータルでサポートしています。

この度、弊社ServiceNow環境で外部システムとのREST API連携を検証しました。
このブログでは、REST APIを使った外部データの取得と、取得したデータを使用しレコードを作成する方法を紹介します。

REST APIとは

REST API は、Webサービスを構築するための設計原則に基づいたAPI（アプリケーション・プログラミング・インターフェース）の一種です。Web API の構築方法に関するルールとガイドラインの集まりです。モバイルアプリケーションやWebアプリケーションのバックエンドサービスなど、多くのシステムで採用されています。

また、ServiceNow社では以下のように言及しています。

REST(REpresentational State Transfer) は、Web上のコンピューターシステム間の標準を提供し、相互の通信を容易にするシンプルなステートレスアーキテクチャです。

Now Platformは、デフォルトで有効になっているさまざまなREST APIを提供します。これらの APIには、アプリケーション内のさまざまなServiceNow機能とやり取りする機能があります。このような機能には、既存のテーブルでの作成、読み取り、更新、削除 (CRUD) 操作 (テーブル API)、MetricBaseデータベースに対するデータの挿入、情報の取得、変換の実行 (MetricBase時系列API)、およびその他多くの機能があります。


ServiceNowより

今回私が行った検証は、
外部システムにGETのHTTPメソッドを送り、取得したデータを用いて2種類の方法でカスタムレコードを作成する、といった内容になります。

検証環境について

使用した環境、ツールは以下になります。

ServiceNow環境

  • 作成　・・・・・・　弊社デモインスタンス
  • バージョン　・・・　WashingtonDC
  • 操作　・・・・・・　System Administrator (admin)　

使用ツール

ServiceNow機能

  • RESTメッセージ
  • スケジュール済みジョブ
  • Flow Designer

検証内容

検証には3つのストーリーを作成しました。

  1. RESTメッセージ、HTTPメソッドを作成する。
    外部システムからデータを取得する。
  2. 作成したRESTメッセージをスケジュール済みジョブで呼び出す。
    取得したデータを用いてカスタムレコードを作成する。
  3. 作成したRESTメッセージをFlow Designerで呼び出す。
    取得したデータを用いてカスタムレコードを作成する。

イメージ画像

検証手順：ストーリー①

ストーリー①ではServiceNowの機能である「RESTメッセージ」を使用し、
Open Weatherからデータを取得します。

Open Weatherの設定

まずはアカウントを作成し、APIキーを取得します。
そしてログインしたら「API keys」からAPIキーを確認します。
このキーをREST メッセージのHTTPメソッドで使用します。

REST メッセージの作成

RESTメッセージは、ServiceNowインスタンスが外部システムやサービスと通信するためのREST APIリクエストを作成、送信するための機能です。
また、RESTメッセージ内で作成するHTTPメソッドごとに具体的なAPIリクエストを定義します。

アプリケーションナビゲーターから、
[すべて] > [システムWEBサービス] > [アウトバウンド]  > [REST メッセージ] を選択し、
新規作成します。

RESTメッセージには以下のように設定します。

※項目の説明
名前：適当な名称を付ける
アクセス可能：すべてのアプリケーションスコープ」(デフォルト)
→実務で使用する場合は用途によって変更する必要がある。
RESTエンドポイント：http://api.openweathermap.org/data/2.5/weather
→ベースとなるURLを記述する。

先ほど取得したAPIキーはこの後のHTTPメソッドで使用するので、認証タイプについては「認証なし」で設定します。

保存すると「Default GET」と名前の付いたHTTPメソッドが自動作成されています。

HTTPメソッドの作成

「Default GET」のHTTPメソッドを編集または削除後新規作成して、Open Weatherから現在の天気を取得するHTTPリクエストを作成します。
以下のように設定します。

※設定する項目とその説明
名前：適当な名称を付ける
HTTPメソッド：GET(デフォルト)
→今回はデータを取得するのでGETを設定。

RESTエンドポイントに記入しているのは現在の天気を取得するリクエストです。
以下のようにパラメータを付与したURLで、指定した都市の現在の天気を取得するAPIをコールします。

詳しい説明はこちら(公式サイト)

http://api.openweathermap.org/data/2.5/weather?q=${city}&appid=${key}&lang=ja&units=metric

一旦ここまでで保存を行い、ページ下部「関連リンク」の「変数の自動設定」をクリックします。
すると、以下のように「REST メッセージ関数パラメーター」タブにエンドポイント内の${}で囲まれたcityとkeyが設定されます。
cityには「Tokyo,JP」と、keyには取得したAPIキーを記入します。

ここまでの内容を保存し、「関連リンク」の「テスト」をクリックします。
正しく設定できていれば以下のように現在の天気の情報を取得することができます。
HTTPステータスが200で、正しい内容が記載されていれば大丈夫です。

<応答内容>

{"coord":{"lon":139.6917,"lat":35.6895},"weather":[{"id":803,"main":"Clouds","description":"曇りがち","icon":"04n"}],"base":"stations","main":{"temp":8.01,"feels_like":4.66,"temp_min":7.36,"temp_max":8.79,"pressure":1021,"humidity":83,"sea_level":1021,"grnd_level":1019},"visibility":10000,"wind":{"speed":6.17,"deg":330},"clouds":{"all":75},"dt":1732091953,"sys":{"type":2,"id":268395,"country":"JP","sunrise":1732051327,"sunset":1732087913},"timezone":32400,"id":1850144,"name":"東京都","cod":200}

これでRESTメッセージを使用し、外部システムからデータを取得することが可能になりました。

検証手順：ストーリー②

ストーリー②ではServiceNowの機能である「スケジュール済みジョブ」を作成し、ストーリー①で作成したRESTメッセージ、HTTPメソッドを呼び出します。
取得した天気の情報を用いてカスタムレコードを作成します。

カスタムレコードは事前に以下のように作成しています。

  • ラベル：REST API連携検証テーブル
  • 追加フィールド
    ラベル：天気　タイプ：文字列
    ラベル：都市　タイプ：文字列

スケジュール済みジョブの作成

スケジュール済みジョブでは決まった時間にスクリプトを実行することが可能です。(今回この機能は使用しません)
月初や週末など決まった時間に必要なデータを収集したい場合に便利な機能になっています。
アプリケーションナビゲーターから[すべて] > [システム定義] > [スケジュール済みジョブ]  を選択し、新規作成します。

スケジュール済みジョブは以下のように設定します。

※設定する項目とその説明
名前：適当な名称を付ける
アクティブ：チェック
→チェックしないと実行タイミングの設定が一部非表示となるので注意。
実行：日次(デフォルト)
→「今すぐ実行」ボタンでテストするのでどの値でもよい。今回は日次の12時で設定。

スクリプトは以下のように設定します。

try {
    // RESTメッセージのHTTPメソッドの呼び出し
    var r = new sn_ws.RESTMessageV2('検証_天気予報', 'Tokyo_Weather');
    // エンドポイント内の変数を設定
　　// 記述の必要はないがスクリプト内でも変更できる
    r.setStringParameterNoEscape('city', 'Tokyo,JP');
    r.setStringParameterNoEscape('key', ここにはAPIキーが入ります);
    // HTTPメソッドの実行
    var response = r.execute();
    var responseBody = response.getBody();
    var httpStatus = response.getStatusCode();
    var jsonArray = JSON.parse(responseBody);
　　// レコードの作成
    var record = new GlideRecord('u_rest_api_kennsyou');
    record.initialize();
    record.setValue('city', jsonArray.name);
    record.setValue('weather', jsonArray.weather[0].description);
    // 挿入結果
    var insert_result = record.insert();
    // 挿入結果により、成功または失敗を判定する
    if (insert_result) {
        gs.info('挿入が成功しました');
    } else {
        gs.info('挿入が失敗しました' + ' city=' + jsonArray.name + ' weather=' + jsonArray.weather[0].description);
    }
} catch (ex) {
    var message = ex.message;
}

ここまでで保存し、右上の「今すぐ実行」をクリックします。
正しく設定できていれば、レコードが挿入されています。

これでスケジュール済みジョブでRESTメッセージを呼び出し、取得した情報を用いてレコードを作成することが可能になりました。

検証手順：ストーリー③

ストーリー③ではServiceNowの機能である「Flow Designer」でカスタムレコードを作成するフローを作成します。
まずはHTTPメソッドを呼び出すフローアクションを作成します。

フローアクションの作成

1.適当な名前をつけ、フローアクションを作成

2.「入力」の設定

HTTPメソッドで設定した「API key」と「都市」という変数を設定します。

3.スクリプトstepの作成

アクションアウトラインから「新しいステップを追加」をクリックし、スクリプトを選択します。

4.スクリプトstepの設定：入力変数

入力変数「key」「city」を作成します。
「値」には2で作成した「API key」「都市」をデータピルピッカーからドラッグします。

5.スクリプトstepの設定：出力変数

スクリプトの前に出力変数を設定します。
以下のように設定し、スクリプトの中で変数にデータを入れます。

レコード作成に必要なものは「都市」と「天気」です。
「メッセージ」と「ステータスコード」はテスト時の判定として作成しています。

6.スクリプトstepの設定：スクリプト

スクリプトは以下のように設定します。

(function execute(inputs, outputs) {
try { 
 // RESTメッセージのHTTPメソッドの呼び出し
 var r = new sn_ws.RESTMessageV2('検証_天気予報', 'Tokyo_Weather');
 // エンドポイント内の変数を入力変数から格納
 r.setStringParameterNoEscape('city', inputs.city);
 r.setStringParameterNoEscape('key', inputs.key);
 // HTTPメソッドの実行
 var response = r.execute();
 var responseBody = response.getBody();
 var jsonArray = JSON.parse(responseBody);
 // 出力変数に格納
     outputs.message = responseBody
     outputs.code = response.getStatusCode();
     outputs.city = jsonArray.name
     outputs.weather = jsonArray.weather[0].description
}
catch(ex) {
 var message = ex.message;
}
})(inputs, outputs);

基本はストーリー②で記述した内容と同じになっています。
変更点としては以下の３点です。

  • レコード作成の箇所を省いている。(フロー内のアクションで実行するため)
  • エンドポイント内の変数を入力変数から格納している。
  • 出力変数に必要な値を格納している。

また、入力変数から取得した値は「inputs.変数」、出力する変数は「outputs.変数」と記述することにも注意が必要です。

7.「出力」の設定

「都市」「天気」「メッセージ」「ステータスコード」を作成します。
5で作成した対応する出力変数をデータピルピッカーからドラッグします。

8.フローアクションのテスト

ここまで設定が出来たらテストを行います。
上部の「テスト」ボタンをクリックして必要な値を入力します。

「出力データ」に正しく値が取得できていることが確認できました。

ここまでの設定を保存し、必ず「公開」ボタンをクリックします。
これをしないとフロー作成時にこのアクションが選択できません。

フローの作成

アクションが正しく作成できたので、フローを作成します。
適当な名前をつけて作成します。

9.トリガーの設定

トリガーを設定します。
今回はカスタムレコードが作成できることが確認できればよいので特に指定はないですが、日次で16時に動くよう設定します。

10.アクションの設定：作成したフローアクションの設定

「アクション、フローロジック、またはサブフローを追加」をクリックし、先ほど作成したフローアクションを追加します。
左の「インストールされたスポーク」から「Global」を選択し先ほど作成したアクションを選択します。

「API key」「都市」を記入します。

11.アクションの設定2：カスタムレコード作成

10のアクションの下にさらにアクションを追加します。
「ServiceNow Core」から「レコードの作成」を選択します。

以下のように設定します。

12.フローのテスト

ここまでの設定が正しく行われていればレコードが作成されるのでテストを行います。
右上のテストボタンをクリックします。
アクションと違い入力は必要ないのでそのまま実行します。
テスト結果でレコードが無事に作成されていることが確認できました。

最後に

いかがでしょうか。
ここまで読んでいただきありがとうございます。
このようにRESTメッセージで外部データを取得し、取得したデータを用いて2種類の方法でカスタムレコードを作成しました。
外部データを取得したいという要件はよくあると思いますので、この検証が何かの役に立てれば幸いです。

最後まで閲覧いただき、ありがとうございました。
あなたにとって有益な情報を提供できたのであれば、大変嬉しく思います。

参考サイト

投稿者プロフィール

M. O
M. O
2023年に中途入社。
ServiceNowのインシデント管理導入、スクリプト開発などを担当しています。

保有資格
- ServiceNow Certified System Administrator
- ServiceNow Certified Application Developer
- ServiceNow Certified Implementation Specialist - IT Service Management

カテゴリー

タグ一覧

目次

カテゴリー

タグ一覧

※ServiceNow®は、米国および/またはその他の国における ServiceNow, Inc.の商標または登録商標です

TOP