배치 API

워싱턴 DC API 참조

Release

washingtondc

ft:locale

ko-KR

ft:publication_title

워싱턴 DC API 참조

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

배치 API

릴리스 버전: Washingtondc

업데이트 날짜 2024년 02월 01일

읽기15분

Batch API는 여러 REST API 호출이 포함된 단일 요청을 보내는 엔드포인트를 제공하고 응답 페이로드 스트림을 반환합니다.

이 REST API를 통해 통합자는 다음을 수행할 수 있습니다.

API 요청을 일괄 처리하여 전송하는 데 필요한 시간을 줄이고, 인증, 세션 설정 및 왕복 트래픽을 한 단계로 좁혀 오버헤드를 줄입니다.
클라이언트 측 통합을 위한 보다 효율적인 코드를 생성합니다.
배치 항목 형식을 혼합하여 단일 배치 요청에 포함합니다. 예를 들어 하나의 일괄 처리에는 한 엔드포인트로 보내기 위한 XML 형식의 Bases64 인코딩 요청과 다른 엔드포인트로 보내기 위한 JSON 형식의 Base64 인코딩 요청이 포함될 수 있습니다.
그 대가로 응답 페이로드 스트림을 받습니다.
배치의 각 API 호출에 기존 ACL을 적용합니다.

인스턴스에서 사용할 수 있는 모든 API를 배치 API 호출에 포함할 수 있습니다. 성능상의 이유로 장기 실행 요청과 많은 양의 데이터를 검색하는 요청을 포함하지 마십시오.

중요사항:

Batch API는 개별 API 요청과 동일한 성능 특성을 갖지만 여러 클라이언트-서버 요청의 오버헤드를 방지합니다. Batch API는 병렬 트랜잭션 처리를 위한 것이 아니며 장기 실행 API 요청으로 인해 API 요청이 최대 트랜잭션 시간을 초과하고 실패를 반환할 수 있습니다.

크기 및 처리 한계

페이로드는 다음 크기 제한을 준수합니다.

요청의 각 항목: 5MB 시스템 속성을 업데이트하여 이 기본값을 glide.rest.batch.max.inputSize 변경할 수 있습니다. 최대값: 10MB.
응답의 각 항목: 10MB. 시스템 속성을 업데이트 glide.rest.batch.max.outputSize 하거나 요청에 헤더를 X-BATCHREQUEST-MAX-OUTPUT-SIZE 추가하여 이 기본값을 변경할 수 있습니다. 헤더 값은 X-BATCHREQUEST-MAX-OUTPUT-SIZE 시스템 속성의 값을 초과할 수 없습니다.

주:

요청이 30초 이상 실행되면 트랜잭션 할당량 규칙에 따라 REST Batch API request timeout 트랜잭션이 종료됩니다. 이 트랜잭션 할당량 규칙의 값을 늘리면 성능 문제가 발생할 수 있습니다.

일괄 처리 요청이 크기 또는 처리 제한에 도달하면 시스템은 트랜잭션을 취소하고 응답의 서비스되지 않은 JSON 배열에 처리 되지 않은 요청을 반환합니다.

배치 - POST /now/batch

한 번의 호출로 여러 REST API 요청을 보냅니다.

URL 형식

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

지원되는 요청 매개변수

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

표 2. 쿼리 매개변수
이름	설명
없음

표 3. 요청 본문 매개변수(JSON)
이름	설명
batch_request_id	요청 배치를 식별하는 ID입니다. 데이터 유형: 문자열
rest_requests	필수 배치 요청에 포함할 요청 객체의 목록입니다. 데이터 유형: 배열 `"rest_requests":[ { "body": "String", "exclude_response_headers": Boolean, "headers":[Array], "id": "String", "method": "String", "url": "String" } ]`
rest_requests.본문	Base64로 인코딩된 요청 본문입니다. 본문이 필요한 메서드(예: POST)에만 적용됩니다. 인코딩하기 전에 본문은 어떤 형식이든 될 수 있습니다. 예를 들어 XML 또는 JSON입니다. 데이터 유형: 문자열
rest_requests.exclude_response_headers	응답에서 응답 헤더를 제외할지 여부를 나타내는 플래그입니다. 유효한 값은 다음과 같습니다. true: 응답 헤더가 응답에 포함되지 않습니다. false: 응답 헤더가 응답에 포함됩니다. 데이터 유형: 부울 기본값: false
rest_requests.헤더	엔드포인트에 보낼 요청 헤더 객체의 목록입니다. 데이터 유형: 배열 `"headers":[ { "name":"String", "value":"String" } ]`
rest_requests.headers.name	헤더의 이름입니다. 데이터 유형: 문자열
rest_requests.headers.value	헤더의 값입니다. 데이터 유형: 문자열
rest_requests.id	필수 배치의 각 항목에 대한 ID입니다. 데이터 유형: 문자열
rest_requests.method	필수 연결된 끝점을 호출할 메서드입니다. 데이터 유형: 문자열
rest_requests.url	필수 요청을 보낼 엔드포인트의 상대 경로입니다. 쿼리 매개 변수를 포함합니다. 데이터 유형: 문자열

머리글

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

표 4. 요청 헤더
헤더	설명
수용	응답 본문의 데이터 형식입니다. application/json만 지원합니다.
컨텐츠-형식	요청 본문의 데이터 형식입니다. application/json만 지원합니다.
X-BATCHREQUEST-MAX-OUTPUT-SIZE	배치 응답의 각 항목에 대한 크기 제한입니다. 이 헤더를 추가하여 시스템 속성에서 glide.rest.batch.max.outputSize 설정한 기본값보다 낮은 크기 제한을 제공합니다. 시스템 속성의 값보다 높은 값을 설정할 수 없습니다. 기본값: 10MB.

표 5. 응답 헤더
헤더	설명
없음

상태 코드

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

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

응답 본문 매개변수(JSON)


이름	설명
batch_request_id	요청의 매개변수와 batch_request_id 일치하는 배치의 ID입니다. 데이터 유형: 문자열
serviced_requests	배치 요청의 응답 객체 목록입니다. 데이터 유형: 배열 `"serviced_requests":[ { "body": "String", "error_message": "String", "execution_time": Number, "headers": [Array], "id": "String", "redirect_url: "String", "status_code": Number, "status_text": "String" } ]`
serviced_requests.본문	응답의 Base64 인코딩 본문입니다. 본문의 값을 가져오기 위해 Base64는 이 매개 변수의 내용을 디코딩합니다. 데이터 유형: 문자열
serviced_requests.error_message	있는 경우 오류 메시지입니다. 데이터 유형: 문자열
serviced_requests.execution_time	배치 항목 요청을 실행하는 데 걸린 시간입니다. 데이터 유형: 숫자 단위: 밀리초
serviced_requests.헤더	배치 항목의 헤더입니다. 데이터 유형: 배열 `"headers":[ { "name":"String", "value":"String" } ]`
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": []
}