第3回　Evernote APIの基礎：データモデルとデータアクセス

Evernoteと連携するには

前回、Evernoteと連携をするアプリケーションのアイデアについて話しましたが、Evernoteと連携するための方法は大きく分けて2つあります。1つは各プラットフォーム上のEvernoteクライアントが提供する仕組みを使う方法、もう1つはEvernote APIを使う方法です。どちらを使うかは開発者の自由です。

各プラットフォーム上のEvernoteクライアントには、Evernoteと連携するための仕組みが備わっています。WindowsではEvernote.exeやENScript.exeにコマンドを指定することで、ノートを作成するなどの簡単な操作を行えるようになっています。Mac OS XではAppleScript、AndroidではIntentで同様のことが可能です。単純な連携であれば、これらの仕組みを使うのが簡単です。たとえば、pomeraで作成したテキストをEvernoteにアップロードするpomera2evernoteは、ENScriptを使用しているようです。

（参考）Evernote API Overview br> http://www.evernote.com/about/developer/api/

Evernote APIを使う理由

しかし、より複雑な手続きをしたいとか、WebサービスにEvernoteとの連携を組み込みたいといった場合など、Evernoteクライアントが提供しているものではできないこともたくさんあります。その場合にはEvernote APIを通して、直接EvernoteWebサービスとやり取りすることができます。Evernoteの公式クライアントも公開されたEvernote APIを使って開発されていますので、公式クライアントができることはすべてこのAPIを使って実現できるはずです。Evernote APIは、EDAM (Evernote Data Access and Management) APIとも呼ばれています。今後APIの中身を見ていくとさまざまなところでEDAMという文字列を見ることになりますが、Evernote APIのことだと思って問題ありません。

Thriftとは？

Evernote APIは、Evernote内の情報を表すデータモデルと、データにアクセスするためのプロトコルが、Thriftで記述されています。ThriftはHTTPを用いた軽量なRPCフレームワークです。元々Facebookが開発していたものでしたが、今はApache Incubatorの一プロジェクトとして、オープンソースで開発されています。Thrift IDLでデータ構造やAPIを記述すると、Java、C++、Python、PHP、Rubyといったさまざまな言語用のAPIインターフェースを生成できます。そのインターフェースを使って、開発者は好みの言語環境からEvernote APIを利用することができます。また、WindowsやAndroidを含む、さまざまなプラットフォームに対応することが可能です。

Evernote APIの基本的な使い方

Evernote APIの基本的な使い方ですが、まずユーザ認証によってAuthentication Tokenを取得します。そして、取得したTokenを利用してユーザのデータにアクセスするという流れになります。

ユーザの認証方法には、UserStoreサービスとOAuthサービスの2種類が提供されています。UserStoreサービスは、Evernoteのユーザ名とパスワードで認証します。デスクトップやモバイルアプリケーションなどでは、UserStoreサービスを使うのが手軽でしょう。しかし、Webサービス側でEvernoteと連携する時のように、ユーザのパスワードを直接取扱いたくない場合もあります。その場合にはOAuthを使った実装をお勧めします。UserStoreとOAuthどちらで認証したとしても、Authentication Tokenを取得することになります。そのTokenを利用することで、認証されたユーザのデータにアクセスできるようになります。

NoteStoreについて

ユーザのデータへのアクセスはNoteStoreサービスを使います。データモデルの概要は図の通りです。

まず、1つのNotebookが複数のNoteを持つというのが基本構造になります。Noteの内容はENML（Evernote Markup Language）を使って表現されており、その内容はcontentsから参照することができます。ENMLはXHTMLのサブセットをベースに、Evernote社が独自に作成した言語です。

Resourceとは、Noteに添付された画像やPDFなどのファイルのことです．ENML内では<en-media>という要素で参照されています。一部のResourceは、画像認識などで抽出した文字列のインデックスをXMLとして持っており、検索などに利用可能です．また、NoteやResourceに関するデータ（クリップ元のURLや位置情報など）はNoteAttirubtesやResourceAttributesから取得できます。

TagとNoteは多対多の関係で、あるTagは複数のNoteに付けられますし、1つのNoteに複数のTagを付けることも可能です。また、直接他のデータとの関係はありませんが、SavedSearchによって、ユーザが保存した検索文字列も利用することができます。

APIからデータを直接参照するために、各データにはguid (globally unique identifier) が割り当てられています。また、データが変更されたときには必ずUSN (updateSequenceNumber) が変更されるため、USNを比較することで、データーの同期を実装することができます。

次回は

今回はEvernote APIの概要として、その基盤となっているThriftと、提供されているサービスやデータモデルの解説をしました。次回はAPIの具体的な使い方を理解してもらうために、JavaとRubyによるサンプルコードを見ていきます。