创建笔记

在本指南中，我们会讨论如何使用印象笔记云 API 创建简单的文本笔记和包含附件的笔记

• 通过 HTTP 请求创建文本笔记（适用于第三方应用快速接入）

  本方法可通过 HTTP POST 请求快速创建笔记。

  目前仅支持在默认笔记本或用户授权时指定的笔记本中创建笔记。

  可指定笔记的标题和内容，笔记内容部分支持Markdown格式。

  目前不支持创建带附件的笔记。

  通过此方式创建笔记前，需要先获取用户授权。

  接口描述文件 (OpenAPI 格式)

  使用 curl 命令调用接口

  以下是使用 curl 命令调用创建笔记接口的示例：

  curl -X POST "https://app.yinxiang.com/third/third-party-note-service/restful/v1/createNoteFromMCP" \
    -H "Content-Type: application/json" \
    -H "auth: S=xxx:U=xxx:E=xxx:C=xxx:P=xxx:A=xxx:V=xxx:B=xxx" \
    -d '{
      "title": "我的笔记标题",
      "content": "### 标题1\n\n这是笔记内容的第一部分。\n\n### 标题2\n\n这是笔记内容的第二部分，支持 **粗体** 和 *斜体* 格式。"
    }'

  参数说明：

  • auth - 认证令牌，格式为 S=xxx:U=xxx:E=xxx:C=xxx:P=xxx:A=xxx:V=xxx:B=xxx
  • title - 笔记标题
  • content - 笔记内容，支持 Markdown 格式

  响应示例：

  {
    "code": 0,
    "message": "成功",
    "noteGuid": "d1b2c3a4-e5f6-7890-1234-567890abcdef"
  }

• 创建一个简单的文本笔记

  最基本的一条笔记只包含有文本。当然我们也可以创建更复杂的笔记，但我们还是一步一步从最基本的开始。

  准备工作

  要开始下面这个例子，我们假定你已经满足了如下条件：

  • 你有一个开发者 token （或者实现了 OAuth 授权过程，让你可以获取一个有效的认证 token）
  • 你可以获取 UserStore 跟 NoteStore 的实例

  在印象笔记中创建笔记是通过NoteStore.createNote API 函数完成的。这个函数接受两个参数：一个有效的认证 token （字符串形式）和一个Types.Note的实例。之后Note实例在被发送给 API 之前必须至少明确以下属性：

  • Note.title — 笔记的标题
  • Note.content — 笔记的主体，格式为ENML (Evernote Markup Language)

  另外，我们也可以为这条笔记设置其从属于的笔记本的 GUID （作为Note.notebookGuid）。如果我们不提供这个值，那么笔记就会被创建在帐户的默认笔记本中。

  每一条笔记的主体都必须以这两样东西开头：标准的XML版本声明和指向印象笔记的ENML DOCTYPE定义的链接。

  XML版本声明如下：

  <?xml version="1.0" encoding="UTF-8"?>

  
  

  笔记的 ENML DOCTYPE definition (DTD) 如下：

  <!DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd">

  
  

  如果少了这两个中的任意一个，印象笔记 API 都会将此笔记视为有问题的、无效的。

  假设这两个都已填入，那我们只要添加笔记的主体就可以了。笔记主体必须被放在<en-note>中。下面是一条简单（但完整）的印象笔记的笔记示例：

  <?xml version="1.0" encoding="UTF-8"?>

  <!DOCTYPE en-note SYSTEM "http://xml.evernote.com/pub/enml2.dtd">

  <en-note>Hello, world!</en-note>

  
  

  如果我们把上面的XML加上标题，我们就可以创建一条非常简单的文本笔记了。

  在下面你会找到用于完成整个笔记创建过程的示例代码。

  • Python
  • Objective-C
  • Ruby
  • PHP
  • Java
  • Node.js

• 创建带附件的笔记

  除了文本，笔记还可以包含附件（印象笔记 API 中叫作“Resource“）。附件可以是任意文件格式，但某些文件会用不同的方式显示。

  这部分描述了如何在笔记创建时向其中添加各种各样的附件如音频，图片还有其他文件。首先，我们先来了解下Resource数据类型（详细定义）。

  Types.Resource

  当我们想笔记中添加一个新的Resource的时候，这个对象的许多成员会在资源创建时被印象笔记云 API 设置好：Resource 的 GUID，包含这个资源的笔记的 GUID，所有的识别数据还有资源的 Update Sequence Number (USN).

  要讲一个普通的文件转化成Resource对象，我们需要完成以下步骤：

  1. 确定附件的 MIME 类型
  2. 读入文件内容并用其创建一个 Types.Data 的实例(此实例会被赋给 Resource 对象的 data 成员变量)。
  3. 生成此文件内容的 MD5 校验码

  以上是要为笔记附加一个文件所必要的最少信息，但为了完整，我们还应当添加最后一样东西：ResourceAttributes成员（详细定义）。ResourceAttributes让我们可以定义文件名，源URL地址还有其它关于此资源的数据。

  下面是一个简单的函数，它将一个文件集合转化为可以被添加到一条笔记中的Resource实例。

  • Python
  • Objective-C

  单纯创建一个Resource对我们没有任何意义，我们要把它添加到笔记中，对吧？把一个自由嵌入一条笔记中需要使用<en-media>元素，它是 ENML 的一部分。一个被嵌入到 ENML 文档中的Resource会看起来像这样：

  <en-media type="image/jpg" hash="md5-of-file" />

  图片和 PDF 资源

  以下 MIME 类型的资源会以笔记内视图的形式直接显示在笔记的主体中：

  • image/gif
  • image/jpeg
  • image/png
  • application/pdf

  当我们要把以上 MIME 类型的文件作为一个Resource添加到我们的笔记中时，我们可以（并非必须）在<en-media>元素中写上宽度和高度属性。

  <en-media type="image/jpg" hash="md5-of-file" width="250" height="200" />

  其余类型的写法跟上面的一致。

  音频资源

  支持音频资源的 MIME 类型有：

  • audio/wav
  • audio/mpeg
  • audio/amr

  当<en-media>元素的type属性是以上几种类型之一的时候，一些印象笔记的客户端会显示一个嵌入的音频播放器，无需离开应用便可播放此文件。音频资源的 ENML 语法跟所有其他类型的资源是一样的；不需要特殊的属性或标签。

  所有其他类型的资源

  对于那些 MIME 类型未出现在前两部分中的Resource，它们会通过“附件视图”（与“笔记内视图”对应）显示。这意味着，附件会以一个小的文件图标的形式显示在笔记的主体内。当用户点击/触摸这个文件图标的时候，文件会被操作系统认为正确的应用程序去打开。换句话说，印象笔记本身不会试着打开该文件。

• 示例代码

  下面是我们之前定义过的 makeNote 函数，现在我们对它进行扩展，让它能够添加资源附件。

  • Python
  • Objective-C
  • Ruby
  • PHP
  • Java
  • Node.js