プロアクティブエンゲージメント API

  • リリースバージョン: Yokohama
  • 更新日 2025年01月30日
  • 所要時間：9分

    • プロアクティブエンゲージメント API は、デジタルエクスペリエンスの問題を作成するためのエンドポイントを提供します。

    この API はカスタムスクリプト REST API として使用できます。プロアクティブエンゲージメント (proactive-engagement) プラグインと sn_pren.experience_issue_create ロールが必要です。この API は sn_pren 名前空間に属しています。

    プロアクティブエンゲージメント API を使用して、ユーザーのインスタンスで問題が検出されたときにエクスペリエンスの問題を作成します。作成されたエクスペリエンスの問題は、ユーザーとのエンゲージメントを促進し、ユーザーが問題を自己解決するのに役立ちます。

    この API を使用するには、次のテーブルにレコードが入力されていることを確認します。

    • 問題レジストリテンプレート [sn_pren_issue_registry_template]
    • 問題レジストリ [sn_pren_issue_registry]
    • 解決 [sn_pren_resolution]
    • 通知コンテンツ [sn_pren_notification_content]
    • プロバイダー [sn_pren_provider]

    詳細については、「Proactive Engagement」を参照してください。

    プロアクティブエンゲージメント - CREATE /api/sn_pren/self_remediation/experience_issue/create

    ユーザーのエンドポイントで問題が検出されたときにエクスペリエンスの問題を作成します。エクスペリエンスの問題 [sn_pren_experience_issue] テーブルを更新します。

    URL 形式

    デフォルト URL: /api/sn_pren/self_remediation/experience_issue/create

    サポートされている要求パラメーター

    表 : 1. パスパラメーター
    名前 説明
    なし
    表 : 2. クエリパラメータ
    名前 説明
    なし
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    endpoint 必須。問題の詳細を検出するために使用される構成アイテム (CI) とユーザー情報。
    注:
    このオブジェクト内のすべてのパラメーターはオプションです。ユーザーまたはデバイスを識別するために、オブジェクト内で少なくとも 1 つのパラメーターを渡す必要があります。

    データタイプ: オブジェクト

    "endpoint": {
  "CI": "String",
  "email": "String",
  "user_id": "String",
  "user_name": "String"
}
    エンドポイント。CI 問題が検出された CI デバイスのSys_id。

    データタイプ：文字列

    テーブル:コンピューター [cmdb_ci_computer]
    endpoint.email 問題が検出されたユーザーのメールアドレス。

    データタイプ：文字列
    endpoint.user_id 問題が検出されたユーザーのSys_id。

    データタイプ：文字列

    テーブル:ユーザー [sys_user]
    endpoint.user_name 問題が検出されたユーザーのユーザー名。

    データタイプ：文字列

    テーブル:ユーザー [sys_user]
    experience_id 作成された問題に割り当てるユーザー定義 ID。

    データタイプ：数値

    デフォルト:ID が自動的に生成されます。
    input_parameters デバイスで実行されるアクションに渡すパラメーター。送信された入力パラメーターは、サブフロー、フローアクション、CI アクションなどの構成された解決修復アクションに渡されます。

    データタイプ: オブジェクト

    "input_parameters": {
  "process_id": "String"
}
    input_parameters.process_id 終了または再開するプロセスのSys_id。

    データタイプ：文字列
    investigative_details 電力使用効率 (PUE) の解決に失敗した場合の手動調査に役立つ可能性がある詳細情報。調査の詳細がインシデントにコピーされます。これは、PUE 解決が失敗した場合のフォールバックとして作成されます。

    データタイプ: オブジェクト

    "investigative_details": {
  "cpu_usage": "String",
  "processes_running": "String",
  "available_memory": "String"
  }
    investigative_details.cpu_usage デバイスの CPU 使用率。

    データタイプ: 数値 (文字列として解析)
    investigative_details.processes_running デバイスで実行されているプロセスの数。

    データタイプ: 数値 (文字列として解析)
    investigative_details.available_memory デバイス上の利用可能なメモリ。

    データタイプ: 数値 (文字列として解析)
    issue_code 必須。問題に関連付ける問題コード。問題コードは利用可能であり、インスタンスに展開されている必要があります。空または無効な問題が提供された場合、API はエラーを返します。

    データタイプ：文字列

    テーブル:問題レジストリ [sn_pren_issue_registry]
    プロバイダー 必須。プロバイダーの一意のコード。このコードは、インスタンスの sn_pren_provider テーブルの provider_code フィールドと一致する必要があります。

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「 サポートされている REST API ヘッダー」を参照してください。

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    Content-Type 要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。

    デフォルト： application/json

    ステータスコード

    この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

    ステータスコード 説明
    200 エクスペリエンスの問題が正常に作成されました。
    400 無効な要求。エンドポイントの詳細を入力します。

    空の endpoint オブジェクトが要求で送信されました。
    400 無効な問題コード。有効な問題コードを入力してください。

    要求で空の issue_code が送信されました。
    400 無効なプロバイダーです。有効なプロバイダーを指定してください。

    要求で空のプロバイダーが送信されました。
    400 問題コードまたはプロバイダーが無効です。有効な詳細を入力してください。

    インスタンスで問題を検出できません。issue_codeとproviderの詳細を確認します。
    400 問題コードに適切な解決策がありません。

    特定された問題に対して有効な解決策が PUE フレームワークで構成されていません。
    400 エンドポイントの詳細からユーザーを解決できませんでした。有効な詳細を入力してください。

    このエラーは、PUE フレームワーク ID が指定されたエンドポイントの詳細からユーザーを識別できない場合に返されます。
    400 指定されたユーザーの指定された問題コードで、エクスペリエンスの問題が解決されています。

    指定されたエクスペリエンスの問題は、現在進行中またはオープンステータスです。
    400 指定された experience_id の既存のエクスペリエンスの問題はまだ実行中かクローズされています。

    このエラーは、エクスペリエンスの問題がチェーンシナリオにある場合に発生します。たとえば、新しい issue_code キーが既存の experience_idとともに送信され、以前のエクスペリエンスの問題が実行中であるか、クローズ済みステータスである場合などです。

    このexperience_idのエクスペリエンスの問題はaction_wait前のexperience_idで新しいissue_codeを送信するためのステータスである必要があります。
    400 エクスペリエンスの問題の作成中にエラーが発生しました。

    これは技術的なエラーを示しています。

    応答本文のパラメーター (JSON または XML)

    名前 説明
    experienceId 作成されたエクスペリエンスの問題のエクスペリエンス ID。experience_id 要求パラメーターから生成されます。

    experience_id パラメーターが渡されない場合、結果の ID は常に作成されたレコードのsys_idになります。

    テーブル:エクスペリエンスの問題 [sn_pren_experience_issue]

    cURL 要求

    次の例では、ユーザー Abel Tuter のエクスペリエンスの問題を作成します。本文の問題コードにより、プロアクティブエンゲージメントは問題レジストリテンプレートから解決策を識別し、仮想エージェントを介してエンドユーザーとやり取りし、問題の自己解決を支援できます。

    curl  "http://instance.servicenow.com//api/sn_srf/self_remediation/experience_issue/create" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
--data “{
  "endpoint": {
    "CI": "d049b28e936aa1106f98f6db5cba10d5",
    "user_id": "62826bf03710200044e0bfc8bcbe5df1",
    "user_name": "abel.tuter",
    "email": ""
  },
  "issue_code": "100",
  "provider": "sn",
  "experience_id": "09ed4830f393739df33",
  "input_parameters": {
    "process_id": "10644"
  },
  "investigative_details": {
    "cpu usage": "78%",
    "processes running": "35",
    "available memory": "23%"
  }
}”\

    応答本文は、問題の作成が成功したことを示すエクスペリエンス ID を返します。

    { 
  "result": { 
    "experience_id": “09ed4830f393739df33”
  } 
}