배치 API
Batch API는 여러 REST API 호출이 포함된 단일 요청을 보내는 엔드포인트를 제공하고 응답 페이로드 스트림을 반환합니다.
이 REST API를 통해 통합자는 다음을 수행할 수 있습니다.
- API 요청을 함께 일괄 처리하여 보내는 데 필요한 시간을 줄이고 인증, 세션 설정 및 왕복 트래픽을 단일 단계로 좁혀 오버헤드를 줄입니다.
- 클라이언트 측 통합을 위한 보다 효율적인 코드를 작성합니다.
- 배치 항목 형식을 혼합하여 단일 배치 요청에 포함합니다. 예를 들어, 한 배치에는 한 엔드포인트로 보내기 위한 XML 형식의 Bases64 인코딩 요청과 다른 엔드포인트로 보내기 위한 JSON 형식의 Base64 인코딩 요청이 포함될 수 있습니다.
- 그 대가로 응답 페이로드 스트림을 수신합니다.
- 배치의 각 API 호출에 기존 ACL을 적용합니다.
인스턴스에서 사용할 수 있는 모든 API를 배치 API 호출에 포함할 수 있습니다. 성능상의 이유로 장기 실행 요청 및 많은 양의 데이터를 검색하는 요청을 포함하지 마십시오.
중요사항:
Batch API는 개별 API 요청과 동일한 성능 특성을 갖지만 여러 클라이언트-서버 요청의 오버헤드를 방지합니다. 배치 API는 병렬 트랜잭션 처리를 위한 것이 아니며 API 요청이 오래 실행되면 API 요청이 최대 트랜잭션 시간을 초과하여 실패를 반환할 수 있습니다.
크기 및 처리 한계
페이로드는 다음과 같은 크기 제한을 준수합니다.
- 요청의 각 항목: 5MB. 시스템 속성을 업데이트하여 이 기본값을 glide.rest.batch.max.inputSize 변경할 수 있습니다. 최댓값: 10MB.
- 응답의 각 항목: 10MB. 시스템 속성을 업데이트하거나 요청에 헤더를 X-BATCHREQUEST-MAX-OUTPUT-SIZE 추가하여 이 기본값을 glide.rest.batch.max.outputSize 변경할 수 있습니다. X-BATCHREQUEST-MAX-OUTPUT-SIZE 헤더 값은 시스템 속성 값을 초과할 수 없습니다.
주:
요청이 30초 이상 실행되면 트랜잭션 할당량 규칙에 따라 트랜잭션이 REST Batch API request timeout 종료됩니다. 이 트랜잭션 할당량 규칙의 값을 늘리면 성능 문제가 발생할 수 있습니다.
배치 요청이 크기 또는 처리 제한에 도달하면 시스템은 트랜잭션을 취소하고 처리되지 않은 요청을 응답의 서비스되지 않은 JSON 배열로 반환합니다.
배치 - POST/now/batch
단일 호출로 여러 REST API 요청을 보냅니다.
인스턴스에서 사용할 수 있는 모든 API를 배치 API 호출에 포함할 수 있습니다. 성능상의 이유로 장기 실행 요청 및 많은 양의 데이터를 검색하는 요청을 포함하지 마십시오.
URL 형식
버전이 지정된 URL: /api/now/{api_version}/batch
지원되는 요청 매개변수
| 이름 | 설명 |
|---|---|
| api_version | 옵션입니다. 액세스할 엔드포인트의 버전입니다. 예를 들면 v1 또는 v2입니다. 최신 버전이 아닌 엔드포인트 버전을 사용하려면 이 값만 지정합니다. 데이터 유형: 문자열 |
| 이름 | 설명 |
|---|---|
| 없음 |
| 이름 | 설명 |
|---|---|
| batch_request_id | 요청 배치를 식별하는 ID입니다. 데이터 유형: 문자열 |
| rest_requests | 필수 배치 요청에 포함할 요청 객체의 목록입니다. 데이터 유형: 배열 |
| rest_requests.body | Base64로 인코딩된 요청 본문입니다. 본문이 필요한 메서드(예: POST)에만 적용됩니다. 인코딩하기 전에 본문은 모든 형식이 될 수 있습니다. 예를 들어 XML 또는 JSON입니다. 데이터 유형: 문자열 |
| rest_requests.exclude_response_headers | 응답에서 응답 헤더를 제외할지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다.
데이터 유형: 부울 기본값: false |
| rest_requests.headers | 엔드포인트로 보낼 요청 헤더 개체의 목록입니다. 데이터 유형: 배열 |
| rest_requests.headers.name | 헤더의 이름입니다. 데이터 유형: 문자열 |
| rest_requests.headers.value | 헤더의 값입니다. 데이터 유형: 문자열 |
| rest_requests.id | 필수 배치의 각 항목에 대한 ID입니다. 데이터 유형: 문자열 |
| rest_requests.메서드 | 필수 연결된 엔드포인트에 대해 호출할 메서드입니다. 데이터 유형: 문자열 |
| rest_requests.url | 필수 요청을 보낼 엔드포인트의 상대 경로입니다. 쿼리 매개변수를 포함합니다. 데이터 유형: 문자열 |
헤더
다음 요청 및 응답 헤더는 이 HTTP 작업에만 적용되거나 이 작업에 고유한 방식으로 적용됩니다. REST API에서 사용되는 일반 헤더 목록은 지원되는 REST API 헤더를 참조하세요.
| 헤더 | 설명 |
|---|---|
| 수용 | 응답 본문의 데이터 형식입니다. application/json만 지원합니다. |
| 컨텐츠-형식 | 요청 본문의 데이터 형식입니다. application/json만 지원합니다. |
| X-BATCHREQUEST-최대 출력 크기 | 배치 응답의 각 항목에 대한 크기 제한입니다. 이 헤더를 추가하여 시스템 속성에 glide.rest.batch.max.outputSize 의해 설정된 기본값보다 낮은 크기 제한을 제공합니다. 시스템 속성의 값보다 높은 값을 설정할 수 없습니다. 기본값: 10MB. |
| 헤더 | 설명 |
|---|---|
| 없음 |
상태 코드
다음 상태 코드는 이 HTTP 작업에 적용됩니다. REST API에서 사용할 수 있는 상태 코드 목록은 REST API HTTP 응답 코드를 참조하세요.
| 상태 코드 | 설명 |
|---|---|
| 200 | 성공입니다. 요청이 성공적으로 처리되었습니다. |
| 401 | 승인되지 않았습니다. 사용자 자격 증명이 잘못되었거나 전달되지 않았습니다. |
| 500 | 내부 서버 오류입니다. 요청을 처리하는 동안 예기치 않은 오류가 발생했습니다. 응답에는 오류에 대한 추가 정보가 포함되어 있습니다. |
응답 본문 매개변수(JSON)
| 이름 | 설명 |
|---|---|
| batch_request_id | 요청의 매개변수와 일치하는 batch_request_id 배치의 ID입니다. 데이터 유형: 문자열 |
| serviced_requests | 배치 요청의 응답 객체 목록입니다. 데이터 유형: 배열 |
| serviced_requests.본문 | 응답의 Base64 인코딩 본문입니다. 본문의 값을 가져오기 위해 Base64는 이 매개 변수의 내용을 디코딩합니다. 데이터 유형: 문자열 |
| serviced_requests.error_message입니다. | 오류 메시지가 있는 경우 데이터 유형: 문자열 |
| serviced_requests.execution_time | 배치 항목 요청을 실행하는 데 소요된 시간입니다. 데이터 유형: 숫자 단위: 밀리초 |
| serviced_requests.headers | 배치 항목의 헤더입니다. 데이터 유형: 배열 |
| serviced_requests.headers.name | 헤더의 이름입니다. 데이터 유형: 문자열 |
| serviced_requests.headers.value | 헤더의 값입니다. 데이터 유형: 문자열 |
| serviced_requests.id | 요청의 매개변수와 일치하는 rest_requests.id 배치 항목의 ID입니다. 데이터 유형: 문자열 |
| serviced_requests.redirect_url | 리디렉션 URL이 있는 경우. 데이터 유형: 문자열 |
| serviced_requests.status_code | 배치 항목의 상태 코드입니다. 데이터 유형: 숫자 |
| serviced_requests.status_text입니다. | 배치 항목의 상태 코드 텍스트입니다. 데이터 유형: 문자열 |
| unserviced_requests | 배치 요청이 크기 또는 처리 제한에 도달했기 때문에 처리되지 않은 요청의 ID입니다. 데이터 유형: 배열 |
cURL 요청
이 배치 요청은 인스턴스로 두 개의 GET 요청을 보내고 한 개의 POST 요청을 인시던트 테이블로 보냅니다. POST 요청의 본문은 Base64로 인코딩됩니다.
curl "https://instance.servicenow.com/api/now/v1/batch" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--user "username":"password"\
--data "{
\"batch_request_id\":\"1\",
\"rest_requests\":[
{
\"id\":\"11\",
\"headers\":[
{
\"name\":\"Content-Type\",
\"value\":\"application/xml\"
},
{
\"name\":\"Accept\",
\"value\":\"application/xml\"
}
],
\"url\":\"/api/global/user_role_inheritance\",
\"method\":\"GET\"
},
{
\"id\":\"12\",
\"exclude_response_headers\":true,
\"headers\":[
{
\"name\":\"Content-Type\",
\"value\":\"application/json\"
},
{
\"name\":\"Accept\",
\"value\":\"application/json\"
}
],
\"url\":\"/api/now/table/incident?sysparm_limit=1\",
\"method\":\"GET\"
},
{
\"id\":\"13\",
\"exclude_response_headers\":true,
\"headers\":[
{
\"name\":\"Content-Type\",
\"value\":\"application/json\"
},
{
\"name\":\"Accept\",
\"value\":\"application/json\"
}
],
\"url\": \"/api/now/table/incident\",
\"method\":\"POST\",
\"body\": \"eyd1cmdlbmN5JzonMScsICdzaG9ydF9kZXNjcmlwdGlvbic6J015IGNvbXB1dGVyIG
Jyb2tlJywgJ2NvbW1lbnRzJzonRWxldmF0aW5nIHVyZ2VuY3ksIHRoaXMgaXMgYSBibG9ja2luZyBpc3N1ZSd9\"
}
]
}" \{
"batch_request_id": "1",
"serviced_requests": [
{
"id": "11",
"body": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cmVzcG9uc2U+PHJlc3VsdD48dX
Nlcl9uYW1lLz48L3Jlc3VsdD48L3Jlc3BvbnNlPg==",
"status_code": 200,
"status_text": "OK",
"headers": [
{
"name": "Pragma",
"value": "no-store,no-cache"
},
{
"name": "Expires",
"value": "0"
},
{
"name": "Content-Length",
"value": "88"
},
{
"name": "Content-Type",
"value": "application/xml; charset=UTF-8"
},
{
"name": "Cache-control",
"value": "no-cache,no-store,must-revalidate,max-age=-1"
}
],
"execution_time": 5
},
{
"id": "12",
"body": "eyJyZXN1bHQiOlt7InBhcmVudCI6IiIsIm1hZGVfc2xhIjoidHJ1ZSIsImNhdXNlZF9
ieSI6IiIsIndhdGNoX2xpc3QiOiIiLCJ1cG9uX3JlamVjdCI6ImNhbmNlbCIsInN5c191cGRhdGV
kX29uIjoiMjAxNi0xMi0xNCAwMjo0Njo0NCIsImNoaWxkX2luY2lkZW50cyI6IjAiLCJob2xkX3J
lYXNvbiI6IiIsInRhc2tfZWZmZWN0aXZlX251bWJlciI6IklOQzAwMDAwNjAiLCJhcHByb3ZhbF9
oaXN0b3J5IjoiIiwibnVtYmVyIjoiSU5DMDAwMDA2MCIsInJlc29sdmVkX2J5Ijp7ImxpbmsiOiJ
odHRwczovL2s4czAwNjc5Nzgtbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGk
vbm93L3RhYmxlL3N5c191c2VyLzUxMzcxNTNjYzYxMTIyN2MwMDBiYmQxYmQ4Y2QyMDA3IiwidmF
sdWUiOiI1MTM3MTUzY2M2MTEyMjdjMDAwYmJkMWJkOGNkMjAwNyJ9LCJzeXNfdXBkYXRlZF9ieSI
6ImVtcGxveWVlIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzgtbm9kZTE
udGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2VyLzY4MWN
jYWY5YzBhODAxNjQwMGI5OGEwNjgxOGQ1N2M3IiwidmFsdWUiOiI2ODFjY2FmOWMwYTgwMTY0MDB
iOThhMDY4MThkNTdjNyJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiIyMDE2LTE
yLTEyIDE1OjE5OjU3Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY3OTc4LW5
vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXNfdXNlcl9
ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjciLCJyb3V0ZV9yZWFzb24
iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImVtcGxveWVlIiwia25vd2xlZGdlIjoiZmFsc2UiLCJvcmR
lciI6IiIsImNhbGVuZGFyX3N0YyI6IjEwMjE5NyIsImNsb3NlZF9hdCI6IjIwMTYtMTItMTQgMDI",
"status_code": 200,
"status_text": "OK",
"headers": [],
"execution_time": 8
},
{
"id": "13",
"body": "eyJyZXN1bHQiOnsicGFyZW50IjoiIiwibWFkZV9zbGEiOiJ0cnVlIiwiY2F1c2VkX2J
5IjoiIiwid2F0Y2hfbGlzdCI6IiIsInVwb25fcmVqZWN0IjoiY2FuY2VsIiwic3lzX3VwZGF0ZWR
fb24iOiIyMDIwLTA1LTEyIDAxOjQ0OjM1IiwiY2hpbGRfaW5jaWRlbnRzIjoiMCIsImhvbGRfcmV
hc29uIjoiIiwidGFza19lZmZlY3RpdmVfbnVtYmVyIjoiSU5DMDAxMDAwNCIsImFwcHJvdmFsX2h
pc3RvcnkiOiIiLCJudW1iZXIiOiJJTkMwMDEwMDA0IiwicmVzb2x2ZWRfYnkiOiIiLCJzeXNfdXB
kYXRlZF9ieSI6ImFkbWluIiwib3BlbmVkX2J5Ijp7ImxpbmsiOiJodHRwczovL2s4czAwNjc5Nzg
tbm9kZTEudGh1bmRlci5sYWIzLnNlcnZpY2Utbm93LmNvbS9hcGkvbm93L3RhYmxlL3N5c191c2V
yLzY4MTZmNzljYzBhODAxNjQwMWM1YTMzYmUwNGJlNDQxIiwidmFsdWUiOiI2ODE2Zjc5Y2MwYTg
wMTY0MDFjNWEzM2JlMDRiZTQ0MSJ9LCJ1c2VyX2lucHV0IjoiIiwic3lzX2NyZWF0ZWRfb24iOiI
yMDIwLTA1LTEyIDAxOjQ0OjM1Iiwic3lzX2RvbWFpbiI6eyJsaW5rIjoiaHR0cHM6Ly9rOHMwMDY
3OTc4LW5vZGUxLnRodW5kZXIubGFiMy5zZXJ2aWNlLW5vdy5jb20vYXBpL25vdy90YWJsZS9zeXN
fdXNlcl9ncm91cC9nbG9iYWwiLCJ2YWx1ZSI6Imdsb2JhbCJ9LCJzdGF0ZSI6IjEiLCJyb3V0ZV9
yZWFzb24iOiIiLCJzeXNfY3JlYXRlZF9ieSI6ImFkbWluIiwia25vd2xlZGdlIjoiZmFsc2UiLCJ",
"status_code": 201,
"status_text": "Created",
"headers": [],
"execution_time": 2638
}
],
"unserviced_requests": []
}