EvernoteのAPIを使ったノート検索でfindNotesの代わりにfindNotesMetadataを使ってみた

前置き

以前、EvernoteAPIの話を書いていて、「検索のAPIは2つあるようなのですがそのうち調べます」とか言っていたものを書きました。EvernoteAPIのうち、ノートの検索に使うfindNotesとfindNotesMetadataの話です。ノートの検索に使うAPIであるfindNotesはdeperecatedとのことなので、推奨されているfindNotesMetadataを使ってみました。

概要

findNotesとfindNotesMetadataはどちらもノートのメタデータを返します。メタデータなので実際のノートの中身や、中身に埋め込まれた画像などのバイナリデータは含まれません。
findNotesMetadataで変わった点は、新しい引数を使ってこのメタデータに含めるデータを指定できるところです。findNotesで返されるメタデータに含まれるデータは固定なのですが、findNotesMetadataを使うことでより柔軟に結果を得られるようになったようです。（たぶん、速くなったりメモリを食わなくなったりしてるんだと思います。）また、容量の大きそうなノートの中身やバイナリデータのサイズなども取得できるので、その辺りを見つつうまいことやる、なんてこともできそうです。
この記事では、findNotesとfindNotesMetadataの使い方を示して、それぞれの違いについて説明します。

公式ドキュメント

説明します、といいつつ、この文章は解説というより、自分の使いみちにあった感じで書いたらこうなった、というところです。もっと色々調べたい方は公式のドキュメントをあたってください。というか、検索に限らず、API使って何かしたいと思ったら、まずドキュメントを片手に唸る感じです…。
この記事に関連するドキュメントはこちら。他は必要に応じてリンクを貼っています。またGUIDなど用語に関しては前に書いた記事や用語集 - Evernote Developersをご覧ください。

• ノートの検索 - Evernote Developers
• findNotesのドキュメント
• findNotesMetadataのドキュメント

findNotesのコード例

さて、まずは今までの、findNotesを使ったコード例を乗せます。このfind_notesメソッドは、Evernoteのノートの属性のうちいくつかをまとめたNoteオブジェクトの配列を返します。

def find_notes(options={})
  guid  = options[:guid]            # 検索するノートブックのGUID
  words = options[:words]           # 検索語句
  count = options[:count] || 1      # 検索するノートの数

  # 検索フィルタの作成
  filter = Evernote::EDAM::NoteStore::NoteFilter.new
  filter.notebookGuid ||= guid
  filter.words ||= words

  noteslist = @note_store.findNotes(@token, filter, 0, count)
  noteslist.notes
end

findNotesMetadataのコード例

これをfindNotesMetadataを使って、同じように動作させようと修正をしたらこうなりました。（動作は同じですが、実は返り値が変わっています。これについては後述します。）

def find_notes(options={})
  guid  = options[:guid]            # 検索するノートブックのGUID
  words = options[:words]           # 検索語句
  count = options[:count] || 1      # 検索するノートの数

  # 検索フィルタの作成
  filter = Evernote::EDAM::NoteStore::NoteFilter.new
  filter.notebookGuid ||= guid
  filter.words ||= words

  # ここから変更点
  spec = Evernote::EDAM::NoteStore::NotesMetadataResultSpec.new
  metadatas = @note_store.findNotesMetadata(@token, filter, 0, count, spec)
  metadatas.notes
end

次にこの2つの違いについて説明します。

違いその1：spec

まず両者で変わったところ（返り値は後述します）というと、メソッドに渡す引数にspecが追加されました。
specにはEvernote::EDAM::NoteStore::NotesMetadataResultSpecというクラスのオブジェクトを渡します。このオブジェクトには、返り値のメタデータに何を含めるかを指定します。ただnewしただけのspecを使うと、GUIDしか含まれないメタデータを返してきます。そこで、タイトルも返して！　というときには、つぎのように指定したspecをfindNotesMetadataメソッドに渡してやるといいようです。

  spec.includeTitle = true

タイトルの他に、作成・更新・削除日時、ノートの中身のサイズなども検索結果のメタデータに含められるようです。（実際に何が含められるかは上記のspecのドキュメントをご覧ください。）

違いその2：返り値

次に違う点は返り値です。それぞれ次のようなオブジェクトを返します。

• findNotes
  • Evernote::EDAM::NoteStore::NoteListオブジェクト
• findNotesMetadata
  • Evernote::EDAM::NoteStore::NotesMetadataListオブジェクト

また上記のコード例では、どちらでもそれぞれのAPIの返り値に対して#notesメソッドを叩いています。この#notesメソッドの返り値が、検索に引っかかったノートのデータです。これの返り値も、findNotesとfindNotesMetadataで違います。

• findNotes#notes
  • Evernote::EDAM::NoteStore::Noteの配列（ただしノートの中身と画像などのバイナリデータを省いたもの）
• findNotesMetadata#notes
  • Evernote::EDAM::NoteStore::NoteMetadataオブジェクトの配列

このNoteMetadataに、specで指定したデータが入っています。
なお、空のspecを指定しても、ノートのGUIDは必ず含まれます。（というより、それがないとノートを指定できない）findNotes側で出てくるNoteオブジェクトもノートのGUIDを持っています。

まとめると次のようになります。

API	返り値のクラス	#notesの返り値	#notes で取得できるもの
findNotes	ÏNoteList	Noteの配列	GUIDやタイトルなど（ノートのデータのうち、中身やバイナリデータを除いたもの
findNotesMetadata	NotesMetadataList	NoteMetadataの配列	GUIDとspecで指定したデータ

じゃあ実際のノートの中身はどうすんだ、という話になりますが、そのときはGUIDを使ってノートの実体なり中身なりを取得します。この話はまた別に書きたいなあと思ってます。

まとめ

ノートを検索するときにはfindNotesMetadataの方が欲しいデータだけ拾ってこれるので便利そうです。findNotesではタイトルなど返り値に含まれるデータは固定ですが、findNotesMetadataでGUIDしかいらない、というときにも対応できます。私が作っているものについては、GUIDだけ必要なのでまさにこのパターンでした。
findNotesMetadataの方が、（場合によりますが）余計なデータを取ってこないのでその分早かったりメモリを食わなかったりしそうです。多分。おそらく検索結果が膨大になる場合には結構影響が出そうだなあと思っています。