如何通过 Evernote API 进行多媒体笔记的创建

一、引言：为什么要用 Evernote API 创建多媒体笔记？

在信息管理日益复杂的今天，传统的纯文本笔记工具已难以满足用户对富媒体内容的记录需求。Evernote 作为一款老牌的笔记管理平台，其 API 提供了强大的开发接口，支持文本、图片、音频、PDF 等各种内容类型的笔记操作。

使用 Evernote API，开发者可以：

自动创建图文并茂的日记、笔记或知识文档；
将多媒体素材（如照片、语音）直接嵌入笔记；
实现 IoT 设备日志采集、语音转文字、文档 OCR 存储等自动化应用；
构建 AI 智能笔记系统。

二、API 准备工作

2.1 注册并获取开发者 Token

在 “My Account” 中创建开发者密钥；
或使用 Evernote Sandbox 环境测试；
生成 Developer Token，用于 API 鉴权；
注意生产环境推荐使用 OAuth 认证机制。

2.2 安装 Python SDK

Evernote 官方提供了 Python SDK：

pip install evernote

安装成功后，可以通过如下代码快速连接 NoteStore：

from evernote.api.client import EvernoteClient

client = EvernoteClient(token="your_token", sandbox=False)
note_store = client.get_note_store()

三、ENML：Evernote 的笔记结构语言

Evernote 使用 ENML（Evernote Markup Language）描述笔记内容，其语法类似 HTML：

< ?xml version="1.0" encoding="UTF-8"? >
< !DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd" >
< en-note >
    Hello, this is a simple text note.
< /en-note >

ENML 支持的标签：

< en-note > ：必须的根标签；
< en-media > ：嵌入多媒体资源（图片、音频、PDF）；
< en-todo > ：添加待办复选框；
< br/ > , < div > , < span > , < a > 等常见 HTML 标签也支持。

四、创建基本文本笔记

from evernote.edam.type import ttypes as Types

note = Types.Note()
note.title = "Hello Evernote"
note.content = """ < ?xml version="1.0" encoding="UTF-8"? >
< !DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd" >
< en-note > This is a text note. < /en-note > """

created_note = note_store.createNote(note)
print("Note GUID:", created_note.guid)

五、添加多媒体内容：图片、音频、PDF

5.1 创建资源（Resource）

每个图片、音频或 PDF 文件都作为 Resource 上传，并通过 < en-media > 标签嵌入 ENML 中。

import hashlib, binascii
from evernote.edam.type import ttypes as Types

def create_resource(file_path, mime_type):
    with open(file_path, "rb") as f:
        data_bytes = f.read()
    md5 = hashlib.md5(data_bytes).digest()
    data = Types.Data(bodyHash=md5, size=len(data_bytes), body=data_bytes)
    resource = Types.Resource(mime=mime_type, data=data)
    return resource, binascii.hexlify(md5).decode()

5.2 插入图片示例

img_res, img_hash = create_resource("image.jpg", "image/jpeg")

note = Types.Note()
note.title = "包含图片的笔记"
note.resources = [img_res]
note.content = f""" < ?xml version="1.0" encoding="UTF-8"? >
< !DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd" >
< en-note >
    这是插入的图片：< br/ >
    < en-media type="image/jpeg" hash="{img_hash}"/  >
< /en-note  > """

note_store.createNote(note)

5.3 插入 PDF 示例

pdf_res, pdf_hash = create_resource("doc.pdf", "application/pdf")

note = Types.Note()
note.title = "PDF 示例笔记"
note.resources = [pdf_res]
note.content = f""" < ?xml version="1.0" encoding="UTF-8"?  >
< !DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd"  >
< en-note  >
    请查收 PDF 文档：< br/  >
    < en-media type="application/pdf" hash="{pdf_hash}"/  >
< /en-note  > """

note_store.createNote(note)

六、音频笔记的实现

将语音文件（如 MP3）嵌入笔记，非常适合制作语音日志或听课记录。

audio_res, audio_hash = create_resource("voice.mp3", "audio/mpeg")

note = Types.Note()
note.title = "语音笔记"
note.resources = [audio_res]
note.content = f""" < ?xml version="1.0" encoding="UTF-8"?  >
< !DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd"  >
< en-note  >
    听课录音如下：< br/  >
    < en-media type="audio/mpeg" hash="{audio_hash}"/  >
< /en-note  > """

note_store.createNote(note)

七、笔记标签与笔记本管理

为笔记指定标签与笔记本：

note.tagNames = ["多媒体", "项目资料"]
note.notebookGuid = "your_notebook_guid"

创建新的笔记本：

notebook = Types.Notebook()
notebook.name = "语音与图像笔记"
created_nb = note_store.createNotebook(notebook)
print("Notebook GUID:", created_nb.guid)

八、读取笔记中的多媒体资源

要下载笔记中的附件，可按如下方式获取：

note = note_store.getNote(guid, True, False, False, False)
for res in note.resources:
    resource_data = note_store.getResource(res.guid, True, False, False, False)
    with open(res.guid + ".bin", "wb") as f:
        f.write(resource_data.data.body)

九、常见错误与排查

问题类型	错误信息	解决方案
ENML 错误	"ENML Validation Error"	检查 XML 结构、标签闭合、必须使用 `en-note` 根标签
资源上传失败	"hash mismatch"	保证 `< en-media >` 中 hash 与 Resource 中一致
Token 认证失败	"EDAMUserException: authenticationFailed"	检查 token 是否有效，或切换 OAuth 授权
频繁访问被限流	"EDAMSystemException: rateLimit"	避免重复创建，添加重试逻辑与限速