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

  • リリースバージョン: Xanadu
  • 更新日 2024年08月01日
  • 所要時間：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)
    名前 Description (説明)
    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 必須。問題に関連付ける問題コード。問題コードが利用可能であり、インスタンスに展開されている必要があります。問題レジストリ [sn_pren_issue_registry] テーブルにあります。空または無効な問題が指定された場合、API はエラーを返します。

    データタイプ：文字列
    プロバイダー 必須。プロバイダーの一意のコード。このコードは provider_code インスタンス sn_pren_provider テーブルのフィールドと一致する必要があります。

    データタイプ：文字列

    ヘッダー

    次のリクエストや応答ヘッダーは、この 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で新しいissue_codeを送信するには、このexperience_idのエクスペリエンスの問題がaction_waitステータスである必要があります。
    400 エクスペリエンスの問題の作成中にエラーが発生しました。

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

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

    名前 Description (説明)
    experienceId 作成されたエクスペリエンスの問題のエクスペリエンス ID。experience_id 要求パラメーターから生成されます。エクスペリエンスの問題は、エクスペリエンスの問題 [sn_pren_experience_issue] テーブルに作成されます。

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

    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”
  } 
}