Google Sheets API の紹介

Google Sheets API を使用すると、スプレッドシートの要素を読み取って変更できます。 スプレッドシートは多くの設定を備えており、美しく機能的なシートを作成することができます。そのため、この API にも多くの設定があります。 この API は主に次の 2 の方法でスプレッドシートと連携します。

これらのコレクションはどちらも簡単に使用できますが、spreadsheets コレクションには、より多くのオプションがあります。 これらのコレクションとその使用方法の詳細については、上記のリファレンス ドキュメントのリンク先または次のデベロッパー ガイドをご覧ください。

一般的な用語

このセクションでは、Sheets API に関するドキュメントで使用されている用語を説明します。

スプレッドシート ID

すべての API メソッドには、アクセスまたは変更するスプレッドシートの識別に使用される spreadsheetId パラメータが必要です。 この ID は、スプレッドシートの URL で "/d/" と "/edit" の間にある値です。 Google スプレッドシートを参照する次の URL を例として取り上げます。

https://docs.google.com/spreadsheets/d/1qpyC0XzvTcKT6EISywvqESX3A0MwQoFDE8p-Bll4hps/edit#gid=0

このスプレッドシート ID は 1qpyC0XzvTcKT6EISywvqESX3A0MwQoFDE8p-Bll4hps です。

スプレッドシート ID は、文字、数字、いくつかの特殊文字で構成される文字列です。 次の正規表現を使用すると、Google スプレッドシートの URL からスプレッドシート ID を抽出できます。

/spreadsheets/d/([a-zA-Z0-9-_]+)

Drive API に精通している方は、spreadsheet_idファイル リソースの ID に対応していることが理解できるでしょう。

シート ID

スプレッドシートの個々のシートには、タイトル(一意にする必要があります)と ID があります。 多くの場合、Sheets API では sheetId を使用して、読み取るシートまたはアップデートするシートを指定します。 スプレッドシートの UI では、開いてるスプレッドシートの URL にある gid パラメータの値を見れば、開いているシートの sheetId がわかります。

sheetId を見つけることができる URL の構造を次に示します。

https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=sheetId

シート ID は数値です。次の正規表現を使用して、Google スプレッドシートの URL からシート ID を抽出できます。

[#&]gid=([0-9]+)

API を使用して、シートの ID をフェッチすることもできます。詳細は、シートの ID とその他のプロパティの判別にあるサンプルをご覧ください。

A1 表記

一部の API メソッドでは、A1 表記の範囲が必要です。 この範囲は Sheet1!A1:B2 のような文字列で表され、スプレッドシート内のセルのグループを示します。通常、この文字列は式で使用されます。

有効な範囲の例は次のとおりです。

  • Sheet1!A1:B2 は Sheet1 の先頭 2 行にある最初の 2 つのセルを指します。
  • Sheet1!A:A は Sheet1 の先頭列にあるすべてのセルを指します。
  • Sheet1!1:2 は Sheet1 の先頭 2 行にあるすべてのセルを指します。
  • Sheet1!A5:A は Sheet 1 の先頭列にある 5 行目以降のすべてのセルを指します。
  • A1:B2 は最初に表示されるシートの先頭 2 行にある最初の 2 つのセルを指します。
  • Sheet1 は Sheet1 のすべてのセルを指します。

名前付き範囲もサポートされています。 名前付き範囲がシートの名前と競合する場合は、名前付き範囲が優先されます。

日付 / 時刻のシリアル番号

Google スプレッドシートでは、他の大部分のスプレッドシート アプリケーションと同じように、日付 / 時刻の値が 10 進値として処理されます。 そのため、スプレッドシートで式による日付 / 時刻の計算が可能です。つまり、日や週を増分したり、2 つの日付 / 時刻を加減算したり、その他の同様の操作を実行できます。

Google スプレッドシートは、スプレッドシートで一般的に使用されるエポック日付の形式を使用します。値の整数部(小数点の左側)は、1899 年 12 月 30 日からの経過日数を示します。 小数部(小数点の右側)は、時刻を 1 日の端数として表します。 たとえば、1900 年 1 月 1 日正午は 2.5 として表されます。つまり、1900 年 1 月 1 日は 1899 年 12 月 30 日の 2 日後なので 2、正午は 1 日の半分なので .5 になります。1900 年 2 月 1 日午後 3 時は 33.625 になります。

Google スプレッドシートでは、1900 年をうるう年としてではなく、通常の年として正しく処理しています。

部分的なレスポンス

スプレッドシートは広いので、多くの場合、スプレッドシートのすべての部分が必要とは限りません。 fields URL パラメータを使用すると、Google Sheets API のレスポンスで返される要素を制限できます。 このパラメータは、spreadsheets.get メソッドで特に有用です。 パフォーマンスを最適化するには、応答で必要になるフィールドのみを明示的にリストします。 fields パラメータの形式は、フィールドマスクの JSON エンコードの場合と同じです。 つまり、異なる複数のフィールドはコンマで、サブフィールドはドットで区切ります。 また、同じ種類のサブフィールドは丸括弧の中に列記しておくと便利です。

たとえば、スプレッドシートのタイトル、シートのプロパティ、範囲 A1:C10 の値と形式を取得する場合は、次のリクエストを使用できます。

GET https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId?ranges=A1:C10&fields=properties.title,sheets(sheetProperties,data.rowData.values(effectiveValue,effectiveFormat))

フィードバックを送信...