기본 읽기

Google Sheets API를 사용하면 셀, 범위, 범위 집합, 전체 시트의 값을 읽을 수 있습니다. 이 페이지의 예는 spreadsheets.values 리소스를 사용하는 몇 가지 일반적인 읽기 작업을 보여줍니다. spreadsheets.get 메서드를 사용하여 셀 값을 읽을 수도 있지만 일반적으로 spreadsheets.values.get 또는 spreadsheets.values.batchGet가 더 쉽습니다.

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

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

소스 데이터

다음 예에서는 읽고 있는 스프레드시트의 첫 시트 ('Sheet1')에 다음과 같은 소스 데이터가 있다고 가정합니다. 첫 번째 행의 문자열은 개별 열의 레이블입니다. 스프레드시트의 다른 시트에서 읽는 방법의 예를 보려면 A1 표기법을 참조하세요.

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일

단일 범위 읽기

다음 spreadsheets.values.get 코드 샘플은 Sheet1!A1:D5 범위에서 값을 읽고 응답에 반환하는 방법을 보여줍니다. 비어있는 후행 열과 행은 생략됩니다.

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

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5

응답은 범위 값을 설명하는 ValueRange 객체로 구성됩니다. majorDimension 필드는 배열이 행별로 구성된 값 목록임을 나타냅니다.

{
  "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", "30/20/2016"],
    ["Totals", "$135.5", "7", "3/20/2016"]
  ],
}

열별로 그룹화된 단일 범위 읽기

다음 spreadsheets.values.get 코드 샘플은 Sheet1!A1:D3 범위에서 값을 읽고 응답에 반환하지만 열별로 그룹화하는 방법을 보여줍니다. 비어있는 후행 열과 행은 생략됩니다.

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

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D3?majorDimension=COLUMNS

응답은 범위 값을 설명하는 ValueRange 객체로 구성됩니다. majorDimension 필드는 배열이 열로 구성된 값 목록임을 나타냅니다.

{
  "range": "Sheet1!A1:D3",
  "majorDimension": "COLUMNS",
  "values": [
    ["Item", "Wheel", "Door"],
    ["Cost", "$20.50", "$15"],
    ["Stocked", "4", "2"],
    ["Ship Date", "3/1/2016", "3/15/2016"]
  ],
}

렌더링 옵션으로 단일 범위 읽기

다음 spreadsheets.values.get 코드 샘플은 Sheet1!A1:D5 범위에서 값을 읽고 응답에 반환하지만 렌더링 옵션을 사용하여 정보 반환 방식을 관리하는 방법을 보여줍니다. FORMULAValueRenderOption 설정은 계산된 값 대신 수식이 반환되어야 함을 나타내며, SERIAL_NUMBERDateTimeRenderOption 설정은 날짜가 숫자로 반환되어야 함을 나타냅니다. 다른 설정도 가능합니다. 비어있는 후행 열과 행은 생략됩니다.

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

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values/Sheet1!A1:D5?
            valueRenderOption=FORMULA&dateTimeRenderOption=SERIAL_NUMBER

응답은 범위 값을 설명하는 ValueRange 객체로 구성됩니다. majorDimension 필드는 배열이 행별로 구성된 값 목록임을 나타냅니다.

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

여러 범위 읽기

다음 spreadsheets.values.batchGet 코드 샘플은 Sheet1!B:B 및 Sheet1!D:D 범위에서 값을 읽고 응답으로 반환하는 방법을 보여줍니다. UNFORMATTED_VALUEValueRenderOption 설정은 값이 계산되지만 응답에 서식이 지정되지 않음을 나타냅니다. 비어있는 후행 열과 행은 생략됩니다.

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

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!B:B&ranges=Sheet1!D:D&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

이 메서드 호출에 대한 응답은 스프레드시트 ID가 있는 객체와 요청된 각 범위에 해당하는 ValueRange 객체 배열로 구성되며, 요청된 순서대로 나열됩니다. majorDimension 필드는 배열이 열로 구성된 값 목록임을 나타냅니다. 예를 들면 다음과 같습니다.

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!B1:B1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Cost",20.5,15,100,135.5]
      ]
    },
    {
      "range": "Sheet1!D1:D1000",
      "majorDimension": "COLUMNS",
      "values": [
        ["Ship Date",42430,42444,42449,42449]
      ]s
    }
  ]
}

여러 시트에서 여러 범위 읽기

다음 spreadsheets.values.batchGet 코드 샘플은 Sheet1!A1:D5, Products!D1:D100, Sales!E4:F6 시트의 범위에서 값을 읽고 응답에 반환하는 방법을 보여줍니다. UNFORMATTED_VALUEValueRenderOption 설정은 값이 계산되지만 응답에서 형식이 지정되지 않음을 나타냅니다. 비어있는 후행 열과 행은 생략됩니다.

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

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID/values:batchGet?
            ranges=Sheet1!A1:D5&ranges=Products!D1:D100&ranges=Sales!E4:F6&valueRenderOption=UNFORMATTED_VALUE&majorDimension=COLUMNS

이 메서드 호출에 대한 응답은 스프레드시트 ID가 있는 객체와 요청된 각 범위에 해당하는 ValueRange 객체 배열로 구성되며, 요청된 순서대로 나열됩니다. majorDimension 필드는 배열이 열로 구성된 값 목록임을 나타냅니다. 예를 들면 다음과 같습니다.

{
  "spreadsheetId": SPREADSHEET_ID,
  "valueRanges": [
    {
      "range": "Sheet1!A1:D5",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    },
    {
      "range": "Products!D1:D100",
      "majorDimension": "COLUMNS",
      "values": [
        [...]
      ]
    },
    {
      "range": "Sales!E4:F6",
      "majorDimension": "COLUMNS",
      "values": [
        [...],
        [...]
      ]
    }
  ]
}