应用笔记本

让应用只访问用户指定的单个笔记本

印象笔记 API 的新特性！

想了解更多关于此印象笔记 API 的新特性，请阅读我们在开发者博客的博文：[博文]关于应用笔记本的反馈

概述

在过去，取得授权的印象笔记 API key 会有权访问授权用户的所有笔记和笔记本。而伴随印象笔记开放平台的发展，现在开发者在创建印象笔记 API 时，可以选择限制自己的应用只访问用户的某一特定笔记本。我们将此特性称为应用笔记本。它可以更大程度地保证用户数据安全，同时开发者们也可以方便地实现它。

本文档会描述开发者应如何实现此特性以及用户的授权过程。

实现过程

大体上来说，除了个别地方有变化之外，印象笔记 API 的认证过程仍然与旧 API key相同，

当配置了应用笔记本的 API Key 获取认证 token 后：

• 调用 NoteStore.listNotebooks 会返回一个集合，该集合只包含此 API Key 有权访问的那一个笔记本。
• 试图调用 NoteStore 的函数来访问、修改除了该应用笔记本以外的笔记本，会返回一个错误码为 PERMISSION_DENIED 的 EDAMUserException。

如果想让用户在选择目标笔记本时可以选择现有的共享笔记本或企业笔记本，那么在认证时需要在 OAuth URL 中包含 supportLinkedSandbox=true。

https://app.yinxiang.com/OAuth.action?oauth_token=[...]&preferRegistration=true&supportLinkedSandbox=true

当用户选择共享笔记本或企业笔记本作为应用笔记本时，OAuth 回调时会将 sandbox_lnb 参数设置为 true。否则 sandbox_lnb 默认是 false。

错误处理

用户有可能会删除你的应用程序有权访问的那个笔记本。这时候，NoteStore.listNotebooks 和 NoteStore.listLinkedNotebooks 会返回空集合并且 NoteStore.getNotebook 会抛出 EDAMNotFoundException 异常。

你的应用程序应当对这种情况加以处理。我们建议你提示用户所发生的情况并引导用户重新对应用授权，以便选择其他的笔记本。

try {
    NoteStore.getNotebook(notebookGuid);
} catch EDAMNotFoundException {
    // 回到授权过程，以便用户选择新的笔记本 
    // 再通过 listNotebooks 获取新笔记本的 GUID
    notebooks = NoteStore.listNotebooks()
    if notebooks isn’t empty:
        newGuid = notebooks[0].guid
        NoteStore.getNotebook(newGuid)
    // 其他操作...
}

与以前授权访问整个用户帐户时一样，第三方开发者还要在应用程序中处理认证 token 过期或被用户撤销授权的情况。要了解更多信息，可以查看认证文档的 “OAuth 简介”

用户流程

与 OAuth 流程类似，用户授权的流程也基本保持不变。以前，授权界面会告诉用户此应用将在一年内有权访问用户帐户以及此应用将拥有的具体权限（如创建笔记、更新笔记等）。现在主要的区别是：用户能够选择请求授权的应用可以访问哪一个笔记本。

默认情况下，用户帐户内会新建一个以【应用程序名称】命名的笔记本。

给用户建议一个笔记本名字

为了给用户建议一个笔记本名字，你要给OAuth 变量添加 supportLinkedSandbox 和 suggestedNotebookName两个字段。你需要把 supportLinkedSandbox 设置为 true 并把 suggestedNotebookName设置成你想推荐给用户的，经过URL编码的笔记本名字。例如:

https://www.evernote.com/OAuth.action?oauth_token=[...]&supportLinkedSandbox=true&suggestedNotebookName=Suggested%20Notebook%20Name

其中“Suggested Notebook Name”是你想建议给用户的，经过URL编码的笔记本名字。如果这个用户的账户中，已经有了你推荐的笔记本名字的那个笔记本，那么这个笔记本将会被选中。如果用户账户的笔记本的名字中，没有你通过OAuth的变量推荐的名字，那么你推荐的那个名字将会在用户的笔记本中被创建。你建议的笔记本名字必须遵循API参考文档中的所概述的标准Evernote笔记本名称的规则 这里

用户可以在认证过程中选择 更改笔记本 来选择现有的笔记本。

在认证过程中，用户将可以选择 更改 默认笔记本：

选中的笔记本可以是用户的私人笔记本、共享笔记本和企业笔记本。