AI 검색 외부 사용자 매핑 API

  • 릴리스 버전: Zurich
  • 업데이트 날짜 2025년 07월 31일
  • 소요 시간: 8분

    • AI 검색 외부 사용자 매핑 API는 외부 소스의 사용자 매핑 정보를 애플리케이션의 인덱스로 수집할 수 ServiceNow® AI 검색 있는 엔드포인트를 제공합니다.

    AI 검색 외부 사용자 매핑 - POST /ais/external_content/user_mapping/import_multiple/{target_table}

    외부 사용자 매핑 목록을 사용자 매핑 테이블로 임포트합니다 AI 검색 . 각 매핑은 사용자에 대해 외부에서 정의된 사용자 및 그룹 별칭을 ServiceNow AI 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)
    이름 설명
    {객체}

    필수 명명되지 않은 객체입니다.

    데이터 유형: 객체

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

    필수 각 객체가 지정된 대상 테이블로 임포트할 사용자 매핑을 나타내는 객체의 배열입니다.

    데이터 유형: 배열

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

    각 문자열이 {object}.records.mapping_value 매개변수로 지정된 사용자의 별칭 ServiceNow AI Platform 으로 설정할 외부에서 정의된 그룹의 이름인 문자열 배열입니다.

    데이터 유형: 배열

    값은 사용자 매핑을 위해 선택한 외부에서 정의된 그룹의 이름에 따라 모든 형식이 될 수 있습니다. 예제는 다음과 같습니다.

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

    여기서 각 문자열은 {object}.records.mapping_value 매개변수로 지정된 사용자의 별칭 ServiceNow AI Platform 으로 설정할 외부에서 정의된 사용자의 이름입니다.

    데이터 유형: 배열

    값은 사용자 매핑을 위해 선택된 외부에서 정의된 사용자 계정의 이름에 따라 모든 형식이 될 수 있습니다. 예제는 다음과 같습니다.

    "external_user": [
  "beth-anglin",
  "ad\beth.anglin",
  "beth-anglin@sharepoint"
]
    {object}.records.mapping_value
    기존 기록을 고유하게 식별하는 이메일 필드 값입니다. 요청에서 외부에서 정의된 모든 사용자 및 그룹 별칭은 이 이메일 주소를 가진 사용자에게 매핑 ServiceNow AI Platform 됩니다.
    주:
    API는 이 매개변수를 사용자 매핑 기록의 고유 식별자로 처리합니다. 기존 사용자 매핑 기록과 동일한 mapping_value 로 다른 사용자 매핑을 임포트하면 새 기록이 기존 기록을 덮어씁니다.

    데이터 유형: 문자열

    테이블: 사용자 [sys_user]

    헤더

    다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.

    표 4. 요청 헤더
    헤더 설명
    수용 응답 본문의 데이터 형식입니다. application/json만 지원합니다.
    컨텐츠-형식 요청 본문의 데이터 형식입니다. application/json만 지원합니다.
    표 5. 응답 헤더
    헤더 설명
    없음

    상태 코드

    다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.

    표 6. 상태 코드
    상태 코드 설명
    201 성공입니다. 요청이 성공적으로 처리되었습니다.
    400 잘못된 요청입니다. 잘못된 요청 유형 또는 잘못된 형식의 요청이 탐지되었습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문 매개변수(JSON 또는 XML)

    이름 설명
    오류

    요청을 처리하는 동안 발생한 오류를 설명하는 객체입니다.

    데이터 유형: 객체

    "error": {
  "detail": "String",
  "message": "String"
}
    오류.상세 정보

    요청을 처리하는 동안 발생한 오류의 상세 정보입니다.

    데이터 유형: 문자열
    오류.메시지

    요청을 처리하는 동안 발생한 오류에 대한 메시지입니다.

    데이터 유형: 문자열
    import_set_id

    성공적인 요청에 의해 임포트 세트 [sys_import_set] 테이블에서 생성된 새 기록에 대한 Sys_id입니다.

    데이터 유형: 문자열
    multi_import_set_id

    성공적인 요청에 의해 다중 임포트 세트 [sys_multi_import_set] 테이블에서 생성된 새 기록에 대한 Sys_id입니다.

    데이터 유형: 문자열
    결과

    실패한 요청의 결과입니다. 요청 실패의 이유를 설명하는 메시지를 포함합니다.

    데이터 유형: 문자열
    상태

    실패한 요청의 상태입니다.

    유효한 값은 다음과 같습니다.
    • failure

    데이터 유형: 문자열

    cURL 요청

    Beth Anglin과 Abel Tuter 사용자에 대해 ServiceNow AI Platform 외부에서 정의된 사용자 및 그룹 별칭을 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_ids 표시됩니다.

    {
  "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"
}