２０１４・１１時点の自分勉強用の翻訳
イントロダクション
このガイドはGoogle Sheets API Version3について記載します。
このAPIで何ができるか？
このAPIは以下のことに役立ちます。
・Googleシートファイルの中のワークシートを操作する
・ワークシートの行に書き込む
・ワークシート内のセルの位置をシてして操作する。
一般的な使用例は次のとおりです。
・アクセスできないシステムに格納されている財務データを計算する
・Webブラウザでユーザーに統計を表示
・ユーザーがスプレッドシートにデータを入力
対象読者
このガイドはGoogleスプレッドシートAPIを使用するテクニカルリファレンスを必要とする開発者を対象としています。
このガイドはグーグルの開発エンジニアによって書かれ、このAPIの正式なリファレンスです。
用語の定義
スプレッドシート
ユーザーインターフェースか、Google Drive APIで作成されたGoogleシートドキュメント
ワークシート
スプレッドシート内のセルの名前つきコレクション。すべてのスプレッドシートは最低ひとつのワークシートをもちます。
デフォルトでは１シートです。
リスト行
ワークシート内のキーと値のペアからなるセルの行。APIを使う場合はワークシートの最初の行は常にヘッダとみなされる。
各業にキーを行名として定義する必要がある。
セル
ワークシートのデータのひとつ
どのAPIをバージョンを使用するのか？
バージョン3.0はAPI利用ができる唯一のバージョンです。
APIの以前のバージョンを使う利点はありません。バージョン３．０はAPI1,2のスーパーセットです。
バージョン１、２で書かれたコー度は2012年10月２０日で利用できなくなりました。
追加のリソースおよびこのガイドについての情報
時々、このドキュメントには予期せぬ間違いがあります。
それがあなたに起きた場合は大変申し訳ない。フォーラムやバグ提出をお願いいたします。
クライアントライブラリーの設定
クライアントライブラリーはさまざまなプログラミング言語で提供されます。小ライアンとライブラリーを使うことでシートAPIを簡単に使うことができます。
このセクションではプロトコルレベルでシートAPIを使う人には関係ありませんが、GDataクライアントライブラリーを使ってアプリケーションを開発する人には関係があります。
（パッケージの導入は割愛：ライブラリーのインクルードについては各ライブラリーのひな形を参照のこと）
リクエストの承認
アプリケーションがパブリックでないユーザーデータを要求すると、許可トークンを必要とします。
トークンはまた、Googleアプリケーションを特定します。
承認プロトコルについて
OAuth2.0の承認プロセスを使う必要があります。
（OAuth1.0は2015年3月５日で停止されます。）
OAuth2.0の承認
パプリックでないユーザーデータのGoogleスプレッドシートAPIへのリクエストは、認証されたユーザーによって承認されねばなりません。
OAuth2.0の承認プロセスは、アプリケーションの種類により異なりますが、一般的には次のような流れです。
1. Googleに作成するアプリケーションを登録。GoogleはクライアントIDとクライアント・シークレットキーを提供します。
2. アプリケーションがユーザーデータにアクセスする時、アクセスするスコープをGoogleに要求します。
3. Googleは承認を求めてユーザーにOAuthのダイアログを表示します。
4. ユーザーが承認すると、Googleはアクセストークンを提供します。このトークンは時間制限があります。
5. アプリケーションはアクセストークンと共にユーザーデータを要求します。
6. Googleがアクセストークンが有効だと認めると、要求されたデータを処理します。
一部のフローでは、アクセストークンを新規に撮り直すために、リフレッシュトークンを使うなどの追加のステップが必要です。
アプリケーションの様々なフローの詳細はGoogle OAuth2.0のマニュアルを参照してください。
GootldeスプレッドシートAPIのOAuth2.0へ提示するスコープ情報は次のとおりです。
https://spreadsheets.google.com/feeds
さらに、アプリケーションがスプレッドシートを作成すしたり、メタデータを操作する場合は、Googlde Drive APIのスコープが必要です。
それについては、Google Drive APIのChoose Auth Scopeの部分を見てください。
OAuth2.0を使って要求するには、アプリケーションはスコープ情報だけではなく、Googleに登録したクライアントID、クライアントシークレットを必要とします。
OAuth2.0の実行
（コードなので省略）
バージョンを指定する
GoogleシートAPIは必要ないです。すべてバージョン3.0です。
ノート：GoogleシートAPIのクライアントライブラリは自動的に適切なバージョンを設定します。
プロトコル
GData-VersionのHTTPヘッダーは以下のようになります。
GData-Version: 3.0
別にURLパラメータとして渡すこともできます。
https://spreadsheets.google.com/feeds/spreadsheets/private/full?v=3.0
スプレッドシートの作成
GoogleドライブAPIを使って新しいスプレッドシートファイルをアップロードすることで新しいスプレッドシートを作ることができます。
シートAPIは現在、スプレッドシートを削除する方法は提供していません。しかし、Google Drive APIのテスト用としては提供されています。
シートAPIのURL,見え方、プロジェクション
シートAPIは要求されたURLの見え方と、プロジェクションをサポートします。
見え方は認証するかどうかできまります。
プロジェクションはどのデータを要求に応じて返すかを決定します。どちらもAPIへの要求するURLにセットします。
例えばシートAPIに
https://spreassheets.google.com/feeds/worksheets/key/private/full
このようなURLは、フィードによるレスポンス中にさまざまなリンクエレメントを入れてシートAPIにより返されます。
APIを使う時、アプリケーションはキーワードのprivateやfullを変更することができ、それによりソースの要求をキーワードにより変更せることがｄけいます。
つまり、以下のようなAPI要求が可能ということです。
GET https://spreadsheets.google.com/feeds/worksheets/key/private/basic
各ワークシートエントリーのセルのフィードURLのリストを得るには
https://spreadsheets.google.com/feeds/cells/key/worksheetId/private/basic
されにそれぞれのワークシートのフィードURLのリストを得るには
https://spreadsheets.google.com/feeds/list/key/worksheetId/private/basic
プロジェクションbasicはすでに生成されたURLに設定されています。同じことが見え方のpublicにも適用されます
他に可能なパラメータは見え方ではprivate、プロジェクションではfullです。
見え方のprivateはpublicと置き換えることがｄけいます。publicはスプレッドシートが”WEBに公開”されている認証なしの状態のようにフィードを扱うことができます。
見え方のpublicはワークシート、リスト、セルのフィードをサポートします。
見え方publicはウェブページのjabascriptなどから操作する場合に便利です。
ウェブにスプレッドシートを公開するにはファイル＞ウェブに公開をGoogle シートユーザーインターフェースからやって、「公開」を選んでください。
警告：見え方publicを使ったAPIの要求は”WEBへの公開”の状態でHTTP 400 Bad Reqestが帰った場合、ｋのURLのスプレッドシートが発見できなかった場合です。 スプレッドシートが削除されていないか、正しいURLか確認してください。
警告：見え方publicは”見え方オプション”で共有をあらわす”WEB上での共有”としては動作しません。
”ウェブ上へに公開”と”ウェブ上で共有”は違うのです。我々はこの混乱に気づいています。将来のバージョンのAPIでは対応がされるでしょう。今は、混乱しないでくださいということです。
プロジェクションfullはプロジェクションbasicと置き換え、より情報おｗ絞ることができます。（例えば巣内フィールド、重要なデータのみ）
これは帯域が狭い場合に有効です。プロジェクトションbasicはワークシート、リスト、セルのフィードをサポートしています。
スプレッドシートの一覧の取得
GoogleシートAPIは認証されたユーザーのスプレッドシートの一覧を取得することができます。
しかし、スプレッドシートをこのAPIで作成、削除できないことに注意してください。これらの操作にはGoogle Drive APIを使ってください。
このAPIの操作は認証された要求でのみ可能です。要求はフィードに認証なしでは処理されません。
注意：スプレッドシートのフィードは見え方privateとプロジェクチョンfullのみがサポートされています。
プロトコル：
現在認証されたユーザーのスプレッドシートを使うには、以下のGET要求をします。
https://spreadsheets.google.com/feeds/spreadsheets/private/full
この要求はスプレッドシートのフィードのリストすべてを返します。
