임포트 세트 API

Yokohama API 참조

Release

yokohama

ft:locale

ko-KR

ft:publication_title

Yokohama API 참조

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

임포트 세트 API

릴리스 버전: Yokohama

업데이트 날짜 2025년 01월 30일

읽기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`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열
스테이징테이블이름	임포트 데이터를 가져올 테이블의 이름입니다. 데이터 유형: 문자열
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	임포트 세트의 값입니다. 데이터 유형: 문자열
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`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열
스테이징테이블이름	데이터를 임포트할 테이블의 이름입니다. 데이터 유형: 문자열

표 8. 쿼리 매개변수
이름	설명
안 함

표 9. 요청 본문 매개변수(XML 또는 JSON)
이름	설명
콜 관련	가져오기 필드에 삽입할 이름-값 쌍입니다. 데이터 유형: 문자열

머리글

표 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	임포트 세트의 값입니다. 데이터 유형: 문자열
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 Insert Multiples [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 서비스 양식에 추가 버전 정보가 있습니다.

지원되는 요청 매개변수

주:

표 13. 경로 매개변수
이름	설명
api_version	옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들어 `v1` 또는 `v2`입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열
스테이징테이블이름	데이터를 임포트할 임포트 세트 테이블의 이름입니다. 임포트 세트 주요 개념을 참조하십시오. 데이터 유형: 문자열

표 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>" } ] }` REST Insert Multiples [sys_rest_insert_multiple] 테이블에 항목을 추가하고 열 매핑 을 레이블 에서 열 이름으로 변경하여 매핑 설정을 수정할 수 있습니다. `{ "records":[ { "<column_name1>":"<value>", "<column_name2>":"<value>" }, { "<column_name1>":"<value>", "<column_name2>":"<value>" } ] }` 시스템의 Data dictionary tables 테이블 필드에 대한 상세 정보를 제공합니다. 데이터 유형: 배열

머리글

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