이 문서에서는 API 호출을 일괄 처리하여 클라이언트가 수행해야 하는 연결 수를 줄이는 방법을 보여줍니다. 일괄 처리는 네트워크 왕복을 줄이고 처리량을 늘려 애플리케이션의 효율성을 개선할 수 있습니다.
개요
클라이언트에서 연결할 때마다 일정량의 오버헤드가 발생합니다. Google Sheets API는 클라이언트에서 여러 요청 객체(각각 수행할 단일 유형의 요청을 지정하는 객체 요청 객체)를 단일 일괄 요청에 배치할 수 있는 일괄 처리를 지원합니다. 일괄 요청은 여러 하위 요청을 서버에 대한 단일 호출로 결합하고 단일 응답을 다시 검색하여 성능을 높일 수 있습니다.
사용자는 항상 여러 요청을 함께 일괄 처리하는 것이 좋습니다. 다음은 일괄 처리를 사용할 수 있는 상황의 몇 가지 예입니다.
- API를 이제 막 사용하기 시작했고 업로드할 데이터가 많습니다.
- 여러 객체의 메타데이터 또는 속성(예: 서식 지정)을 업데이트해야 합니다.
- 많은 객체를 삭제해야 합니다.
한도, 승인, 종속 항목 고려사항
일괄 업데이트를 사용할 때 고려할 기타 항목은 다음과 같습니다.
- 모든 하위 요청을 포함한 각 일괄 요청은 사용량 한도에서 API 요청 1개로 집계됩니다.
- 일괄 요청은 한 번 인증됩니다. 이 단일 인증은 요청의 모든 일괄 업데이트 객체에 적용됩니다.
- 서버는 일괄 요청에 표시되는 것과 동일한 순서로 하위 요청을 처리합니다. 이후 하위 요청은 이전 하위 요청 중에 수행된 작업에 따라 달라질 수 있습니다. 예를 들어 동일한 일괄 요청에서 사용자는 기존 문서에 텍스트를 삽입한 다음 스타일을 지정할 수 있습니다.
일괄 처리 세부정보
일괄 요청은 스프레드시트 추가 후 서식 지정 등 여러 하위 요청이 포함된 하나의 batchUpdate 메서드 호출로 구성됩니다.
각 요청은 적용 전에 검증됩니다. 일괄 업데이트의 모든 하위 요청은 원자적으로 적용됩니다. 즉, 요청이 유효하지 않으면 전체 업데이트가 실패하고 (잠재적으로 종속된) 변경사항은 적용되지 않습니다.
일부 요청은 적용된 요청에 대한 정보가 포함된 응답을 제공합니다. 예를 들어 객체를 추가하기 위한 모든 일괄 업데이트 요청은 응답을 반환하므로 ID나 제목과 같은 새로 추가된 객체의 메타데이터에 액세스할 수 있습니다.
이 방식을 사용하면 여러 하위 요청이 포함된 하나의 API 일괄 업데이트 요청을 사용하여 전체 Google 문서를 빌드할 수 있습니다.
일괄 요청의 형식
요청은 하나의 필수 속성인 requests가 있는 중첩된 여러 하위 요청이 포함된 단일 JSON 요청입니다. 요청은 개별 요청의 배열로 구성됩니다. 각 요청은 JSON을 사용하여 요청 객체를 나타내고 해당 속성을 포함합니다.
일괄 응답 형식
일괄 요청의 응답 형식은 요청 형식과 비슷합니다. 서버의 응답에는 단일 응답 객체의 전체 응답이 포함됩니다.
기본 JSON 객체의 속성 이름은 replies입니다. 응답은 배열로 반환되며 요청 중 하나에 대한 각 응답은 해당 요청과 동일한 색인 순서를 사용합니다. 일부 요청에는 응답이 없으며 해당 배열 색인의 응답이 비어 있습니다.
예
다음 예는 Sheets API에서 일괄 처리를 사용하는 방법을 보여줍니다.
요청
이 일괄 요청 예시는 다음을 수행하는 방법을 보여줍니다.
AddSheetRequest를 사용하여sheetId이 12345인 시트를 기존 스프레드시트에 추가합니다.UpdateCellsRequest를 사용하여 A1 셀로 시작하는 새 시트에 데이터를 추가합니다.- 새 시트에
namedRange또는 필터 보기를 추가합니다.
요청에 시트 ID를 추가하면 사용자는 동일한 API 호출의 다른 하위 요청에 시트 ID를 사용할 수 있습니다. 이렇게 하면 쓰기-읽기-쓰기 주기를 방지하여 성능이 향상됩니다.
다양한 카테고리로 그룹화된 일괄 업데이트 요청 유형 목록은 일괄 업데이트 작업에 있는 표를 참고하세요.
{
"requests":[
{
"addSheet":{
"properties":{
"sheetId":123456
}
}
},
{
"updateCells":{
"start":{
"sheetId":123456
},
"rows":[
{
"values":[
{
"userEnteredValue":{
"stringValue":"hello"
}
}
]
},
{
"values":[
{
"userEnteredValue":{
"stringValue":"world"
}
}
]
}
],
"fields":"userEnteredValue"
}
},
{
"addNamedRange":{
"namedRange":{
"name":"newRange",
"range":{
"sheetId":123456,
"endRowIndex":2
}
}
}
}
]
}
응답
이 일괄 응답 예시는 일괄 요청 내 각 하위 요청이 적용된 방식에 대한 정보를 표시합니다. UpdateCellsRequest에는 응답이 포함되어 있지 않으므로 [1] 에 있는 배열의 색인 값은 빈 중괄호로 구성됩니다.
"replies":[
{
"addSheet":{
"properties":{
"sheetId":123456,
"title":"Sheet3",
"index":2,
"sheetType":"GRID",
"gridProperties":{
"rowCount":1000,
"columnCount":26
}
}
}
},
{
},
{
"addNamedRange":{
"namedRange":{
"namedRangeId":"2104325079",
"name":"newRange",
"range":{
"sheetId":123456,
"startRowIndex":0,
"endRowIndex":2,
"startColumnIndex":0,
"endColumnIndex":26
}
}
}
}
]