このページは Cloud Translation API によって翻訳されました。

Sheets API v3 からの移行

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 からエラーが返されます。

Sheets API v3 からの移行

表記と用語

リクエストの承認

v3 API

v4 API

公開設定

v3 API

v4 API

予測

v3 API

v4 API

スプレッドシートを作成する

v3 API

v4 API

認証されたユーザーのスプレッドシートを一覧表示する

v3 API

v4 API

シートのメタデータを取得する

v3 API

v4 API

スプレッドシートにシートを追加する

v3 API

v4 API

シートのタイトルとサイズを変更する

v3 API

v4 API

シートを削除する

v3 API

v4 API

行データを取得する

v3 API

v4 API

データの新しい行を追加する

v3 API

v4 API

新しいデータを含む行を編集する

v3 API

v4 API

行を削除する

v3 API

v4 API

セルデータを取得する

v3 API

v4 API

セルを編集する

v3 API

v4 API

バッチ リクエストで複数のセルを編集する

v3 API

v4 API

バッチリクエストで複数のセルを編集する