非公式:Google Reader API(グーグルリーダーAPI)(翻訳)

Googleリーダーは便利なアプリですが、私としてはどうしても普段利用しているメーラーである「Thunderbird」で読めるようにしたい。 Thunderbirdから既読が設定できるようにしたいし、iPhoneのBylineと連携もさせたい。

ThunderbirdとBylineでRSSをシンクロさせたい、というのがやってみたいことなのです。

というわけで、個人的にGoogleリーダーのAPIが必要になったので、翻訳を開始してみました。

Googleリーダーにアクセスするアプリを作りたい人は参考にしてみてください。 元記事はこちらです。

例によって意訳しまくりなので、気がついたところがあったらご指摘くださいね。

必要環境

以下の環境を必要とする(Cookieサポートの場合)。

  • httpクライアント
  • GETとPOSTメソッドのサポート
  • Cookieのサポート
  • httpsのサポート

httpsはGoogleから、認証用のSIDを取得するために必要。

CookieサポートはすべてのページにSIDを渡すために必要。

Cookie未サポートの場合、以下の環境が必要。

  • httpクライアント
  • GETとPOSTメソッドのサポート
  • (httpsを使って)SIDを取得するための外部ツール
  • Request時のheader情報にSIDを含めること

用語集

SID セッションID。 SIDはGoogleにログインする度に生成される。 SIDの有効期限はログアウトするまで。
ユーザーID 20文字で構成される、ユーザー識別の文字列。 内容を知っておく必要はなし。 user IDがなくてもGoogle Readerを操作することはできる。
トークン 特別な57文字の文字列。セッション定義のように利用されるが、もっと早くに期限切れになる。情報を変更する場合のダイレクト接続の際に必要となる。 トークンの有効期限は数分から数時間。 もしAPI呼び出しが失敗したら、新しいトークンを取得しないといけない。
クライアントID 使っているクライアントを定義する文字列。 たぶんログイン中の状態を定義するのに使われているか、いくつかクライアントを接続させるのに使われているらしいが、違うかもしれない。 昔のGoogleReaderは”lens"というUIを使っていて、今は”scroll”と言うUIを使っている。 このドキュメントを書くツールには”contact:ホスト名"が使われている。
アイテム/エントリー アイテムと言われたり、エントリーと言われたりしてるが、フィードの基本要素のこと。アイテムにはテキスト、タイトル、リンクが含まれているが、他にもプロパティがある。 RSS/Atomアグリゲーターはアイテムを収集する。(注:「アイテム」というのはRSS側の言葉で、「エントリー」はAtom側の言葉である)

認証

メモ:GoogleReaderサポートグループのミハイル・パルパリタによると、「認証部分が、APIをまだ公式にリリースできない理由の一つ」なのだそうだ。 なので、大きな変更があるかもしれないことを覚悟しておくように。

GoogleReaderにログインするには、https://www.google.com/accounts/ClientLogin にhttpsを使って以下のパラメーターをPOSTする必要がある。

POSTパラメーター名 POSTパラメーター値
service ‘reader’ ※
Email ログイン用メールアドレス
Passwd ログイン用パスワード
source クライアント文字列 ※
continue ‘http://www.google.com/’ ※

当然、「ログイン用メールアドレス」と「ログイン用パスワード」は、いつもGoogleにログインする時に使っているものだ。

※:これらのパラメーターはオプションらしい。 ちゃんとテストしてないが。 これらのパラメーターはブラウザー側でどう定義するかを決めるものだ。 思うに、sourceとserviceはgoogleのための情報で、google側が「必要だ」と要求してくるまでは要らないものじゃないかな。 彼らが何を考えているのかは私には分からないけども。 何も無いよりは、何らか作られた情報があった方がいいのかもしれないし、要らないかもしれない。 誰か知ってるかな…

クライアント文字列の定義に公式なルールはない。 詳しくはクライアントIDの項目を見て。

POSTアクションで送信した後、次のような形式でテキスト情報が返ってくる。

キー名=値

SIDというキー名にあるのが必要な値だ。

これを以下のようなプロパティで、自分でCookieに加えないといけない(googleがやってくれるわけではないみたい)。

name SID
domain .google.com
path /
expires 1600000000

もし、Cookieをサポートしていないクライアントを使っている場合は、すべてのリクエストに対してheader情報にこのCookieを含めるようにしないといけない。 Cookieが本当に必要な時にできるたった一つの作戦だ。

フィード・アグリゲーターのための3つのレイヤー

フィード・アグリゲーターを自作する場合、ことなる3つのレイヤーを作成する必要がある。

レイヤー1 フィードをパースするためのレイヤー。 これが難しい。 「でも、XMLだろ? 簡単じゃん」と思うだろう。 うん、確かにXMLだ。 だが、XMLとは互換性のないXMLフォーマットが10ヵ所もある(マーク・ピルグリムによるとRSSフォーマットに9箇所、Atomフォーマットに1箇所だ)。 ひょっとしたら、違った標準をフィーチャーした非標準のフィードを理解する必要があるかもしれない。
レイヤー2 データベースレイヤー。 一旦フィードをパースしたら、それをデータベースに保存しないといけない。 あと「既読」情報とかも。
レイヤー3 ユーザーインターフェース。

もちろん、レイヤー1~3にアクセスすることになる。 これがGoogle Readerのメイン部分なのだから。

URLスキーム

認証プロセスを除いて、すべてのGoogleReaderのURLリソースは「http://www.google.com/reader/」で始まるようになっている。 以下にそれらのURLと呼び方を書いておく。

URL この文書内での呼称 概要
http://www.google.com/reader/atom/ /atom/ この書き方で始まるURLはすべてAtomフィードを返す。 これがフィードコンテンツにアクセスするための(唯一の?)方法になる。 ここはレイヤー1、あるいはレイヤー1+レイヤー2にアクセスする手段となる。
http://www.google.com/reader/api/0/ /api/0/ メインAPIのエントリーポイント。 星をつけたり、タグを削除したりなど、アイテム/フィード情報の編集時に利用される。 これらの編集サービス利用時には、「OK」あるいは「」空文字が返される。 また、ここはフィードリストやタグリスト、未読のフィードやタグなどの設定にも利用される。 これらの利用時にはJSON形式やXML形式のオブジェクトデータを返す。 ここはレイヤー2のみの領域。
http://www.google.com/reader/view/ /view/ AJAXインターフェースは/view/アドレスによって行われる。 AJAXコードでは、/atom/や/api/0/を処理を行うためのサブレイヤーとして利用する。 これはレイヤー3にアクセスする方法。
http://www.google.com/reader/shared/ /shared/ 共有ページにはすべてこのURLを利用する。 共有ページには認証は使わない。
http://www.google.com/reader/settings/ /settings/ 全体の設定を調整するためのAJAXアプリケーション用。 主に/api/0/からの情報を操作する。

Atom形式のアイテム

ここでは、http://www.google.com/reader/atom/ で始まるURLについて説明する。

Google Readerのデータベースには非常に多くのアイテムが含まれている。 これらの中に、読んでいる記事リストがある(あなたのアカウントのGoogleリーダーでご存知の、フィード/タグの「全てのアイテム」だ)

アイテム関連の情報をゲットする唯一の方法は、アイテムのAtomセットを取得することだ。

全てのアイテムはフィードの中に含まれている。 アイテムを取得する1つの方法は、オリジナルフィードを問い合せることだ。

アイテムはカテゴリーに属している。 タグ/ラベルはカテゴリーだし、「既読」情報もカテゴリーだ。

アイテムを取得するもう一つの方法が、カテゴリーに属しているフィードを問い合せる方法だ。

アイテムセットの形式 概要
feed/ フィードURL 特定のフィードを取得するためのURL。 Google Readerがレイヤー1のみにアクセスする唯一の方法。 メモ:このサービスはアカウントに関連しているものではなく、登録しなくてもアクセスすることができる。
user/ ユーザーID label/ ラベル名 特定のラベルがついた全てのアイテムにアクセスすることができる形式。
user/ ユーザーID state/com.google/ 状態 read」や「starred」などの状態になっている全てのアイテムにアクセスすることができる形式。

ユーザーIDのところは、自分のアカウントで認証したユーザーIDを使います。

状態名 意味
read 既読状態のアイテム
kept-unread 「未読のままにする」がつけられたアイテム
fresh 取得したフィードで新しいアイテムが届くと「fresh」ラベルが付けられます。freshラベルが削除されたアイテムを探すと、見えなくなります。
starred スターを付けたアイテム
broadcast 共有したアイテム
reading-list すべてのアイテム。 「すべてのアイテム」を見たいときに、reading-listで問い合せます。
tracking-body-link-used 一度でも本文内のリンクをクリックしたアイテム。
tracking-emailed 一度でも誰かにメールしたアイテム。
tracking-item-link-used 一度でも本文内のリンクをクリックしたアイテム。
tracking-kept-unread 一度でも「未読のままにする」をつけたことがるアイテム。

Atom形式でアイテムを取得したい場合は、http://www.google.com/reader/atom/ に対して以上の語尾を追加して問い合わせてみてくれ。

たとえば、もし君がhttp://xkcd.com/rss.xmlのGoogle
Reader内でのフィードにアクセスしたい場合、http://www.google.com/reader/atom/feed/http://xkcd.com/rss.xml へ問い合せる。 これは君が定義しているいないに関わらずできることだ。 もし、最近読んだアイテムリスト全部を取得したい場合は次のように指定しよう。 http://www.google.com/reader/atom/user/-/state/com.google/read

それぞれのAtomセットはデフォルトで20個含まれている。 これは変更可能で、結果を変えるために次のようなパラメーターを付加することもできる。

GETパラメーター名 python Google Reader API名
n count アイテムセットに含めるアイテム数(デフォルトで20個)
client client デフォルトのクライアント名(上にあった用語集の「クライアント名」を見ておいて)
r order デフォルトでは、アイテムは現在のものから順に古いものが並んでいく。 値を「o」にすると古いものが1番にくる(デフォルト値は「d」)
ot start_time どの時間からのアイテムを取得するかを指定するための時間(UNIX TIME(1970/1/1 00:00 UTC)から計算した秒数で指定) 「order=o」とセットにしないと動作しない。 1ヶ月以上前を指定すると、自動的に1ヶ月前に指定し直される。
ck timestamp 現在のタイムスタンプ。 キャッシュを働かせないためのちょっとしたハックとして利用する。
xt exclude_target もう一つのアイテムセット取得の指定方法で、取得するものを除外できる。 たとえば、「未読」のものを取得する場合、この値は「feed/」や「user/」で始めて、「!http://」や「www」を含めないようにする。
c continuation 「続きを見る」処理に利用する。 それぞれのフィードは全てのアイテムを返さず、ある程度の数のアイテムを返すようになる。 Atomフィード内の(gr:continuationの下にある)文字がcontinuationと呼ばれているものだ。 そこに書いてある文字列をこのパラメーターで利用すると、次のアイテムを取得しようとする。

メモ:continuationに関しては特に意味はない。 次のアイテムを見つける手助けになるだけの文字列だ。 それ以外に、この値は使わないほうがいい。

例:xkcd.comのメインフィードで、未読分のうち17アイテムを取得する場合、次のようなURLになります。http://www.google.com/reader/atom/feed/http://xkcd.com/rss.xml?n=17&ck=1169900000&xt=user/-/state/com.google/read

API

この章は、http://www.google.com/reader/api/0/で始まるURLたちについてだ。

APIのコマンドには大きく2種類ある。

  • 編集コマンド
  • リストコマンド

数字の「0」の部分は、多分APIのバージョン番号だ。 この数字を使って、GoogleReaderは下位互換性を維持しながら変更を加えていくのだろう。

編集用API

Google Readerのデータベースに何らかの変更を加える場合、トークン(用語集を参照)が必要になる。 トークンを取得するには、http://www.google.com/reader/api/0/token へアクセスする。 すると、57文字の文字列を含んだ結果が返ってくる。 これがトークンだ。

トークン取得用のURLにはGETメソッド用のオプションパラメーターがある。

GETパラメーター名 python Google Reader API名
ck timestamp 現在のタイムスタンプ。 キャッシュを使わないようにするためのちょっとしたハック。
client client デフォルトのクライアント名(用語集を参照)

すべての編集コマンドでは情報取得にPOSTメソッドを使う(GETメソッドでは多分動作しない)が、一方で以下のパラメータはURLに付加して送信する。

GETパラメーター名 python Google Reader API名
client client デフォルトのクライアント名(用語集を参照)

全ての編集用コマンドは、失敗した場合に空文字が返ってくる。 成功すると「OK」の文字列が返ってくる。 もし失敗した場合は、(ひょっとすると)トークンが期限切れになっているかもしれない。 その時はまた新しいトークンを取得してみよう。 それでもまだOKが返ってこない場合は、それは本当に失敗していることになる。

購読や編集についてのPOSTパラメーターは以下の通り。

API呼び出し関数 POSTパラメーター名 python Google Reader API名
購読情報の編集(subscription/edit)
  s feed feed/フォーム内の編集先フィード名
  t title 編集する購読先のタイトル。新しい購読先を追加する場合や、購読先を変更する場合に利用する。
  a add user/フォーム内の追加するラベル(購読先ラベルはフォルダーと呼ばれる)
  r remove user/フォーム内の削除するラベル(購読先ラベルはフォルダーと呼ばれる)
  ac action 行うアクション。 知られているものとしては「edit」(フィードへラベル(またはフォルダー)を追加(または削除)する)、’subscribe’(購読する)、’unsubscribe’(購読をやめる)
  token token 義務用の期限付きトークン
タグ編集(tag/edit)
  s feed フィードとして見えているタグ/フォルダー名
  pub public ブーリアン文字列の「true」あるいは「false」。 trueの場合は、タグ/フォルダーは公開される。 falseの場合は、タグ/フォルダーの公開を停止する。
  token token 義務用の期限付きトークン
タグ編集(edit-tag)
  i entry 「タグ名:google.com」、「2005:reader/item…」などで表示されるアイテム中の、編集したいアイテム/エントリー。 (Atomフィードのエントリータグにあるxml
idで示される)
  a add user/フォーム内の追加したいラベル/状態。 (アイテム/エントリー上のラベルは、タグと呼ばれる)
  r remove user/フォーム内の削除したいラベル/状態。 (アイテム/エントリー上のラベルは、タグと呼ばれる)
  ac action アクション。 知られているものとしては、「edit」(フィードに対してラベル/フォルダーを追加/削除する)
  token token 義務用の期限付きトークン
タグの無効化(disable-tag)
  s feed フィードとして見えているタグ/フォルダー名
  ac action アクション。 知られているものとしては、「disable-tags」(タグ/フォルダーを削除する)
  token token 義務用の期限付きトークン

例:

新しいフィード(たとえば、http://xkcd.com/rss.xml )を購読先に追加する場合、

http://www.google.com/reader/api/0/subscription/edit?client=contact:myname-at-gmail

POSTパラメーター:s=http://xkcd.com/rss.xml&ac=subscribe&token=(有効なトークン文字列)

このフィードをフォルダー(たとえば、「comics」)に追加したい場合、

http://www.google.com/reader/api/0/subscription/edit?client=contact:myname-at-gmail

POSTパラメーター:s=http://xkcd.com/rss.xml&ac=edit&a=user/-/label/comics&token=(有効なトークン文字列)

修正すべき公開質問項目:

  • タグ編集(tag/edit)は、タグ編集(edit-tag)のエイリアス項目?
  • 他の呼び出しがアクションを必要とするなか、どうしてタグ/フォルダーの削除にアクションが必要じゃないのか?
  • なんでいくつものURLが存在するのか? アクション用パラメーターが冗長すぎないか?

リストAPI

これらの呼び出しはGETリクエストですべて行う。

呼び出すAPI関数 GETパラメーター名 python Google Reader API名 値/API呼び出しの説明
タグ/リスト(tag/list) タグリストと、それぞれのタグ共通のstatusを取得する
  output output 返ってくるデータのフォーマットを指定。 ’json’や’xml’が使える
  ck timestamp 現在のタイムスタンプ。 キャッシュを使わないようにするためのちょっとしたハック。
  client client デフォルトのクライアント名(用語集を参照)
登録/リスト(subscription/list) 登録フィードのリストと、それぞれのタグ共通のstatusを取得する
  output output 返ってくるデータのフォーマットを指定。 ’json’や’xml’が使える
  ck timestamp 現在のタイムスタンプ。 キャッシュを使わないようにするためのちょっとしたハック。
  client client デフォルトのクライアント名(用語集を参照)
初期設定/リスト(preference/list)  
  output output 返ってくるデータのフォーマットを指定。 ’json’や’xml’が使える
  ck timestamp 現在のタイムスタンプ。 キャッシュを使わないようにするためのちょっとしたハック。
  client client デフォルトのクライアント名(用語集を参照)
未読記事カウント(unread-count) (登録されているフィードやタグ/フォルダーの)未読記事がどこにあるか全ての情報を取得する
  all all ‘true’にすると登録フィード/タグの全てが対象となる(他の値については調査中)
  output output 返ってくるデータのフォーマットを指定。 ’json’や’xml’が使える
  ck timestamp 現在のタイムスタンプ。 キャッシュを使わないようにするためのちょっとしたハック。
  client client デフォルトのクライアント名(用語集を参照)

Viewer

この章はhttp://www.google.com/reader/view/で始まるURLについて解説する。

http://www.google.com/reader/view/で始まるURLは全て、http://www.google.com/reader/atom/にあるatomフィードを表示するためのAjaxコードを利用したHTMLページである。

基本URLにさまざまなセットの文字列を付加することで、記事のセットが取得できる。 しかしながら、URLにGETパラメーターを付加することはできない(実際、付加しても無視される)。

「重要」のラベリングをした全ての記事を直接見る場合は http://www.google.com/reader/view/user/-/label/important にアクセスする。

xkcdのメインフィードにある全ての記事を直接見る場合は http://www.google.com/reader/view/feed/http://xkcd.com/rss.xml にアクセスする。 この場合、フィードは登録されていなくても良い(このケースでは画面上部に「登録」ボタンが表示される)。 しかし、認証が済んでいない場合は新型(scroll)ではなく、旧型のインターフェース(lens)を使ってブラウジングすることになる。

その他

調査中のものについては、主に /share/ にある。

リファレンス

このページをシェアする

2 件のコメント

  • takke より:

    大変わかりやすい翻訳をありがとうございます。
    私のほうでもいくつかAPIを叩く例を書きました↓
    http://www.mz3.jp/wiki/index.php?GogleReaderAPI
    翻訳を見ていて気になったのですが、「リストAPI」については翻訳すると実際のAPIが分からなくなるようです。
    例えば「タグ/リスト」は「タグ/リスト(tag/list)」としたほうがよいかと思います。

  • 山下こうじ より:

    takkeさん、ご指摘ありがとうございます。
    修正致しました。

takke へ返信する コメントをキャンセル

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

2009-12-28