认证

用OAuth对印象笔记云 API进行认证


简介

基于OAuth的认证流程就是,用户在自己的设备上通过印象笔记账户认证你的应用程序的过程。用户必须通过印象笔记域名下的网站认证你的应用的访问权限(app.yinxiang.com 或者 sandbox.yinxiang.com)。在认证被授权(或是被拒绝)之后,印象笔记将会把用户重定向回你的应用程序,同时你会收到一些必要的信息,来取回一个access token。这个access token使你可以在用户的设备上使用这个用户的印象笔记的数据

开发者 token

用你自己的账户快速测试一下印象笔记API, 获取一个开发者Token »

基于OAuth的认证流程由四部分组成:

  1. 生成一个临时的Token
  2. 请求用户认证
  3. 取回 Access Token
  4. 接下来的步骤,访问API


1. 生成一个临时Token

首先,你的应用程序必须向印象笔记发送请求,生成一个临时的token。下面是一个请求的例子:

注意:作为产品环境访问时,要将sandbox.yinxiang.com替换为app.yinxiang.com.

这个请求必须是GET方法,请求到以下地址:

Method Endpoint URL
GET https://sandbox.yinxiang.com/oauth

作为这个请求的一部分,你必须提供一个回调地址(你开发的时候可以在本地用"localhost"),这个回调地址的所有变量都应该进行URL编码(URL-encoded),在用户选择认证或者拒绝你的应用程序的访问以后,用户将会被指向你的这个回调地址。

临时Token请求参数

在下面的表格中,你可以看到所有需要的参数。如果你还没有API key(oauth_consumer_key) 你可以从这获取一个: 获取API Key

名称
描述
实例
oauth_callback
在用户对你的应用程序授权访问以后,被重定向到的 URL
http://www.foo.com
oauth_consumer_key
用来标识你的应用的API key
sampleKey
oauth_nonce
*
3166905818410889691
oauth_signature
*
xCYjTiyz7GZiElg1uQaHGQ6I
oauth_signature_method
*
HMAC-SHA1
oauth_timestamp
*
1429565574
oauth_version
*
1.0

注意: * oauth_nonce, oauth_signature, oauth_signature_method, oauth_timestamp, 和 oauth_version 是由大多数Evernote SDKs和OAuth 库提供的变量,如果你对给你的平台开发OAuth1的库感兴趣的话,请访问这里the OAuth1 3LO specification.

临时Token请求的响应

在发送了一个合法的请求后,你会收到以下返回值:

这个返回值包括了以下变量

名称
描述
实例
oauth_token
临时OAuth token
sampleKey-121.14C...
oauth_callback_confirmed
一个布尔值,用来确认回调地址是否已经设置
true


2.请求用户授权

在你取回临时Token以后,你需要将用户重定向到印象笔记,让用户在他们的印象笔记账户中对你的应用程序进行授权。

重定向地址(URL)

你的应用程序会用到上一步你取回的oauth_token这个变量,将用户重定向到https://sandbox.yinxiang.com/OAuth.action,这样就可以开始用户验证授权的步骤了,下面是一个重定向地址的例子:

在用户授权或者拒绝他们的印象笔记账户访问你的应用程序后,用户会被重定向到,你在临时token请求时特别说明的那个oauth_callback变量里面的地址。下面的重定向地址就是,用户允许你的应用访问他们的印象笔记账户之后,成功返回的例子:

回调地址的变量说明
名称
描述
实例
oauth_token
临时的Token
sampleKey-121.14C...
oauth_verifier
(可选项)只有在用户成功授权了你的应用程序访问他们的印象笔记账户,才会有这个值
40793F8BAE15D4E3B6DD5CA8AB4BF62F
sandbox_lnb
布尔值,与API Key权限有关 (更多信息,请看“权限”一文)
false

请注意,被授权或者被拒绝的app收到的回调地址的参数应该是一样的,只是,被拒绝的时候,回调地址的参数中没有oauth_verifier这一变量, 就像下面例子中这样:



3.获取Accesss Token

下面是获取Access Token的例子:

这个请求必须是GET方法,请求以下地址(URL):

Method
Endpoint URL
GET
https://sandbox.yinxiang.com/oauth

这个请求必须包含URL编码的OAuth需要的参数,下面的表格中列出了这些参数。请注意,如果你在回调中没有收到oauth_verifier变量,这意味着用户拒绝了你的应用程序访问他的印象笔记账户,那么你就没办法发出一个合法的Access Token的请求

Access Token请求参数
名称
描述
实例
oauth_consumer_key
用来识别认证你的应用程序的API key
sample-api-key-4121
oauth_token
临时的OAuth Token
sampleKey-121.14C...
oauth_verifier
如果用户成功授权了你的应用程序访问他们的印象笔记账户,OAuth verify就会在回调中出现
40793F8BAE15D4E3B6DD5CA8AB4BF62F
oauth_nonce
*
3166905818410889691
oauth_signature
*
xCYjTiyz7GZiElg1uQaHGQ6I
oauth_signature_method
*
HMAC-SHA1
oauth_timestamp
*
1429565574
oauth_version
*
1.0

注意: * oauth_nonce, oauth_signature, oauth_signature_method, oauth_timestampoauth_version 是由大多数Evernote SDKs和OAuth 库提供的参数,如果你对给你的平台开发OAuth1的库感兴趣的话,请访问这里the OAuth1 3LO specification.

Access Token返回值

如果成功了,你会收到一个类似下面例子的回应:

回应将会包括以下变量:

名称
描述
实例
oauth_token
Access Token,可以用来在用户设备上访问(印象笔记)API
S=s432:U=4a535ee:E=15430d...
oauth_token_secret
总是为空
edam_shard
用户个人笔记的分片
s432
edam_userId
这个用户的用户ID(useful for webhook notifications)
77936110
edam_expires
Token到期的日期(UNIX时间戳(毫秒))
1461107889411
edam_noteStoreUrl
用户个人笔记的note store的地址(URL)
https://sandbox.yinxiang.com/shard/s432/notestore
edam_webApiUrlPrefix
仅供内部使用
https://sandbox.yinxiang.com/shard/s432/
授权访问的Token期限


每一个授权访问的Token都有一个到期的日期。授权访问的Token默认有效期是一年。用户可以把这个时间段调整为一天,一周或是一个月。在所有这些情况中,到期日期都会包含在变量edam_expires中。这个变量的值是一个以毫秒为单位的标准UNIX时间戳,表示到期的日期和时间。



4. 接下来的步骤,访问API

用上面的oauth_token这个值(它是以这种形式的开头S=s432:U=4a535ee:E=154d..)你现在就可以在用户的设备上发送API请求来支持你的应用程序! 你可以用这个Token来对用户的印象笔记进行一些操作,比如保存内容和数据到笔记和笔记本并且(如果你的API key有权限去这样做)读取笔记,笔记本,标签,在你的应用里为用户进行搜索并取回企业数据。

既然现在你已经有了认证的Token,我们建议你做一下几步,深入探索API:

激活API key

请注意,在这个网页上我们的示例URL都是以https://sandbox.yinxiang.com开头,其实当你在产品环境时,将URL替换为https://app.yinxiang.com开头,所有示例代码都依然可以正常工作。但是我们建议你先在沙盒中开发你的应用程序。

要把你的Key转移到产品环境请申请在产品环境激活你的API key