予測インテリジェンス API

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

    • Predictive Intelligence API は、1 つ以上の入力フィールドとトレーニング済みソリューションに基づいてフィールド値を予測するエンドポイントを提供します。

    この API は、予測インテリジェンス (com.glide.platform_ml) プラグインが有効になっている場合にのみ使用できます。

    予測インテリジェンス - GET /agent_intelligence/solution/{solution_name}/prediction

    特定のソリューションを使用して出力フィールド値を予測します。

    URL 形式

    デフォルトの URL：/api/now/agent_intelligence/solution/{solution_name}/prediction

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

    表 : 1. パスパラメーター
    名前 説明
    solution_name 予測に使用するソリューションの名前。たとえば、ml_incident_categorization などです。

    データタイプ：文字列
    表 : 2. クエリパラメーター
    名前 説明
    ソリューション定義入力フィールドのキーと値のペア ソリューション入力フィールドの名前と値のペア。たとえば、「short_description」という名前と、「VPN に接続できません」という値を入力します。

    データタイプ：文字列
    表 : 3. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

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

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

    デフォルト： application/json
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 6. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

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

    要素 説明
    入力 呼び出しへの入力として指定された名前と値のペア。

    データタイプ：オブジェクト
    output 指定されたソリューションに基づいて予測された結果の値。

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

    "output": {
  "confidence": Number",
  "outcome": "String",
  "threshold": Number"
}
    output.confidence 予測の推定精度 (%)。例：53.84615375762915

    データタイプ：数値
    output.outcome 予測出力フィールド値。たとえば、インシデントカテゴリ化ソリューションは、インシデントカテゴリ (inquiry など) を返します。

    データタイプ：文字列
    output.threshold 予測に関連付けられた構成済みのしきい値の値。

    データタイプ：数値

    サンプル cURL 要求

    curl "https://instance.service-now.com/api/now/predictive_intelligence/solution/ml_incident_categorization/prediction?short_description=unable%20to%20connect%20to%20VPN" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    {
  "result": {
    "input": {
      "short_description": "unable to connect to VPN",
      "api": "api"
    },
    "output": {
      "outcome": "inquiry",
      "confidence": 53.84615375762915,
      "threshold": 5
    }
  }
}

    予測インテリジェンス - GET /agent_intelligence/solution/prediction

    複数のソリューションの予測を返します。

    注:
    得られる結果オブジェクトは、ソリューション名と sys_id を用いて result.<solutionname>.<sys_id>.[{ <result1> },{ <result2>}] という形式でグループ化されます。

    カスタマイズの詳細については、「 MLSolutionFactory スクリプト可能オブジェクト」を参照してください。

    URL 形式

    バージョニングされた URL：/now/{api_version}/agent_intelligence/solution/prediction

    デフォルトの URL：/now/agent_intelligence/solution/prediction

    注:
    利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

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

    表 : 7. パスパラメーター
    名前 説明
    api_version オプションアクセスするエンドポイントのバージョン。たとえば、v1 や v2 などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。

    データタイプ：文字列
    表 : 8. クエリパラメーター
    パラメーター 説明
    input_filter 必須パラメーター input_table を使用する場合は、このパラメーターを input_maps パラメーターと一緒に使用しないでください。予測を実行するレコードを選択するためのフィルター。例：
    sys_id 0ef47232db801300864adfea5e961912

    データタイプ：文字列
    input_maps input_table パラメーターを使用する場合を除き、必須です。入力の名前と値のペアのアレイ。例： 
    [{"short_description":"my email is not working"}, {"short_description":"need help with password"}]

    データタイプ：オブジェクトのアレイ
    input_table input_maps パラメーターを使用する場合を除き、必須です。予測を実行するテーブル名。例：
    incident

    データタイプ：文字列
    options オプションの引数を持つ JSON オブジェクト。例：
    {"top_n" : 5, "apply_threshold":false}
    有効なオプション：
    • top_n：数値。指定されている場合、指定された予測の数までの上位の結果を返します
    • apply_threshold：ブール。ソリューションのしきい値をチェックして結果セットに適用します。しきい値は、類似性のソリューションしきい値または分類のクラスレベルのしきい値です。デフォルト値は true です。
    • custom_results_filter：文字列。類似性ソリューションのみ。エンコードされたクエリを使用して結果が返される元になる許可されたセットを指定します。

    データタイプ：オブジェクト
    solution_names 必須です。予測を実行するソリューション名のカンマ区切りリスト。例：
    ml_incident_categorization,ml_incident_assignment

    データタイプ：文字列
    表 : 9. 要求本文パラメーター (XML または JSON)
    名前 説明
    なし

    ヘッダー

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

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

    デフォルト： application/json
    表 : 11. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 12. ステータスコード
    ステータスコード 説明
    200 成功。要求が正常に処理されました。
    401 権限がありません。ユーザー資格情報が間違っているか、渡されていません。
    404 見つかりません。要求されたアイテムが見つかりませんでした。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

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

    要素 説明
    confidence 予測に関連付けられた信頼性の値。例：53.84。

    データタイプ：数値
    detailedResults 類似性ソリューションのみ。一致するテキストインデックスに関する詳細を含む JSON のキーと値のペア。

    データタイプ：文字列
    predictedSysId 予測値の sys_id。結果は、情報が予測されている任意のテーブルから取得できます。

    データタイプ：文字列
    predictedValue 予測結果を表す値。

    データタイプ：文字列
    threshold 予測に関連付けられた構成済みのしきい値の値。

    データタイプ：数値

    サンプル cURL 要求

    curl "http://instance.servicenow.com/api/now/agent_intelligence/solution/prediction?input_table=incident&input_filter=sys_id%3D0ef47232db801300864adfea5e961912&solution_names=ml_incident_categorization%2Cml_incident_assignment&options=%7B%22top_n%22%20%3A%202%2C%20%22apply_threshold%22%3Afalse%7D" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"
    {
  "result": {
    "ml_incident_categorization": {
      "0ef47232db801300864adfea5e961912": [
        {
          "confidence": 29.12211732875455,
          "threshold": 15,
          "predictedValue": "Email",
          "predictedSysId": ""
        },
        {
          "confidence": 19.08583525847071,
          "threshold": 14,
          "predictedValue": "Platform Performance",
          "predictedSysId": ""
        }
      ]
    },
    "ml_incident_assignment": {
      "0ef47232db801300864adfea5e961912": [
        {
          "confidence": 5.782322543467415,
          "threshold": 5,
          "predictedValue": "IT Finance CAB",
          "predictedSysId": "5f63e48fc0a8010e00eeaad81cd4dd37"
        },
        {
          "confidence": 5.303589009246953,
          "threshold": -1,
          "predictedValue": "NY DB",
          "predictedSysId": "5f74727dc0a8010e01efe33a251993f9"
        }
      ]
    }
  }
}