이 페이지는 Cloud Translation API를 통해 번역되었습니다.

기본 쓰기

Google Sheets API를 사용하면 셀, 범위, 범위 세트, 전체 시트에 값과 수식을 쓸 수 있습니다. 이 페이지의 예에서는 Sheets API의 spreadsheets.values 리소스를 사용하여 일반적인 쓰기 작업을 실행하는 방법을 보여줍니다.

spreadsheet.batchUpdate 메서드를 사용하여 셀 값을 쓸 수도 있습니다. 이는 셀 서식이나 spreadsheets.values 리소스가 영향을 주지 않는 다른 속성을 동시에 업데이트하려는 경우에 유용할 수 있습니다. 예를 들어 셀 수식과 셀 서식을 모두 덮어쓰면서 한 시트에서 다른 시트로 셀 범위를 복사하려면 spreadsheet.batchUpdate와 함께 UpdateCellsRequest 메서드를 사용하면 됩니다.

단순한 값 쓰기의 경우 spreadsheets.values.update 메서드 또는 spreadsheets.values.batchUpdate 메서드를 사용하는 것이 더 쉽습니다.

이러한 예는 언어 중립성을 위해 HTTP 요청 형식으로 표시됩니다. Google API 클라이언트 라이브러리를 사용하여 여러 언어로 쓰기를 구현하는 방법을 알아보려면 셀 값 읽기 및 쓰기를 참고하세요.

이 예에서 자리표시자 SPREADSHEET_ID는 스프레드시트 URL에서 찾을 수 있는 스프레드시트 ID를 입력할 위치를 나타냅니다. 쓸 범위는 A1 표기법을 사용하여 지정됩니다. 범위의 예는 Sheet1!A1:D5입니다.

단일 범위 쓰기

다음 spreadsheets.values.update 코드 샘플은 빈 새 스프레드시트에서 범위에 값을 쓰는 방법을 보여줍니다. ValueInputOption 쿼리 매개변수는 필수이며 작성된 값이 파싱되는지 여부를 결정합니다 (예: 문자열이 날짜로 변환되는지 여부).

요청 본문은 작성할 범위 값을 설명하는 ValueRange 객체입니다. majorDimension 필드는 배열이 행별로 구성된 값 목록임을 나타냅니다. 타겟 범위의 기존 값을 덮어씁니다.

요청 프로토콜은 다음과 같습니다.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:D5",
  "majorDimension": "ROWS",
  "values": [
    ["Item", "Cost", "Stocked", "Ship Date"],
    ["Wheel", "$20.50", "4", "3/1/2016"],
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
    ["Totals", "=SUM(B2:B4)", "=SUM(C2:C4)", "=MAX(D2:D4)"]
  ],
}

응답은 다음과 같은 UpdateValuesResponse 객체로 구성됩니다.

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:D5",
  "updatedRows": 5,
  "updatedColumns": 4,
  "updatedCells": 20,
}

결과 시트는 다음과 같습니다.

	A	B	C	D
1	항목	비용	재고 있음	배송 날짜
2	휠	$20.50	4	2016년 3월 1일
3	문	$15	2	2016년 3월 15일
4	엔진	$100	1	2016년 3월 20일
5	총계	$135.5	7	2016년 3월 20일

범위에 선택적으로 쓰기

범위에 값을 쓸 때 상응하는 배열 요소를 null로 설정하여 일부 기존 셀을 변경하지 않을 수 있습니다. 빈 문자열 ("")을 셀에 작성하여 셀을 지울 수도 있습니다.

위 예에서 생성된 동일한 데이터가 포함된 시트에서 시작하여 다음 spreadsheets.values.update 코드 샘플은 일부 셀은 변경하지 않고 다른 셀은 지우면서 B1:D4 범위에 값을 쓰는 방법을 보여줍니다. ValueInputOption 쿼리 매개변수는 필수이며 작성된 값이 파싱되는지 여부를 결정합니다 (예: 문자열이 날짜로 변환되는지 여부).

요청 본문은 작성할 범위 값을 설명하는 ValueRange 객체입니다. majorDimension 필드는 배열이 열별로 정렬된 값 목록임을 나타냅니다.

요청 프로토콜은 다음과 같습니다.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!B1?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!B1",
  "majorDimension": "COLUMNS",
  "values": [
    [null,"$1","$2", ""],
    [],
    [null,"4/1/2016", "4/15/2016", ""]
  ]
}

여기의 values 필드에는 범위의 각 열에 적용된 변경사항이 나열됩니다. 첫 번째 배열은 B1이 변경되지 않고 (null 배열 요소로 인해) B4가 삭제됨 (빈 문자열)을 나타냅니다. B2 및 B3의 값이 업데이트됩니다. 세 번째 배열은 D 열에 동일한 작업을 실행하는 반면 두 번째 빈 배열은 C 열을 변경하지 않아야 함을 나타냅니다.

응답은 다음과 같은 UpdateValuesResponse 객체로 구성됩니다.

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!B1:D5",
  "updatedRows": 3,
  "updatedColumns": 2,
  "updatedCells": 6,
}

결과 시트는 다음과 같습니다.

	A	B	C	D
1	항목	비용	재고 있음	배송 날짜
2	휠	$1.00	4	2016년 4월 1일
3	문	$2	2	2016년 4월 15일
4	엔진		1
5	총계	$3.00	7	2016년 4월 15일

'총합' 행은 이 요청에 의해 직접 변경되지는 않지만, 변경된 셀에 종속된 수식이 셀에 포함되어 있으므로 변경됩니다.

여러 범위에 쓰기

다음 spreadsheets.values.batchUpdate 코드 샘플은 빈 시트에서 시작하여 Sheet1!A1:A4 및 Sheet1!B1:D2 범위에 값을 쓰는 방법을 보여줍니다. 대상 범위의 기존 값을 덮어씁니다. 요청 본문은 입력 데이터를 해석하는 방법을 보여주는 ValueInputOption 객체와 작성된 각 범위에 해당하는 ValueRange 객체 배열로 구성됩니다. majorDimension 필드는 포함된 배열이 열 배열로 해석되는지 아니면 행 배열로 해석되는지를 결정합니다.

요청 프로토콜은 다음과 같습니다.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchUpdate

{
  "valueInputOption": "VALUE_INPUT_OPTION",
  "data": [
    {
      "range": "Sheet1!A1:A4",
      "majorDimension": "COLUMNS",
      "values": [
        ["Item", "Wheel", "Door", "Engine"]
      ]
    },
    {
      "range": "Sheet1!B1:D2",
      "majorDimension": "ROWS",
      "values": [
        ["Cost", "Stocked", "Ship Date"],
        ["$20.50", "4", "3/1/2016"]
      ]
    }
  ]
}

응답은 업데이트된 셀 통계를 나열하는 객체와 업데이트된 범위마다 하나씩 UpdateValuesResponse 객체 배열로 구성됩니다. 예를 들면 다음과 같습니다.

{
  "spreadsheetId": SPREADSHEET_ID,
  "totalUpdatedRows": 4,
  "totalUpdatedColumns": 4,
  "totalUpdatedCells": 10,
  "totalUpdatedSheets": 1,
  "responses": [
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!A1:A4",
      "updatedRows": 4,
      "updatedColumns": 1,
      "updatedCells": 4,
    },
    {
      "spreadsheetId": SPREADSHEET_ID,
      "updatedRange": "Sheet1!B1:D2",
      "updatedRows": 2,
      "updatedColumns": 3,
      "updatedCells": 6,
    }
  ],
}

결과 시트는 다음과 같습니다.

	A	B	C	D
1	항목	비용	재고 있음	배송 날짜
2	휠	$20.50	4	2016년 3월 1일
3	문
4	엔진
5

파싱하지 않고 값 쓰기

다음 spreadsheets.values.update 코드 샘플은 빈 시트에서 시작하여 Sheet1!A1:E1 범위에 값을 쓰는 방법을 보여줍니다. 하지만 쓰여진 문자열이 수식, 불리언 또는 숫자로 파싱되지 않도록 RAW ValueInputOption 쿼리 매개변수를 사용합니다. 문자열로 표시되며 시트에서 텍스트 정렬이 가운데 정렬됩니다.

요청 프로토콜은 다음과 같습니다.

PUT https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1?valueInputOption=RAW

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Data", 123.45, true, "=MAX(D2:D4)", "10"]
  ],
}

응답은 다음과 같은 UpdateValuesResponse 객체로 구성됩니다.

{
  "spreadsheetId": SPREADSHEET_ID,
  "updatedRange": "Sheet1!A1:E1",
  "updatedRows": 1,
  "updatedColumns": 5,
  "updatedCells": 5,
}

결과 시트는 다음과 같습니다.

	A	B	C	D	E
1	데이터	123.45	TRUE	=MAX(D2:D4)	10
2

'TRUE'는 중앙에 정렬되며 불리언 값이지만 '123.45'는 숫자이므로 오른쪽 정렬되고 '10'은 문자열이므로 왼쪽 정렬됩니다. 수식은 파싱되지 않으며 문자열로 표시됩니다.

값 추가

아래 표와 같은 시트로 시작합니다.

	A	B	C	D
1	항목	비용	재고 있음	배송 날짜
2	휠	$20.50	4	2016년 3월 1일
3

다음 spreadsheets.values.append 코드 샘플은 3번 행부터 시작하여 값의 새 행 2개를 추가하는 방법을 보여줍니다. ValueInputOption 쿼리 매개변수는 필수이며 작성된 값이 파싱되는지 여부를 결정합니다 (예: 문자열이 날짜로 변환되는지 여부).

요청 본문은 작성할 범위 값을 설명하는 ValueRange 객체입니다. majorDimension 필드는 배열이 행별로 구성된 값 목록임을 나타냅니다.

요청 프로토콜은 다음과 같습니다.

POST https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:E1:append?valueInputOption=VALUE_INPUT_OPTION

{
  "range": "Sheet1!A1:E1",
  "majorDimension": "ROWS",
  "values": [
    ["Door", "$15", "2", "3/15/2016"],
    ["Engine", "$100", "1", "3/20/2016"],
  ],
}

응답은 다음과 같은 AppendValuesResponse 객체로 구성됩니다.

{
  "spreadsheetId": SPREADSHEET_ID,
  "tableRange": "Sheet1!A1:D2",
  "updates": {
    "spreadsheetId": SPREADSHEET_ID,
    "updatedRange": "Sheet1!A3:D4",
    "updatedRows": 2,
    "updatedColumns": 4,
    "updatedCells": 8,
  }
}

결과 시트는 다음과 같습니다.

	A	B	C	D
1	항목	비용	재고 있음	배송 날짜
2	휠	$20.50	4	2016년 3월 1일
3	문	$15	2	2016년 3월 15일
4	엔진	$100	1	2016년 3월 20일
5