임포트 세트 API

  • 릴리스 버전: Australia
  • 업데이트 날짜 2026년 03월 12일
  • 소요 시간: 15분

    • 임포트 세트 API는 임포트 세트 테이블과 상호작용할 수 있는 엔드포인트를 제공합니다.

    이 API는 연결된 변환 맵을 기반으로 들어오는 데이터를 변환합니다. 임포트 세트 API는 동기 변환을 지원합니다. 임포트 세트 API는 기존 SOAP 인터페이스를 미러링합니다.

    보안

    REST API를 통한 테이블에 대한 액세스는 BasicAuth에 의해 제한됩니다. 인증이나 권한 부여 없이 테이블에 대한 액세스를 허용하려면 sys_public.list에 테이블 이름을 추가합니다. 테이블에 정의된 ACL은 여전히 적용되며 ACL을 비활성화하는 것은 관리자의 책임입니다.

    임포트 세트 - GET /now/import/{stagingTableName}/{sys_id}

    지정된 임포트 준비 기록과 결과 변환 결과를 검색합니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/import/{stagingTableName}/{sys_id}

    기본 URL: /api/now/import/{stagingTableName}/{sys_id}

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    표 1. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오.

    데이터 유형: 문자열
    stagingTableName 임포트 데이터를 가져올 테이블의 이름입니다.

    데이터 유형: 문자열
    sys_id 데이터를 포함하는 기록의 Sys_id입니다.

    데이터 유형: 문자열
    표 2. 쿼리 매개변수
    이름 설명
    안 함
    표 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 권한이 해제되었습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    404 지정된 자원을 사용할 수 없음을 나타냅니다. 임포트 세트 테이블은 일정에 따라 자주 삭제되기 때문에 변환 결과가 더 이상 존재하지 않을 경우 GET 요청에서 404 찾을 수 없음 응답을 반환할 수 있습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

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

    이름 설명
    import_set 임포트 세트의 이름입니다.

    데이터 유형: 문자열
    결과 임포트된 데이터 세트에 대한 정보를 포함하는 객체의 목록입니다.
    데이터 유형: 배열
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    result.display_name 표시 값이 예인 테이블의 특정 열의 표시 이름입니다. 예를 들면 숫자입니다.

    데이터 유형: 문자열
    result.display_value 열의 표시 값입니다.display_name 예를 들면 CHG0000123입니다.

    데이터 유형: 문자열
    result.record_link 임포트한 기록에 대한 테이블 API GET 요청입니다.

    데이터 유형: 문자열
    결과.상태 임포트의 상태입니다.

    데이터 유형: 문자열
    result.sys_id 임포트 기록의 Sys_id입니다.

    데이터 유형: 문자열
    결과.테이블 데이터를 임포트한 테이블의 이름입니다.

    데이터 유형: 문자열
    result.transform_map 변환 맵의 이름입니다.

    데이터 유형: 문자열
    staging_table 임포트 준비 테이블의 이름입니다.

    데이터 유형: 문자열

    샘플 cURL 요청

    curl "https://instance.servicenow.com/api/now/import/imp_user/e2928be64f411200adf9f8e18110c777" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.service-now.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    임포트 세트 - POST /now/import/{stagingTableName}

    지정된 준비 테이블에 들어오는 데이터를 삽입하고 임포트 세트 테이블의 미리 정의된 변환 맵을 기반으로 변환을 트리거합니다.

    변환은 동시에 발생합니다. 정의하는 각 변환 맵에 대한 응답에는 대상 기록에 대한 정보와 같은 변환 결과가 포함됩니다.
    주:
    변환 스크립트의 status_message 및 error_message 필드가 사용자 지정 응답 필드와 함께 처리되어 응답으로 반환됩니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/import/{stagingTableName}

    기본 URL: /api/now/import/{stagingTableName}

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    주:
    임포트 세트 POST 메서드는 요청 본문 매개변수에 문자열 데이터 유형의 이름-값 쌍만 허용합니다. 다른 데이터 유형이 제공되면 임포트 세트 테이블에 저장된 결과 값이 의도한 형식과 일치하지 않을 수 있습니다. 예를 들어 중첩된 JSON 객체의 ":" 개념은 "="로 변경됩니다.
    표 7. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오.

    데이터 유형: 문자열
    stagingTableName 데이터를 임포트할 테이블의 이름입니다.

    데이터 유형: 문자열
    표 8. 쿼리 매개변수
    이름 설명
    안 함
    표 9. 요청 본문 매개변수(XML 또는 JSON)
    이름 설명
    호출 관련 임포트 필드에 삽입할 이름-값 쌍입니다.

    데이터 유형: 문자열

    헤더

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

    표 10. 요청 헤더
    머리글 설명
    수용 응답 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    콘텐츠-형식 요청 본문의 데이터 형식입니다. 지원되는 유형은 application/json 또는 application/xml입니다.

    기본값: application/json
    표 11. 응답 헤더
    머리글 설명
    안 함

    상태 코드

    이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

    표 12. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    201 성공입니다. 요청이 생성되었습니다.
    401 권한이 해제되었습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

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

    이름 설명
    import_set 임포트 세트의 이름입니다.

    데이터 유형: 문자열
    결과 임포트된 데이터 세트에 대한 정보를 포함하는 객체의 목록입니다.
    데이터 유형: 배열
    "result": [
  {
    "display_name": "String",
    "display_value": "String",
    "record_link": "String",
    "status": "String",
    "sys_id": "String",
    "table": "String",
    "transform_map": "String"
  }
]
    result.display_name 표시 값이 예인 테이블의 특정 열의 표시 이름입니다. 예를 들면 숫자입니다.

    데이터 유형: 문자열
    result.display_value 열의 표시 값입니다.display_name 예를 들면 CHG0000123입니다.

    데이터 유형: 문자열
    result.record_link 임포트한 기록에 대한 테이블 API GET 요청입니다.

    데이터 유형: 문자열
    결과.상태 임포트의 상태입니다.

    데이터 유형: 문자열
    result.sys_id 임포트 기록의 Sys_id입니다.

    데이터 유형: 문자열
    결과.테이블 데이터를 임포트한 테이블의 이름입니다.

    데이터 유형: 문자열
    result.transform_map 변환 맵의 이름입니다.

    데이터 유형: 문자열
    staging_table 임포트 준비 테이블의 이름입니다.

    데이터 유형: 문자열

    샘플 cURL 요청

    curl "https://instance.servicenow.com/api/now/import/imp_user" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{'first_name':'John','last_name':'Public','user_id':'john.public','email':'john.public@company.com'}" \
--user "username":"password"
    {
  "import_set": "ISET0010001",
  "staging_table": "imp_user",
  "result": [
    {
      "transform_map": "User",
      "table": "sys_user",
      "display_name": "name",
      "display_value": "John Public",
      "record_link": "https://instance.servicenow.com/api/now/table/sys_user/ea928be64f411200adf9f8e18110c777",
      "status": "inserted",
      "sys_id": "ea928be64f411200adf9f8e18110c777"
    }
  ]
}

    임포트 세트 - POST /now/import/{stagingTableName}/insertMultiple

    지정된 스테이징 테이블에 여러 기록을 삽입하고 단일 요청에서 미리 정의된 변환 맵 또는 강력한 변환 엔진(RTE) 구성을 기반으로 변환을 트리거합니다.

    변환은 기본적으로 비동기식입니다. 동기 변환을 설정하려면 REST 다중 삽입 [sys_rest_insert_multiple] 테이블에서 새 기록을 만들고, 소스 테이블을 선택하고, 변환을 동기로 설정합니다.

    이 엔드포인트는 두 가지 형식으로 요청 본문을 보낼 수 있습니다.
    데이터 소스 파일 형식
    JSON 데이터 소스에서 준비 테이블을 생성하는 경우 소스 파일의 JSON 형식과 일치시킵니다.
    스테이징 테이블 열 형식
    기본값입니다. 키 값 쌍의 준비 테이블 열 요청 본문 형식과 일치합니다.

    URL 형식

    버전이 지정된 URL: /api/now/{api_version}/import/{stagingTableName}/insertMultiple

    기본 URL: /api/now/import/{stagingTableName}/insertMultiple

    주:
    사용 가능한 버전은 REST API 탐색기에 지정됩니다. 스크립트 기반 REST API의 경우 스크립트 기반 REST 서비스 양식에 추가 버전 정보가 있습니다.

    지원되는 요청 매개변수

    주:
    임포트 세트 POST 메서드는 요청 본문 매개변수에 문자열 데이터 유형의 이름-값 쌍만 허용합니다. 다른 데이터 유형이 제공되면 임포트 세트 테이블에 저장된 결과 값이 의도한 형식과 일치하지 않을 수 있습니다. 예를 들어 중첩된 JSON 객체의 ":" 개념은 "="로 변경됩니다.
    표 13. 경로 매개변수
    이름 설명
    api_version 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하도록 이 값만 지정하십시오.

    데이터 유형: 문자열
    stagingTableName 데이터를 임포트할 임포트 세트 테이블의 이름입니다. 임포트 세트 주요 개념을 참조하십시오.

    데이터 유형: 문자열
    표 14. 쿼리 매개변수
    이름 설명
    multi_import_set_id 다중 임포트 세트 [sys_multi_import_set] 테이블의 항목 Sys_id입니다. 지정된 경우, 새 다중 임포트 세트에 추가하는 대신 현재 임포트를 이 다중 임포트 세트에 추가합니다.

    데이터 유형: 문자열

    테이블:
    run_after 실행할 항목의 Sys_id입니다. 지정된 임포트 세트가 완료된 후 현재 임포트 세트를 실행할 수 있습니다. 이 매개변수를 사용하여 임포트의 순차적 순서를 적용할 수 있습니다.

    이 매개변수는 비동기 변환에서만 유효합니다.

    데이터 유형: 문자열

    테이블: 임포트 세트 [sys_import_set]
    표 15. 요청 본문(JSON)
    형식 설명
    데이터 소스 파일 이 요청 본문 형식은 데이터 소스를 만드는 데 사용되는 JSON 파일 형식과 일치합니다. 데이터 소스의 JSON과 동일한 형식으로 요청 본문을 제공합니다. JSON 입력은 데이터 소스의 속성에 따라 다릅니다. 파일 형식 데이터 소스의 JSON 정보를 참조하십시오.
    • 이 옵션은 JSON 데이터 소스를 사용하여 스테이징 테이블을 만든 경우에만 사용할 수 있습니다. 파일 형식 데이터 소스 만들기를 참조하십시오.
    • 각 행 필드의 경로에 있는 데이터 소스 [sys_data_source] 테이블에서 데이터 소스의 경로를 정의해야 합니다.
    • REST 다중 삽입 사용자의 기본 동작을 변경하려면 REST 다중 삽입 [sys_rest_insert_multiple] 테이블에 항목을 생성합니다.
    • REST 다중 삽입 항목에서 데이터 소스 형식 사용을 활성화합니다.

    데이터 유형: 객체
    스테이징 테이블 열 (기본값) 이 요청 본문 형식은 준비 중인 테이블 열과 일치합니다. 임포트 필드에 삽입할 스테이징 테이블 열과 일치하는 키-값 쌍의 배열을 사용합니다 records . 각 JSON 키는 테이블 열을 삽입할 값을 나타내는 JSON 값에 매핑합니다. JSON 입력은 스테이징 테이블의 필드에 따라 다릅니다.

    열 매핑 기본 키 값은 열 테이블에 있습니다.

    {
   "records":[
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      },
      {
         "<ColumnLabel1>":"<value>",
         "<ColumnLabel2>":"<value>"
      }
   ]
}
    나머지 삽입 다중 [sys_rest_insert_multiple] 테이블에 항목을 추가하고 열 매핑 을 레이블 에서 열 이름으로 변경하여 매핑 설정을 수정할 수 있습니다.
    {
   "records":[
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      },
      {
         "<column_name1>":"<value>",
         "<column_name2>":"<value>"
      }
   ]
}

    Data dictionary tables 시스템의 테이블 필드에 대한 상세 정보를 제공합니다.

    데이터 유형: 배열

    헤더

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

    표 16. 요청 헤더
    머리글 설명
    수용 응답 본문의 데이터 형식입니다. application/json만 지원합니다.
    콘텐츠-형식 요청 본문의 데이터 형식입니다. application/json만 지원합니다.
    표 17. 응답 헤더
    머리글 설명
    안 함

    상태 코드

    이 HTTP 작업에 적용되는 상태 코드는 다음과 같습니다. REST API에 사용되는 가능한 상태 코드 목록은 REST API HTTP 응답 코드를 참조하십시오.

    표 18. 상태 코드
    상태 코드 설명
    200 성공입니다. 요청이 성공적으로 처리되었습니다.
    201 성공입니다. 요청이 생성되었습니다.
    401 권한이 해제되었습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다.
    500 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다.

    응답 본문(JSON)

    이름 설명
    import_set_id 추가된 기록의 Sys_id입니다. 비동기 요청의 경우 이 임포트 세트 프로세스가 완료된 후 이 값을 사용하여 다른 임포트 세트를 실행할 수 있습니다.

    데이터 유형: 문자열

    테이블: 임포트 세트 [sys_import_set]
    multi_import_set_id 추가된 기록의 Sys_id입니다. 이 값을 사용하여 여러 임포트 세트를 하나의 세트로 그룹화합니다.

    데이터 유형: 문자열

    테이블: 다중 임포트 세트 [sys_multi_import_set]

    샘플 cURL 요청

    다음 예시에서는 스테이징 테이블 열 형식을 사용하여 u_employee_import_set_table라는 임포트 테이블에서 변환을 실행하는 방법을 보여줍니다.

    curl "https://instance.servicenow.com/api/now/import/u_employee_import_set_table/insertMultiple" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"records\": [
  {
   \"Address\": \"Hollywood\",
   \"Name\": \"Tom\",
   \"ID\": \"123\"
  },
  {
   \"Address\": \"Vine\",
   \"Name\": \"Irene\",
   \"ID\": \"456\"
  }
  ]
}" \
--user 'username':'password'

    결과에는 임포트 세트[sys_import_set] 및 다중 임포트 세트[sys_multi_import_set] 테이블의 새 기록에 대한 sys_ids가 포함됩니다.

    {
  "import_set_id": "<import_set_sys_id>",
  "multi_import_set_id": "<multi_import_set_sys_id>"
}