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
これは Namespace に
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
公開設定と同様の固定サブセットは定義されていません。スプレッドシート コレクションのメソッドでは、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 エンドポイントからアクセスできます。
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
このリクエストに対するレスポンスには、特に、特定の行に対応するエントリが含まれています。個々のセルは、(必須)シートのヘッダー行にある名前によって参照されます。たとえば、1 行のエントリは次のようになります。
<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 ヘッダーを含めます。元の行の ETag 値は、エントリ要素の gd: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 を見つけます。
セルベースのフィードを取得するには、適切な認証ヘッダーを使用して、セルフィード 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=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
リクエストを発行します。たとえば、次の例では、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 メソッドを使用して単一のセルを編集できます。このメソッドでは ValueInputOption
クエリ パラメータが必要です。このパラメータは、入力データをスプレッドシート UI に入力されたかのように扱うか(USER_ENTERED
)、解析せずにそのまま使用するか(RAW
)を指定します。たとえば、次のコードはセル 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"]] } ] }
1 つのセルを範囲として指定した場合、指定されたすべての値が、そのセルを左上の座標としてシートに書き込まれます。複数セルの範囲を指定する場合は、指定する値がその範囲に正確に一致する必要があります。そうでない場合、API はエラーを返します。