AI 검색 외부 사용자 매핑 API

  • 릴리스 버전: Xanadu
  • 업데이트 날짜 2024년 08월 01일
  • 읽기8분

    • AI 검색 외부 사용자 매핑 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}

    지원되는 요청 매개변수

    표 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 매개변수로 지정된 사용자에 대한 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
    사용자 [sys_user] 테이블의 기존 기록을 고유하게 식별하는 이메일 필드 값입니다. 요청에서 외부에서 정의된 모든 사용자 및 그룹 별칭은 이 이메일 주소를 가진 사용자에게 매핑 Now Platform 됩니다.
    주:
    API는 이 매개변수를 사용자 매핑 기록의 고유 식별자로 처리합니다. 기존 사용자 매핑 기록과 동일한 mapping_value 으로 다른 사용자 매핑을 임포트하면 새 기록이 기존 기록을 덮어씁니다.

    데이터 유형: 문자열

    헤더

    다음 요청 및 응답 헤더는 이 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에 대해 Now Platform 외부에서 정의된 사용자 및 그룹 별칭을 AI 검색 x_snc_sharepoint_user_table이라는 사용자 매핑 테이블로 임포트합니다.

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