이 페이지는 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	Engine	$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	Engine		1
5	총계	3달러	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	Engine
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	Engine	$100	1	2016년 3월 20일
5