ServiceNow¶
ServiceNow 通知先は、Guance のアラートを POST JSON として ServiceNow の受信エンドポイントに送信します。受信フローはアラートを解析した後、インスタンスのビジネスルールに従って Incident(インシデントチケット)を作成したり、その他の処理フローをトリガーしたりできます。
本記事では Scripted REST API を使用します。これは ServiceNow 管理者が作成するカスタム HTTP インターフェースです。受信スクリプトはアラートフィールドをチケットフィールドに変換し、チケット作成、重複排除、フロー制御、ステータス管理を制御します。
ServiceNow で受信エンドポイントを設定¶
API とリソースの作成には、ServiceNow の web_service_admin または admin ロールが必要です。呼び出しアカウントは、受信リソースの認証ポリシー、ACL(アクセス制御ルール)、および対象チケットテーブルの権限要件も満たす必要があります。
- All > System Web Services > Scripted REST APIs に移動し、API を作成して、名前と API ID を入力します。
- Resources 関連リストで New をクリックし、リソースを作成して POST を選択し、リソースパス(例:
/notification)を設定します。 application/jsonのリクエスト形式を保持または設定し、Script 内でrequest.body.dataを介してアラート JSON を読み取り、チケットフィールドのマッピングを完了します。以下の受信スクリプト例を参照できます。- リソースの Security で Requires authentication を有効にします。インターフェースの呼び出し権限を制限する必要がある場合は、Requires ACL authorization を有効にし、
REST_Endpointタイプの ACL を選択します。ACL フィールドを空欄にすると、親 API の ACL が使用されます。インターフェースの呼び出し権限と、対象チケットテーブルおよびフィールドの権限は個別に設定する必要があります。 - インスタンスのポリシーに従って認証情報を準備します。初回検証では、インスタンスで許可されている Basic 認証を使用し、呼び出しとチケット作成の権限を持つ統合アカウントおよびパスワードを準備できます。Bearer Token または API Key を使用することもできます。
- リソースを保存し、インスタンスのドメイン、名前空間、API ID、リソースパスを含む完全な HTTPS URL を取得します。
URL の構造は次のとおりです。version はその API でバージョンを使用する場合にのみ入力し、実際にリソースで生成されたアドレスを基準にします。
具体的な操作については、Scripted REST API、POST リソースの作成、リソース ACL の設定、API アクセスポリシー を参照してください。メニューと認証機能は、お客様のインスタンスのバージョンによって異なります。
受信スクリプト例¶
以下の例では、通知ごとに 1 件の Incident を作成します。title を短い説明に、message と通知 JSON 全体を説明に書き込み、ワークスペース、イベントコンテキスト、およびバックリンクを保持します。1 回の集約通知に含まれる複数のイベントは、同じチケット内に保存されます。
テストインスタンスでスクリプトを検証し、インスタンスの必須フィールド、フィールド長、アプリケーションのアクセス権限、およびビジネスルールに合わせて調整したうえで使用してください。集約通知が長い場合は、インスタンスのフィールド容量に応じて、チケット作成を分割するか、完全な内容を別途添付ファイルとして保存するかを選択します。テストリクエストのたびにチケット作成が実行されます。
(function process(request, response) {
var data = request.body.data;
if (!data || typeof data !== 'object' || Array.isArray(data)) {
response.setStatus(400);
response.setBody({ error: 'JSON object required' });
return;
}
var incident = new GlideRecordSecure('incident');
incident.initialize();
if (!incident.canCreate() || !incident.short_description.canWrite() ||
!incident.description.canWrite()) {
response.setStatus(403);
response.setBody({ error: 'Incident creation is not permitted' });
return;
}
incident.setValue('short_description', String(data.title || 'Monitoring notification'));
incident.setValue('description', String(data.message || '') +
'\n\n' + JSON.stringify(data, null, 2));
var sysId = incident.insert();
if (!sysId) {
response.setStatus(500);
response.setBody({ error: 'Incident creation failed' });
return;
}
response.setStatus(201);
response.setBody({ sys_id: String(sysId), number: incident.getValue('number') });
})(request, response);
この例では、GlideRecordSecure を通じて、現在の呼び出しユーザーの ACL に従ってチケットを作成します。受信スクリプトは、ビジネス要件に応じて events を反復処理して個別にチケットを作成したり、イベント識別子に基づいて既存レコードを更新したりすることもできます。
スクリプトインターフェースについては、ServiceNow Scripted REST の例、レコード作成権限 canCreate()、フィールド書き込み権限 canWrite()、RESTAPIResponse を参照してください。
Guance で通知先を作成¶
モニタリング > 通知先管理 > 通知先を作成 に移動し、ServiceNow を選択します。
- リストおよびアラートポリシーで通知先を識別するための名前を入力します。名前は現在のワークスペース内で一意であり、最大 200 文字です。
- Webhook アドレスに、上記 POST リソースの完全な HTTPS URL を入力し、最終的な受信アドレスを使用します。
- 認証方式で Basic を選択し、このエンドポイントで許可されているユーザー名とパスワードを入力します。または、受信側の設定に応じてその他の認証方式を選択します。
- 必要に応じてカスタムリクエストヘッダーを有効にし、受信側で追加的に要求されるキーと値を入力します。
- テスト通知を送信をクリックし、プレビューして送信を確認します。ServiceNow で受信リクエスト、スクリプト実行、および生成されたチケットを確認します。
- 操作権限を設定し、保存を確認します。
- アラートポリシーでこの通知先を選択し、送信するイベントのレベルと範囲を設定します。
認証方式とリクエストヘッダー¶
受信リソースの API アクセスポリシーは、選択した認証方式を許可している必要があります。プラットフォームは提供された認証情報に従ってリクエストを送信します。トークンの取得と更新はお客様が行います。
| 認証方式 | 入力内容 | 受信側の準備 |
|---|---|---|
| Basic | ユーザー名、パスワード | インスタンスで許可されている統合アカウントを使用します。ユーザー名は空でなく、コロンを含まないようにします。 |
| Bearer Token | Token | インスタンスの OAuth 設定に従って有効な Access Token を取得し、元の値を入力します。システムが Bearer プレフィックスを追加します。有効期限切れまたは失効後は速やかに更新します。 |
| API Key | リクエストヘッダー名、API Key | 下記の API Key 設定を完了します。リクエストヘッダー名はインスタンス設定に従って入力します(例: x-sn-apikey)。インスタンスがプレフィックスを要求する場合は、プレフィックスを含む完全な Key 値を入力します。 |
| 認証なし | — | 受信リソースの実際の認証要件に従ってカスタムリクエストヘッダーを設定します。 |
インスタンスが Basic Auth Restriction の適用を開始した後は、統合アカウントが許可条件を満たす必要もあります。たとえば、Web Services Access Only(Web サービスアクセスのみ)のアカウントに設定するか、snc_basic_auth_api_access ロールを付与します。管理者がインスタンスのポリシーに従って設定します。
API Key を使用する場合、設定担当者には api_service_admin、adaptive_auth_policy_admin ロールが必要です。インスタンスで API Key and HMAC Authentication プラグイン(com.glide.tokenbased_auth)を有効にし、次の設定を完了する必要があります。
- API Key のインバウンド認証 Profile を作成し、認証パラメーターでリクエストヘッダー方式(例:
x-sn-apikey: Auth Header)を選択します。 - REST API Key を作成し、呼び出しユーザーを関連付け、生成された Token をコピーします。
- API アクセスポリシーを作成して有効にし、その認証 Profile を対象 API の POST リソースおよび適用バージョンに関連付けます。
詳細な手順については、ServiceNow API Key 設定 を参照してください。Access Token の取得については、REST OAuth の例 を参照してください。Basic のインスタンス制限については、Basic authentication restriction を参照してください。
カスタムリクエストヘッダー名は大文字と小文字を区別せずに重複排除されます。選択した認証方式で生成されるリクエストヘッダーは、同名のカスタムヘッダーより優先されます。Content-Type は application/json に固定され、Accept のデフォルトは application/json です。API Key のリクエストヘッダー名には、Content-Type 以外の有効な名前を使用する必要があります。
認証情報の編集¶
同じアドレス、認証方式、および ID では、編集時にパスワード、Token、または API Key を空欄にすると元の値が保持され、新しい値を入力すると置き換えられます。アドレス、認証方式、ユーザー名、または API Key のリクエストヘッダー名を変更した後は、対応する認証情報を入力する必要があります。
カスタムリクエストヘッダーの値は暗号化して保存されます。上記の設定が同一である場合、保存済みの同名リクエストヘッダーの値を空欄にすると保持され、新しい値を入力すると置き換えられます。行を削除すると、そのヘッダーは削除されます。リクエストヘッダーを追加もしくは名前変更した場合、または上記の設定を変更した場合は、完全なリクエストヘッダー値を入力してください。
テストでは現在のフォームで有効な設定が使用されます。保存後は、以降のアラートで新しい設定が使用されます。
通知内容とアラート集約¶
ServiceNow 通知先は、シンプル HTTP リクエストのアラート集約形式を踏襲し、通常、ルール集約、インテリジェント集約の通知をサポートします。
| フィールド | 意味 |
|---|---|
title、message、status |
現在の通知のタイトル、本文、およびステータス。 |
events |
イベントリスト。通常アラートには 1 つのイベントが含まれます。集約アラートには対応する一連のイベントが含まれ、イベントコンテキストとバックリンクが保持されます。 |
workspace_uuid、workspace_name |
イベントが属するワークスペースの ID と名前。 |
monitor_checker_links |
ルール集約およびインテリジェント集約通知におけるモニター名とイベントリストへのリンク。 |
アラートポリシーによって、どのイベントが同じ通知を構成するかが決まります。通知内容の構築が完了すると送信が開始されます。明示的な遅延が設定された通知は、指定された時刻に従って送信されます。受信スクリプトは、上記のアラート構造に従ってフィールド変換を完了し、その後インスタンスのチケット処理ロジックを呼び出します。
テストとトラブルシューティング¶
テスト通知のフィールドは、受信側が実際に受信した JSON を基準にします。エンドポイントと認証のテストを完了した後、実際の通常アラートおよび集約アラートを使用して、フィールドマッピングと events の処理結果を検証します。
受信エンドポイントが HTTP 2xx を返しても、リクエストが完了したことのみを示します。ServiceNow の受信ログ、スクリプト実行、チケットフィールドも併せて確認し、受信フローが期待どおりの動作を完了したことを確認してください。
| 現象 | 確認方法 |
|---|---|
| 認証失敗またはアクセス権限なし | アカウント、トークン、または API Key の有効性、および対応する POST リソースのアクセスポリシーと ACL を確認します。 |
| リクエストは完了したが、チケットが生成されない | 受信スクリプト、対象テーブルの権限、インスタンスの必須フィールド、およびビジネスルールを確認します。 |
| チケット内容が欠落している | request.body.data のフィールドマッピングを確認し、実際の通常アラートと集約アラートでそれぞれ検証します。集約アラートでは events リストを処理する必要があります。 |
| 送信失敗 | 最終的な HTTPS アドレス、証明書、およびネットワーク接続性を確認します。HTTP 3xx リダイレクトは送信失敗として扱われます。 |