Google Sheets API v3를 기반으로 하는 기존 앱이 있는 경우 Google Sheets API v4로 이전할 수 있습니다. v4 버전은 JSON 기반이며 사용하기 쉬운 인터페이스를 제공하고 v3 버전에서는 불가능한 상당한 양의 기능을 추가합니다.
이 페이지에서는 이전 Sheets API v3 명령어와 Sheets API v4의 상응하는 작업 간의 매핑을 제공합니다. 매핑은 주로 직접 셀 읽기 및 쓰기 기능을 제공하는 spreadsheets.values 컬렉션에 중점을 둡니다. 시트 추가 또는 시트 속성 업데이트와 같은 기타 측면은 spreadsheets 컬렉션에서 처리합니다. v4 API의 JSON 구조는 v3에서 사용된 XML 구조와 하위 호환되지 않습니다.
Sheets v4 API에서 사용할 수 있는 리소스에 관한 자세한 내용은 API 참조를 참고하세요.
표기법 및 용어
v3 API는 특정 스프레드시트 내 시트를 '워크시트'라고 합니다. 이는 v4 API에서 사용하는 '시트'라는 용어와 동의어입니다.
API를 사용할 때는 작업 중인 스프레드시트의 스프레드시트 ID를 지정해야 하는 경우가 많습니다. 또한 조작되는 시트의 ID가 필요한 경우가 많습니다. 이러한 값은 API 엔드포인트 URL의 일부, 쿼리 매개변수 또는 요청 본문의 일부로 표시됩니다. 이 페이지에서 자리표시자 spreadsheetId 및 sheetId는 각각 스프레드시트 ID와 시트 ID를 나타냅니다. 이 페이지에 설명된 메서드를 사용할 때는 이러한 위치에 실제 ID를 대체하세요.
v3 API는 목록 피드를 사용하여 검색된 행에 ID를 할당합니다. 이 ID는 이 페이지에서 rowId 자리표시자로 표시됩니다.
요청 승인
앱이 실행되면 사용자에게 특정 권한을 부여해 달라고 요청합니다. 애플리케이션에서 지정하는 범위에 따라 요청하는 권한이 결정됩니다.
v3 API
Sheets API v3는 단일 승인 범위로 작동합니다.
https://spreadsheets.google.com/feeds
의 별칭입니다.
https://www.googleapis.com/auth/spreadsheets
두 범위 형식 중 어느 쪽이든 사용할 수 있습니다.
v4 API
Sheets API v4는 다음 범위 집합 중 하나 이상을 사용합니다.
https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/drive
애플리케이션에서 사용자의 시트 또는 시트 속성을 수정할 필요가 없는 경우 읽기 전용 범위를 사용하세요. 애플리케이션에 일반 Drive 액세스가 필요하지 않은 경우 Drive 범위 대신 스프레드시트 범위를 사용하세요.
공개 상태
이전 버전의 API에서는 공개 상태라는 용어를 특정 스프레드시트의 사용 가능 여부를 나타내는 데 사용합니다.
v3 API
Sheets API v3는 엔드포인트에서 직접 가시성을 표현합니다. public 스프레드시트는 '웹에 게시'되었으므로 승인 없이 API에서 액세스할 수 있지만 private 스프레드시트는 인증이 필요합니다. 공개 상태는 스프레드시트 ID 뒤의 엔드포인트에 지정됩니다.
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
v4 API
새 Sheets API v4에는 공개 상태를 명시적으로 선언하는 항목이 없습니다. API 호출은 스프레드시트 ID를 사용하여 이루어집니다. 애플리케이션에 지정된 스프레드시트에 액세스할 권한이 없으면 오류가 반환됩니다. 그렇지 않으면 통화가 진행됩니다.
투영
Sheets API v3에서 프로젝션이라는 용어는 특정 API 호출에서 반환되는 데이터 집합(전체 또는 API 내에 정의된 고정 하위 집합)을 나타내는 데 사용됩니다. Sheets API v4는 프로젝션을 사용하지 않습니다. 대신 반환되는 데이터를 더 세부적으로 제어할 수 있습니다.
v3 API
Sheets API v3에는 두 가지 투영 설정만 가능합니다. full 프로젝션은 사용 가능한 모든 정보를 반환하는 반면 basic는 워크시트, 목록, 셀 피드의 경우 더 작고 고정된 데이터 하위 집합을 반환합니다.
공개 상태와 마찬가지로 프로젝션은 API 엔드포인트(공개 상태 설정 후)에 지정해야 합니다.
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
basic 프로젝션에서 제공하는 더 작은 데이터 하위 집합은 코드의 효율성을 높이는 데 유용하지만 맞춤설정할 수는 없습니다.
v4 API
Sheets API v4는 전체 데이터 세트를 반환할 수 있지만 Sheets API v3의 basic 공개 상태 설정과 유사한 고정 하위 집합은 정의하지 않습니다.
스프레드시트 모음의 메서드는 fields 쿼리 매개변수를 사용하여 반환하는 데이터의 양을 제한합니다.
예를 들어 다음 쿼리는 특정 스프레드시트의 모든 시트 제목만 반환합니다.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?fields=sheets.properties.title
스프레드시트 만들기
v3 API
Sheets API v3는 새 스프레드시트를 만드는 수단을 제공하지 않습니다. 대신 Drive API Files.create 메서드를 사용하여 새 스프레드시트 파일을 만들 수 있습니다. 이렇게 하려면 애플리케이션에서 https://www.googleapis.com/auth/drive 범위를 선언해야 합니다.
v4 API
Drive API Files.create 메서드는 Sheets API v4에서도 사용할 수 있지만 애플리케이션에서 https://www.googleapis.com/auth/drive 범위를 제공해야 합니다.
이에 상응하는 대안으로 Sheets API v4는 spreadsheets.create 메서드를 제공합니다. 이 메서드는 선택적으로 시트를 추가하고, 스프레드시트 및 시트 속성을 설정하고, 이름이 지정된 범위를 추가할 수도 있습니다. 예를 들어 다음은 새 스프레드시트를 만들고 'NewTitle'이라는 이름을 지정합니다.
POST https://sheets.googleapis.com/v4/spreadsheets
{
"properties": {"title": "NewTitle"}
}인증된 사용자의 스프레드시트 목록
v3 API
Sheets API v3 피드를 사용하면 애플리케이션이 인증된 사용자가 액세스할 수 있는 모든 스프레드시트의 목록을 가져올 수 있습니다. 스프레드시트 피드 엔드포인트는 다음과 같습니다.
GET https://spreadsheets.google.com/feeds/spreadsheets/private/full
v4 API
Sheets API v4는 이 특정 작업을 제공하지 않습니다. 스프레드시트 선택을 위해 Google 선택 도구와 함께 drive.file 범위를 사용하도록 앱을 이전하는 것이 좋습니다.
스프레드시트를 나열해야 하는 경우 mimeType 쿼리를 사용하여 Drive API Files.list 메서드를 통해 이를 재현할 수 있습니다.
GET https://www.googleapis.com/drive/v3/files
?q=mimeType='application/vnd.google-apps.spreadsheet'Drive API files.list 메서드를 사용하여 사용자의 모든 스프레드시트를 나열하려면 제한된 범위가 필요합니다.
시트 메타데이터 검색
Sheets API v3는 특정 스프레드시트에 포함된 시트 메타데이터에 액세스하는 피드를 제공합니다 (행 및 셀 데이터는 별도의 피드를 통해 액세스됨). 메타데이터에는 시트 제목 및 크기 정보와 같은 정보가 포함됩니다.
Sheets API v4 spreadsheets.get 메서드를 사용하면 이 정보와 그 밖의 많은 정보에 액세스할 수 있습니다.
v3 API
워크시트 피드는 적절한 승인 헤더를 사용하여 이 API 엔드포인트에서 액세스할 수 있습니다.
GET https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
이 요청에 대한 응답은 다음과 유사한 구조를 가지며 각 시트의 데이터가 별도의 <entry>에 포함됩니다.
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:gs="http://schemas.google.com/spreadsheets/2006"
xmlns:gd="http://schemas.google.com/g/2005"
gd:etag='W/"D0cERnk-eip7ImA9WBBXGEg."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Groceries R Us</title>
<link rel="alternate" type="text/html"
href="https://spreadsheets.google.com/ccc?key=spreadsheetId"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full"/>
<author>
<name>Fitzwilliam Darcy</name>
<email>fitz@example.com</email>
</author>
<openSearch:totalResults>1</openSearch:totalResults>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>1</openSearch:itemsPerPage>
<entry gd:etag='"YDwqeyI."'>
<id>https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<title type="text">Sheet1</title>
<content type="text">Sheet1</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>100</gs:rowCount>
<gs:colCount>20</gs:colCount>
</entry>
</feed>
v4 API
spreadsheets.get 메서드를 사용하면 Sheets API v3를 사용하여 얻을 수 있는 것보다 훨씬 더 많은 시트 속성과 기타 메타데이터를 가져올 수 있습니다. 시트 속성만 읽으려면 includeGridData 쿼리 매개변수를 false로 설정하여 스프레드시트 셀 데이터가 포함되지 않도록 합니다.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?includeGridData=false
Spreadsheet 응답에는 Sheet 객체의 배열이 포함됩니다. 시트 제목과 크기 정보는 이러한 객체의 SheetProperties 요소 아래에서 확인할 수 있습니다. 예를 들면 다음과 같습니다.
{
"spreadsheetId": spreadsheetId,
"sheets": [
{"properties": {
"sheetId": sheetId,
"title": "Sheet1",
"index": 0,
"gridProperties": {
"rowCount": 100,
"columnCount": 20,
"frozenRowCount": 1,
"frozenColumnCount": 0,
"hideGridlines": false
},
...
},
...
},
...
],
...
}스프레드시트에 시트 추가하기
두 API 모두 기존 스프레드시트에 새 시트를 추가할 수 있습니다.
v3 API
Sheets API v3는 다음과 같은 (인증된) POST 요청을 실행하여 스프레드시트에 새 워크시트를 추가할 수 있습니다. 새 시트의 크기를 지정할 수 있습니다.
POST https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<title>Expenses</title>
<gs:rowCount>50</gs:rowCount>
<gs:colCount>10</gs:colCount>
</entry>
v4 API
spreadsheets.batchUpdate 메서드에서 AddSheet 요청을 실행하여 새 시트를 추가할 수 있습니다. 요청 본문의 일부로 새 시트의 시트 속성을 지정할 수 있습니다. 모든 속성은 선택사항입니다. 기존 시트에 사용된 제목을 제공하면 오류가 발생합니다.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [{
"addSheet": {
"properties": {
"title": "Expenses",
"sheetType": "GRID",
"gridProperties": {
"rowCount": 50,
"columnCount": 10
}
}
}
}],
}시트 제목 및 크기 변경하기
Sheets API v3를 사용하면 시트 제목과 크기를 업데이트할 수 있습니다. Sheets API v4를 사용하면 이 작업도 할 수 있지만 다른 시트 속성을 업데이트하는 데도 사용할 수 있습니다. 시트 크기를 줄이면 잘린 셀의 데이터가 경고 없이 삭제될 수 있습니다.
v3 API
워크시트의 제목이나 크기를 변경하려면 먼저 워크시트 피드를 가져와 edit URL이 포함된 원하는 워크시트 항목을 찾습니다.
워크시트의 메타데이터를 업데이트하고 수정 URL에 PUT 요청의 본문으로 전송합니다. 예를 들면 다음과 같습니다.
PUT https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
<entry>
<id>
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId
</id>
<updated>2007-07-30T18:51:30.666Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#worksheet"/>
<title type="text">Expenses</title>
<content type="text">Expenses</content>
<link rel="http://schemas.google.com/spreadsheets/2006#listfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full"/>
<link rel="http://schemas.google.com/spreadsheets/2006#cellsfeed"
type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full"/>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version"/>
<gs:rowCount>45</gs:rowCount>
<gs:colCount>15</gs:colCount>
</entry>
v4 API
크기, 제목, 기타 시트 속성을 업데이트하려면 spreadsheets.batchUpdate 메서드에서 updateSheetProperties 요청을 실행합니다. POST 요청 본문에는 변경할 속성이 포함되어야 하며 fields 매개변수에는 이러한 속성이 명시적으로 나열되어야 합니다. 모든 속성을 업데이트하려면 fields:"*"를 사용하여 모든 속성을 나열하는 방법을 사용하세요. 예를 들어 다음은 지정된 ID의 시트에서 시트 제목 및 크기 속성을 업데이트해야 한다고 지정합니다.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"updateSheetProperties": {
"properties": {
"sheetId": sheetId,
"title": "Expenses",
"gridProperties": {
"rowCount": 45,
"columnCount": 15,
}
},
"fields": "title,gridProperties(rowCount,columnCount)"
}
}
],
}시트의 sheetId를 가져오려면 스프레드시트 spreadsheets.get 메서드를 사용합니다.
시트 삭제하기
두 API 모두 지정된 스프레드시트에서 시트를 삭제할 수 있습니다.
v3 API
워크시트를 삭제하려면 먼저 워크시트 피드를 가져온 다음 대상 워크시트 항목의 edit URL에 DELETE 요청을 전송합니다.
DELETE https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/private/full/sheetId/version
v4 API
시트를 삭제하려면 spreadsheets.batchUpdate 메서드에서 DeleteSheet 요청을 실행합니다. POST 요청 본문에는 삭제할 시트의 sheetId만 포함되어야 합니다. 예를 들면 다음과 같습니다.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteSheet": {
"sheetId": sheetId
}
}
],
}개별 시트의 sheetId를 가져오려면 스프레드시트 spreadsheets.get 메서드를 사용합니다.
행 데이터 검색
행 목록 피드는 Sheets API v3에서 스프레드시트의 셀 내 데이터에 액세스하기 위해 제공하는 두 가지 메서드 중 하나입니다 (다른 하나는 셀 피드). 행 피드는 일반적인 스프레드시트 작업 (행별로 읽기, 행 추가, 정렬)을 지원하기 위한 것이지만, 특정 작업에는 적합하지 않도록 특정 가정을 합니다. 특히 목록 피드는 빈 행이 피드 종료이고 필수 헤더가 시트의 첫 번째 행에 있다고 가정합니다.
반면 Sheets API v4는 행별 액세스 메서드를 사용하지 않습니다. 대신 A1 표기법을 사용하여 필요한 특정 범위를 참조하여 시트 셀 데이터에 액세스합니다. 범위는 셀 블록, 전체 행, 전체 열 또는 전체 시트일 수 있습니다. API는 서로 연결되지 않은 셀 집합에 액세스할 수도 있습니다.
v3 API
특정 워크시트의 목록 기반 피드의 URL을 확인하려면 워크시트 피드를 가져와 관심 있는 워크시트 항목에서 목록 피드 URL을 찾습니다.
목록 기반 피드를 검색하려면 적절한 승인 헤더를 사용하여 목록 피드 URL에 GET 요청을 보냅니다. 예를 들면 다음과 같습니다.
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
이 요청에 대한 응답에는 무엇보다도 특정 행에 해당하는 항목이 포함됩니다. 개별 셀은 (필수) 시트 헤더 행에 제공된 이름으로 참조됩니다. 예를 들어 다음은 단일 행 항목입니다.
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>10</gsx:hours>
<gsx:items>2</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
기본적으로 목록 피드에 반환되는 행은 행 순서로 반환됩니다. Sheets API v3에서는 이 순서를 변경하는 쿼리 매개변수를 제공합니다.
역순:
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full?reverse=true
특정 열을 기준으로 정렬하려면 다음 단계를 따르세요.
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?orderby=column:lastnameSheets API v3를 사용하면 구조화된 쿼리 (열 헤더에서 참조)를 통해 특정 행을 필터링할 수도 있습니다.
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
?sq=age>25%20and%20height<175v4 API
Sheets API v4를 사용하면 spreadsheets.values.get 또는 spreadsheets.values.batchGet 메서드를 사용하여 범위별로 행을 가져올 수 있습니다. 예를 들어 다음은 'Sheet1'의 모든 행을 반환합니다.
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1
이 요청에 대한 응답은 다음과 유사한 구조를 갖습니다.
{
"range": "Sheet1",
"majorDimension": "ROWS",
"values": [["Name", "Hours", "Items", "IPM"],
["Bingley", "10", "2", "0.0033"],
["Darcy", "14", "6", "0.0071"]]
}전체 행, 열 또는 시트를 검색할 때 빈 셀은 응답에 포함되지 않습니다.
Sheets API v4에는 Sheets API v3에서 제공하는 행 순서 쿼리 매개변수와 동등한 매개변수가 없습니다. 역순은 간단합니다. 반환된 values 배열을 역순으로 처리하면 됩니다. 열별 정렬은 읽기에 지원되지 않지만 SortRange 요청을 사용하여 시트에서 데이터를 정렬한 후 읽을 수 있습니다.
Sheets API v4에는 현재 Sheets API v3의 구조화된 쿼리와 직접적으로 상응하는 항목이 없습니다. 하지만 애플리케이션에서 필요에 따라 관련 데이터를 검색하고 정렬할 수 있습니다.
새 데이터 행 추가
두 API 중 하나를 사용하여 시트에 새 데이터 행을 추가할 수 있습니다.
v3 API
특정 시트의 목록 기반 피드의 URL을 확인하려면 시트 피드를 가져와서 관심 있는 시트 항목에서 게시물 URL을 찾습니다.
데이터 행을 추가하려면 적절한 승인 헤더를 사용하여 게시 URL에 POST 요청을 보냅니다. 예를 들면 다음과 같습니다.
POST https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full
POST 요청의 본문에는 추가할 행 데이터 항목이 포함되어야 하며, 개별 셀은 열 헤더에서 참조합니다.
<entry xmlns="http://www.w3.org/2005/Atom"
xmlns:gsx="http://schemas.google.com/spreadsheets/2006/extended">
<gsx:hours>2</gsx:hours>
<gsx:ipm>0.5</gsx:ipm>
<gsx:items>60</gsx:items>
<gsx:name>Elizabeth</gsx:name>
</entry>
지정된 시트의 끝에 새 행이 추가됩니다.
v4 API
Sheets API v4를 사용하면 spreadsheets.values.append 메서드를 사용하여 행을 추가할 수 있습니다. 다음 예에서는 스프레드시트의 'Sheet1'에 있는 마지막 표 아래에 새 데이터 행을 씁니다.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/append/Sheet1
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}또한 Sheets API v4를 사용하면 spreadsheets.batchUpdate에서 AppendCells 요청을 사용하여 특정 속성과 형식이 지정된 셀을 추가할 수 있습니다.
새 데이터로 행 수정하기
두 API 모두 행 데이터를 새 값으로 업데이트할 수 있습니다.
v3 API
데이터 행을 수정하려면 목록 피드를 검토하여 업데이트하려는 행의 항목을 찾습니다. 필요에 따라 항목의 콘텐츠를 업데이트합니다. 사용하는 항목의 ID 값이 기존 항목의 ID와 정확하게 일치하는지 확인합니다.
항목이 업데이트되면 적절한 승인 헤더를 사용하여 항목을 요청 본문으로 포함하는 PUT 요청을 해당 행 항목에 제공된 edit URL로 전송합니다. 예를 들면 다음과 같습니다.
PUT https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
<entry gd:etag='"S0wCTlpIIip7ImA0X0QI"'>
<id>rowId</id>
<updated>2006-11-17T18:23:45.173Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#list"/>
<title type="text">Bingley</title>
<content type="text">Hours: 10, Items: 2, IPM: 0.0033</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version"/>
<gsx:name>Bingley</gsx:name>
<gsx:hours>20</gsx:hours>
<gsx:items>4</gsx:items>
<gsx:ipm>0.0033</gsx:ipm>
</entry>
v4 API
Sheets API v4를 사용하면 수정하려는 행의 A1 표기법을 사용하여 행을 수정하고 spreadsheets.values.update 요청을 실행하여 해당 행을 덮어쓸 수 있습니다. 지정된 범위는 행의 첫 번째 셀만 참조하면 됩니다. API는 요청과 함께 제공된 값을 기반으로 업데이트할 셀을 추론합니다. 대신 셀 다중 범위를 지정하는 경우 제공하는 값이 해당 범위에 포함되어야 합니다. 그렇지 않으면 API에서 오류를 반환합니다.
다음 요청 및 요청 본문은 'Sheet1'의 네 번째 행에 데이터를 추가합니다.
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet1!A4
{
"values": [["Elizabeth", "2", "0.5", "60"]]
}spreadsheet.values.batchUpdate 메서드에서 행 데이터를 업데이트할 수도 있습니다. 행 또는 셀을 여러 번 업데이트하는 경우 이 메서드를 사용하는 것이 더 효율적입니다.
또한 Sheets API v4를 사용하면 spreadsheets.batchUpdate에서 UpdateCells 또는 RepeatCell 요청을 사용하여 셀 속성과 셀 형식을 수정할 수 있습니다.
행 삭제
두 API 모두 행 삭제를 지원합니다. 삭제된 행은 스프레드시트에서 삭제되고 그 아래 행은 하나씩 위로 이동합니다.
v3 API
행을 삭제하려면 먼저 목록 피드에서 삭제할 행을 가져온 다음 행의 항목에 제공된 edit URL에 DELETE 요청을 전송합니다.
행을 업데이트하는 데 사용된 것과 동일한 URL입니다.
DELETE https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full/rowId/version
가져온 이후 다른 클라이언트에서 변경된 행을 삭제하지 않으려면 원래 행의 ETag 값이 포함된 HTTP If-Match 헤더를 포함합니다. 항목 요소의 gd:etag 속성을 검사하여 원래 행의 ETag 값을 확인할 수 있습니다.
가져온 이후 다른 사용자가 행을 업데이트했는지와 관계없이 행을 삭제하려면 If-Match: * 를 사용하고 ETag를 포함하지 마세요. 이 경우 삭제하기 전에 행을 검색할 필요가 없습니다.
v4 API
Sheets API v4를 사용하여 행을 삭제하는 작업은 DeleteDimension 요청을 사용하여 spreadsheet.batchUpdate 메서드 호출로 처리됩니다. 이 요청은 열을 삭제하는 데도 사용할 수 있으며 개발자는 행 또는 열의 일부만 삭제하도록 선택할 수 있습니다. 예를 들어 다음은 지정된 ID가 있는 시트의 6번째 행을 삭제합니다 (행 색인은 0부터 시작하며 시작 인덱스는 포함하고 종료 인덱스는 제외함).
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
{
"requests": [
{
"deleteDimension": {
"range": {
"sheetId": sheetId,
"dimension": "ROWS",
"startIndex": 5,
"endIndex": 6
}
}
}
],
}시트의 sheetId는 spreadsheet.get 메서드를 사용하여 가져올 수 있습니다.
셀 데이터 검색
Sheets API v3는 스프레드시트에 저장된 모든 데이터에 대한 기본 액세스를 위한 셀 피드를 제공합니다. 읽기 액세스의 경우 셀 피드는 전체 시트 콘텐츠 또는 일련의 쿼리 매개변수로 정의된 시트 셀 범위를 단일 블록으로만 제공할 수 있습니다. 중복되지 않는 범위는 추가 GET 요청을 사용하여 별도로 가져와야 합니다.
Sheets API v4는 시트에서 여러 개의 중복되지 않는 범위를 포함하여 모든 셀 데이터 집합을 검색할 수 있습니다. Sheets API v3는 셀 콘텐츠를 입력 값 (사용자가 키보드로 입력하는 값) 또는 수식의 출력값 (숫자인 경우)으로만 반환할 수 있습니다. Sheets API v4는 값, 수식, 서식, 하이퍼링크, 데이터 유효성 검사, 기타 속성에 대한 전체 액세스 권한을 부여합니다.
v3 API
특정 워크시트의 셀 기반 피드의 URL을 확인하려면 워크시트 피드를 살펴보고 관심 있는 워크시트 항목에서 셀 피드 URL을 찾습니다.
셀 기반 피드를 검색하려면 적절한 승인 헤더를 사용하여 셀 피드 URL로 GET 요청을 보냅니다. 예를 들면 다음과 같습니다.
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
셀은 행 및 열 번호를 사용하여 참조됩니다. max-row, min-row, max-col, min-col 쿼리 매개변수를 사용하여 특정 범위를 하나만 가져올 수 있습니다. 예를 들어 다음은 2행부터 열 4 (D)의 모든 셀을 검색합니다.
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
?min-row=2&min-col=4&max-col=4Sheets API v3는 검색된 셀의 inputValue를 반환합니다. 이 값은 사용자가 셀을 조작하기 위해 Google Sheets 사용자 인터페이스에 입력하는 값입니다. inputValue은 리터럴 값 또는 수식일 수 있습니다. API는 수식이 숫자로 반환되는 경우와 같이 numericValue를 반환하기도 합니다. 예를 들어 응답에는 다음과 유사한 구조의 셀 항목이 포함될 수 있습니다.
<entry gd:etag='"ImB5CBYSRCp7"'>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4</id>
<updated>2006-11-17T18:27:32.543Z</updated>
<category scheme="http://schemas.google.com/spreadsheets/2006"
term="http://schemas.google.com/spreadsheets/2006#cell"/>
<title type="text">D4</title>
<content type="text">5</content>
<link rel="self" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4"/>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R9C4/srevc"/>
<gs:cell row="4" col="4" inputValue="=FLOOR(C4/(B4*60),.0001)"
numericValue="5.0">5</gs:cell>
</entry>
v4 API
관심 있는 범위의 spreadsheets.values.get 또는 spreadsheets.values.batchGet 메서드를 각각 호출하여 셀 데이터를 가져옵니다. 예를 들어 다음은 'Sheet2'의 D열에 있는 셀을 2번 행부터 열 우선 순서로 반환하고 입력된 대로 수식을 반환합니다 (뒤의 빈 셀은 생략됨).
GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/Sheet2!D2:D?majorDimension=COLUMNS&valueRenderOption=FORMULA
이 요청에 대한 응답은 다음과 유사한 구조입니다.
{
"spreadsheetId": spreadsheetId,
"valueRanges": [
{"range": "Sheet2!D2:D",
"majorDimension": "COLUMNS",
"values": [["Widget", 234, "=FLOOR(C4/(B4*60),.0001)", "=D4\*1000"]]
}]
}여러 범위의 셀 데이터를 검색하려면 spreadsheet.values.batchGet을 사용하는 것이 더 효율적입니다. 형식과 같은 셀 속성에 액세스하려면 spreadsheet.get 메서드가 필요합니다.
셀 수정
Sheets API v3를 사용하면 수정된 셀 항목을 요청 본문으로 사용하여 셀 피드에 PUT 명령어를 실행하여 셀 콘텐츠를 수정할 수 있습니다.
반면 Sheets API v4는 셀 콘텐츠를 변경하기 위한 spreadsheets.values.update 및 spreadsheets.values.batchUpdate 메서드를 제공합니다.
v3 API
단일 셀의 콘텐츠를 수정하려면 먼저 셀 피드에서 셀 항목을 찾습니다.
항목에 수정 URL이 포함되어 있습니다. 셀에 포함할 내용을 반영하도록 항목을 업데이트한 다음 업데이트된 셀 항목을 요청 본문으로 사용하여 수정 URL에 PUT 요청을 실행합니다. 예를 들어 다음은 SUM 수식이 포함되도록 D2 (R2C4) 셀을 업데이트합니다.
PUT https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full//R2C4/srevc<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gs="http://schemas.google.com/spreadsheets/2006"> <id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id> <link rel="edit" type="application/atom+xml" href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4"/> <gs:cell row="2" col="4" inputValue="=SUM(A1:B6)"/> </entry>
v4 API
Sheets API v4에서 단일 셀을 수정하려면 spreadsheets.values.update 메서드를 사용하면 됩니다. 이 메서드에는 입력 데이터가 Sheets UI에 입력된 것처럼 처리되는지 (USER_ENTERED) 아니면 파싱되지 않고 있는 그대로 가져오는지 (RAW) 지정하는 ValueInputOption 쿼리 매개변수가 필요합니다. 예를 들어 다음은 수식으로 D2 셀을 업데이트합니다.
PUT https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values/D2?valueInputOption=USER_ENTERED
{"values": [["=SUM(A1:B6)"]]}여러 셀을 수정하는 경우 spreadsheets.values.batchUpdate 메서드를 사용하여 한 번의 요청으로 수정합니다.
일괄 요청을 통해 여러 셀 수정
두 API 모두 단일 (일괄) 요청으로 여러 셀의 콘텐츠를 변경하는 수단을 제공합니다. 일괄 요청에서 참조하는 셀은 연속된 범위에 있을 필요가 없습니다.
일괄 처리의 셀 수정 중 하나 이상이 실패하는 경우 Sheets API v3를 사용하면 다른 수정은 성공할 수 있습니다. 그러나 Sheets API v4는 일괄 업데이트 중 하나라도 실패하면 오류를 반환하고 이 경우 업데이트를 적용하지 않습니다.
v3 API
여러 셀을 수정하려면 먼저 워크시트의 셀 피드를 가져옵니다. 항목에 일괄 URL이 포함되어 있습니다. 업데이트하려는 셀과 새 셀 콘텐츠를 설명하는 요청 본문과 함께 이 URL에 POST 요청을 보냅니다. POST 요청 및 요청 본문의 구조는 다음과 유사합니다.
POST https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/batch
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:batch="http://schemas.google.com/gdata/batch"
xmlns:gs="http://schemas.google.com/spreadsheets/2006">
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full</id>
<entry>
<batch:id>request1</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C4/version"/>
<gs:cell row="2" col="4" inputValue="newData"/>
</entry>
...
<entry>
<batch:id>request2</batch:id>
<batch:operation type="update"/>
<id>https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5</id>
<link rel="edit" type="application/atom+xml"
href="https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full/R2C5/version"/>
<gs:cell row="5" col="2" inputValue="moreInfo"/>
</entry>
</feed>
batch:id 필드는 일괄 처리 내에서 요청을 고유하게 식별해야 합니다.
셀 수정 시 batch:operation 필드는 update여야 합니다. gs:cell는 행 및 열 번호로 셀을 식별하고 여기에 삽입할 새 데이터를 제공합니다. id에는 업데이트할 셀의 전체 URL이 포함됩니다.
link에는 셀 ID의 전체 경로가 포함된 href 속성이 있어야 합니다. 이러한 필드는 항목마다 모두 필요합니다.
v4 API
Sheets API v4는 spreadsheets.values.batchUpdate 메서드를 통해 셀 값을 일괄 수정할 수 있도록 지원합니다.
여러 셀을 수정하려면 요청 본문에 데이터 변경사항이 지정된 POST 요청을 실행하면 됩니다. 예를 들면 다음과 같습니다.
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId/values:batchUpdate
{
"valueInputOption": "USER_ENTERED"
"data": [
{"range": "D4",
"majorDimension": "ROWS",
"values": [["newData"]]
},
{"range": "B5",
"majorDimension": "ROWS",
"values": [["moreInfo"]]
}
]
}단일 셀을 범위로 지정한 경우 제공된 모든 값이 해당 셀을 왼쪽 상단 좌표로 시작하여 시트에 쓰여집니다. 대신 다중 셀 범위를 지정하는 경우 제공하는 값이 해당 범위에 정확하게 일치해야 합니다. 그렇지 않으면 API에서 오류를 반환합니다.