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 を割り当てます。このページでは、これは rowId プレースホルダで表されます。
リクエストの承認
アプリを実行すると、ユーザーに特定の権限を付与するように求められます。アプリで指定するスコープによって、要求する権限が決まります。
v3 API
Sheets API v3 は、単一の承認スコープで動作します。
https://spreadsheets.google.com/feeds
これは Pod のエイリアス
https://www.googleapis.com/auth/spreadsheets
どちらのスコープ形式も使用できます。
v4 API
Sheets API v4 では、次のスコープのセットが 1 つ以上使用されます。
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
アプリケーションでユーザーのスプレッドシートやシート プロパティを編集する必要がない場合は、読み取り専用のスコープを使用します。アプリケーションで一般的なドライブ アクセスが必要ない場合は、ドライブ スコープではなくスプレッドシート スコープを使用します。
公開設定
古いバージョンの 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 で使用できる投影設定は 2 つだけです。full
投影は利用可能なすべての情報を返しますが、basic
はより小さな固定されたデータ サブセット(ワークシート、リスト、セルフィード用)を返します。可視性と同様に、投影は API エンドポイントで(公開設定の後に)指定する必要があります。
https://spreadsheets.google.com/feeds/worksheets/spreadsheetId/public/basic
basic
投影によって提供されるデータのサブセットは、コードの効率化に役立ちますが、カスタマイズはできません。
v4 API
Sheets API v4 は完全なデータセットを返すことができますが、Sheets API v3 の basic
公開設定に類似した固定サブセットは定義していません。spreadsheet コレクションのメソッドでは、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 では、このような操作は行っていません。スプレッドシートの選択には、drive.file のスコープを Google Picker と組み合わせて使用するようにアプリを移行することをおすすめします。
スプレッドシートを一覧表示する必要がある場合は、Drive API Files.list メソッドで mimeType
クエリを使用して複製できます。
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 エンドポイントからアクセスできます(適切な Authorization ヘッダーを使用)。
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 が含まれています。ワークシートのメタデータを更新し、PUT
リクエストの本文として編集 URL に送信します。次に例を示します。
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 に用意されている 2 つのメソッドのうちの 1 つです(もう 1 つはセルフィードです)。行フィードは、一般的なスプレッドシート操作(行ごとの読み取り、行の追加、並べ替え)をサポートすることを目的としていますが、一部のタスクには適さないことが前提となります。具体的には、リストフィードでは、空白行がフィードの終了であり、シートの最初の行に必須のヘッダーが存在することを前提としています。
これに対して、Sheets API v4 では行固有のアクセス メソッドを使用しません。代わりに、A1 表記を使用して必要な特定の範囲を参照することで、シートのセルデータにアクセスします。範囲は、セルのブロック、行全体、列全体、またはシート全体のいずれかです。この API では、互いに素なセルのセットにアクセスすることもできます。
v3 API
特定のワークシートのリストベースのフィードの URL を確認するには、ワークシート フィードを取得し、目的のワークシート エントリでリストフィードの URL を見つけます。
リストベースのフィードを取得するには、適切な認証ヘッダーを使用して、GET
リクエストをリストフィードの URL に送信します。次に例を示します。
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:lastname
Sheets API v3 では、構造化クエリ(列ヘッダーで参照)を使用して特定の行をフィルタリングすることもできます。
GET https://spreadsheets.google.com/feeds/list/spreadsheetId/sheetId/private/full ?sq=age>25%20and%20height<175
v4 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" の 4 番目の行にデータを追加します。
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 も行の削除をサポートしています。削除された行はスプレッドシートから削除され、その下の行は 1 つ押し上げられます。
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 で行を削除するには、spreadsheet.batchUpdate メソッド呼び出しで DeleteDimension リクエストを使用します。このリクエストは、列を削除する場合にも使用されます。デベロッパーは、行または列の一部のみを削除することを選択できます。次の例では、指定した ID のシートの 6 行目を削除します(行インデックスはゼロベースで、startIndex と endIndex は含みません)。
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 を見つけます。
セルベースのフィードを取得するには、適切な認証ヘッダーを使用して、GET
リクエストをセルフィードの URL に送信します。次に例を示します。
GET https://spreadsheets.google.com/feeds/cells/spreadsheetId/sheetId/private/full
セルは行番号と列番号を使用して参照されます。特定の範囲を 1 つ取得するには、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=4
Sheets API v3 は、取得したセルの inputValue
を返します。この値は、ユーザーが Google スプレッドシートのユーザー インターフェースに入力してセルを操作します。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
1 つのセルのコンテンツを編集するには、まずセルフィードでセルのエントリを見つけます。エントリに編集 URL が含まれている。エントリを更新してセルに含める内容を反映してから、更新されたセルエントリをリクエストの本文に指定して、編集 URL に PUT
リクエストを発行します。次の例では、セル D2(R2C4)を更新して SUM
数式を含めます。
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 メソッドで単一のセルを編集できます。このメソッドには、入力データをスプレッドシート 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 メソッドを使用して、1 回のリクエストでそれらを発行します。
バッチ リクエストで複数のセルを編集する
どちらの API も、単一の(バッチ)リクエストで複数のセルのコンテンツを変更する手段を提供します。バッチ リクエストで参照されるセルが連続する範囲内にある必要はありません。
バッチで 1 つ以上のセルの編集が失敗した場合、Sheets API v3 では他のセルの編集が成功します。ただし、Sheets API v4 は、バッチ アップデートのいずれかが失敗した場合、エラーを返し、その場合、いずれの更新も適用しません。
v3 API
複数のセルを編集するには、まずワークシートのセルフィードを取得します。このエントリにはバッチ URL が含まれています。更新するセルと新しいセルの内容を記述したリクエスト本文とともに、POST
リクエストをこの URL に送信します。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 からエラーが返されます。