AI 検索 外部ユーザーマッピング API

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

    • AI Search 外部ユーザーマッピング API は、外部ソースから ServiceNow® AI 検索 アプリケーションのインデックスへのユーザーマッピング情報の取り込みを可能にするエンドポイントを提供します。

    AI 検索 外部ユーザーマッピング - POST /ais/external_content/user_mapping/import_multiple/{target_table}

    外部ユーザーマッピングのリストを AI 検索 ユーザーマッピングテーブルにインポートします。各マッピングは、Now Platform ユーザーに対して外部で定義されたユーザーとグループのエイリアスを指定します。AI 検索 はこれらのエイリアスを使用して、ユーザーが表示できる外部ドキュメントの検索結果を決定します。

    AI 検索外部コンテンツセキュリティで外部ユーザーマッピングを利用する方法については、「AI 検索の外部コンテンツセキュリティ」を参照してください。

    外部ユーザーマッピングのユーザー名とグループ名は、外部コンテンツ取り込み API の POST /ais/external_content/ingestDocument/{schema_table_name} エンドポイントを介して取り込まれた外部ドキュメントのセキュリティアクセス権限で指定されているものと一致する必要があります。外部で定義されたユーザーおよびグループのセキュリティアクセス権限を持つ外部ドキュメントを取り込む方法の詳細については、「 外部コンテンツ取り込み API」を参照してください。

    このエンドポイントを介してインポートされた外部ユーザーマッピングレコードのインポート履歴を表示するには、次に移動します: AI 検索 > 外部コンテンツ > ユーザーマッピングインポート履歴. 履歴レコードから、インポートタスクのインポートセット [sys_import_set] およびマルチインポートセット [sys_multi_import_set] レコードを表示できます。これらのレコードの情報を使用して、外部ユーザーマッピングが正しくインポートされたことを確認します。

    URL 形式

    バージョニングされた URL：/api/now/{api_version}/ais/external_content/user_mapping/import_multiple/{target_table}

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

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

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

    データタイプ：文字列
    target_table
    インポートされたマッピングを表示させる AI 検索 ユーザーマッピングテーブルの名前。たとえば、x_snc_sharepoint_user_table などです。
    注:
    ターゲット AI 検索 ユーザーマッピングテーブルは、 AI 検索 > 外部コンテンツ > ユーザーマッピングの作成 モジュールを使用して、このエンドポイントを使用する前に使用します。存在しないユーザーマッピングテーブルを指定すると、要求は失敗します。

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

    必須です。名前なしオブジェクト。

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

    {
  "records": [Array]
}
    {object}.records

    必須です。各オブジェクトが指定されたターゲットテーブルにインポートするユーザーマッピングを表すオブジェクトのアレイ。

    データタイプ：アレイ

    "records": [
  {
    "external_group": [Array],
    "external_user": [Array],
    "mapping_value": "String"
  }
]
    {object}.records.external_group

    {object}.records.mapping_value パラメーターで指定された Now Platform ユーザーのエイリアスとして設定される外部定義グループ名を各文字列とする文字列のアレイ。

    データタイプ：アレイ

    値は、ユーザーマッピング用に選択された外部定義グループの名前に応じて、任意の形式にすることができます。例：

    "external_group": [
  "itil",
  "hr-admin",
  "report-dev"
]
    {object}.records.external_user

    {object}.records.mapping_value パラメーターで指定された Now Platform ユーザーのエイリアスとして設定される外部定義ユーザー名を各文字列とする文字列のアレイ。

    データタイプ：アレイ

    値は、ユーザーマッピング用に選択された外部定義ユーザーアカウントの名前に応じて、任意の形式にすることができます。例：

    "external_user": [
  "beth-anglin",
  "ad\beth.anglin",
  "beth-anglin@sharepoint"
]
    {object}.records.mapping_value
    既存のレコードを一意に識別するメールフィールド値。要求内の外部で定義されたすべてのユーザーとグループのエイリアスは、このメールアドレスを持つ Now Platform ユーザーにマッピングされます。
    注:
    API は、このパラメーターをユーザーマッピングレコードの一意の識別子として扱います。既存のユーザーマッピングレコードと同じ mapping_value を使用して別のユーザーマッピングをインポートすると、既存のレコードが新しいレコードで上書きされます。

    データタイプ：文字列

    テーブル:ユーザー [sys_user]

    ヘッダー

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

    表 : 4. 要求ヘッダー
    ヘッダー 説明
    承認 応答本文のデータフォーマット。application/json のみをサポートします。
    Content-Type 要求本文のデータ形式。application/json のみをサポートします。
    表 : 5. 応答ヘッダー
    ヘッダー 説明
    なし

    ステータスコード

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

    表 : 6. ステータスコード
    ステータスコード 説明
    201 成功。要求が正常に処理されました。
    400 要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
    500 内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

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

    名前 説明
    error

    要求の処理中に発生した発生したエラーを説明するオブジェクト。

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

    "error": {
  "detail": "String",
  "message": "String"
}
    error.detail

    要求の処理中に発生したエラーの詳細。

    データタイプ：文字列
    error.message

    要求の処理中に発生したエラーのメッセージ。

    データタイプ：文字列
    import_set_id

    成功した要求によってインポートセット [sys_import_set] テーブルに作成された新しいレコードの sys_id。

    データタイプ：文字列
    multi_import_set_id

    成功した要求によってマルチインポートセット [sys_multi_import_set] テーブルに作成された新しいレコードの sys_id。

    データタイプ：文字列
    result

    失敗した要求の結果。要求が失敗した理由を説明するメッセージが含まれます。

    データタイプ：文字列
    status

    失敗した要求のステータス。

    有効な値：
    • failure

    データタイプ：文字列

    cURL 要求

    Now Platform ユーザーの Beth Anglin と Abel Tuter に対して外部で定義されたユーザーとグループのエイリアスを、x_snc_sharepoint_user_table という名前の AI 検索 ユーザーマッピングテーブルにインポートします。

    curl -X POST 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/x_snc_sharepoint_user_table' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password' \
  -d '{
    "records": [
      {
        "mapping_value": "beth.anglin@example.com",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "itil",
          "itil-admin",
          "itil-dev"
        ]
      },
      {
        "mapping_value": "abel.tuter@example.com",
        "external_user": [
          "ad\abel-tuter",
          "abel.tuter@sharepoint"
        ],
        "external_group": [
          "hr",
          "hr-admin",
          "hr-dev"
        ]
      }
    ]
  }'

    応答には、生成されたインポートセットレコードとマルチインポートセットレコードの sys_id が表示されます。

    {
  "import_set_id": "6e9ddb629d987010f877878bd9f0e9dd",
  "multi_import_set_id": "269ddb629d987010f877878bd9f0e9de"
}

    cURL 要求

    空のマッピングレコードを含む無効な要求をインポートします。

    curl 'https://instance.servicenow.com/api/now/v1/ais/external_content/user_mapping/import_multiple/u_ext_content_user_mapping' \
  --request POST \
  --user 'username':'password' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "records": [
      {
        "mapping_value": "beth.anglin@example.com",
        "external_user": [
          "ad\beth-anglin",
          "beth.anglin@sharepoint"
        ],
        "external_group": [
          "reports",
          "reports-admin",
          "reports-dev"
        ]
      },
      {}
    ]
  }'

    要求はステータス 400 で失敗し、応答に失敗の内容が示されます。

    {
  "result": "Error in processing the message"
}