기본 쓰기

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 필드는 해당 범위의 각 열에 대한 변경사항을 나열합니다. 첫 번째 배열은 (null 배열 요소 때문에) B1은 그대로 유지되어야 하고 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 쿼리 매개변수를 사용합니다. 문자열로 표시되며 시트에서 텍스트 정렬이 가운데 정렬됩니다.

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

요청 프로토콜은 아래와 같습니다.

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