4006 988 223

开放平台

当前位置：首页> 出口易API手册> 了解OAuth2.0

使用 OAuth 2.0 访问出口易 API

出口易支持 OAuth 2.0 协议的授权访问。关于 OAuth 2.0 协议规范，请参考这里。

使用 OAuth 2.0 的流程可以简单概括为：

  1. 应用向出口易请求授权
  2. 出口易为用户显示一个授权页面，用户在此页面确认是否同意应用的请求
  3. 如果用户同意授权，应用会获取到一个访问令牌(access_token)，通过此令牌，应用可以访问授权用户的数据。
  4. 如果访问需要授权的 API，请使用 HTTPS 协议，加上 access_token 的 Header，具体见获取 access_token

出口易支持三种 OAuth 2.0 的授权流程：

server-side flow 与 native-application flow

这两种授权流程基本相同，需要通过两步来获取 access_token。

获取 authorization_code

通过在浏览器中访问下面的地址，来引导用户授权，并获得 authorization_code

http://openapi.test-ck1.cn/oauth2/authorization

参数：

参数名称参数说明
client_id必选参数，应用的唯一标识，对应于ClientId
redirect_uri必选参数，用户授权完成后的回调地址，应用需要通过此回调地址获得用户的授权结果。此地址必须与在应用注册时填写的回调地址一致。
response_type必选参数，此值可以为 code 或者 token 。在本流程中，此值为 code
scope必选参数，申请权限的范围。如果申请多个 scope，使用逗号分隔。

注意：此请求必须是 HTTP GET 方式

例如：

http://openapi.test-ck1.cn/oauth2/authorization?
client_id=YzgyNWQxMGMtN2E3MC00ZTBlLTg5NDgtNTEwZmQ5OGVkYjFk&
redirect_uri=http://appdemo.test-ck1.cn/back&
response_type=code&
scope=3333

返回结果：

  • 当用户拒绝授权时，浏览器会重定向到 redirect_uri，并附加错误信息

    http://appdemo.test-ck1.cn/back?error=access_denied

  • 当用户同意授权时，浏览器会重定向到 redirect_uri，并附加 autorization_code

    http://appdemo.test-ck1.cn/back?code=NGVhZTE4Y2UtNjBiNi00NjFjLThlNmUtMmRhYjJhNDA3OTRi

获取 access_token

http://openapi.test-ck1.cn/oauth2/authorization
参数名称参数说明
client_id必选参数，应用的唯一标识，对应于ClientId
redirect_uri必选参数，用户授权完成后的回调地址，应用需要通过此回调地址获得用户的授权结果。此地址必须与在应用注册时填写的回调地址一致。
response_type必选参数，此值可以为 code 或者 token 。在本流程中，此值为 token
scope必选参数，申请权限的范围。如果申请多个 scope，使用逗号分隔。

注意：此请求必须是 HTTP POST 方式

例如：

http://openapi.test-ck1.cn/oauth2/authorization?
client_id=YzgyNWQxMGMtN2E3MC00ZTBlLTg5NDgtNTEwZmQ5OGVkYjFk&
redirect_uri=http://appdemo.test-ck1.cn/back&
response_type=token&
scope=3333

返回结果：

  • 当用户拒绝授权时，浏览器会重定向到 redirect_uri，并附加错误信息

    http://appdemo.test-ck1.cn/back?error=access_denied

  • 当用户同意授权时，浏览器会重定向到 redirect_uri，并附加 autorization_code

    http://appdemo.test-ck1.cn/back?code=NGVhZTE4Y2UtNjBiNi00NjFjLThlNmUtMmRhYjJhNDA3OTRi

使用 access_token

curl "https://api.douban.com/v2/user/~me"
     -H "Authorization: Bearer a14afef0f66fcffce3e0fcd2e34f6ff4"

access_token 有效期 与 refresh_token

在 OAuth 2.0 中，access_token 不再长期有效。在授权获取 access_token 时会一并返回其有效期，也就是返回值中的 expires_in 参数。

在 access_token 使用过程中，如果服务器返回106错误：“access_token_has_expired ”，此时，说明 access_token 已经过期，除了通过再次引导用户进行授权来获取 access_token 外，还可以通过 refresh_token 的方式来换取新的 access_token 和 refresh_token。

通过 refresh_token 换取 access_token 的处理过程如下：

https://www.douban.com/service/auth2/token
参数名称参数说明
client_id必选参数，应用的唯一标识，对应于 APIKey
client_secret必选参数，应用的唯一标识，对应于出口易 secret
redirect_uri必选参数，用户授权完成后的回调地址，应用需要通过此回调地址获得用户的授权结果。此地址必须与在应用注册时填写的回调地址一致
grant_type必选参数，此值可以为 authorization_code 或者 refresh_token。在本流程中，此值为 refresh_token
refresh_token必选参数，刷新令牌

注意：此请求必须是 HTTP POST 方式，refresh_token 只有在 access_token 过期时才能使用，并且只能使用一次。当换取到的 access_token 再次过期时，使用新的 refresh_token 来换取 access_token

例如：

https://www.douban.com/service/auth2/token?
  client_id=0b5405e19c58e4cc21fc11a4d50aae64&
  client_secret=edfc4e395ef93375&
  redirect_uri=http://appdemo.test-ck1.cn/back&
  grant_type=refresh_token&
  refresh_token=5d633d136b6d56a41829b73a424803ec

返回结果：

{
  "access_token":"0e63c03dfb66c4172b2b40b9f2344c45",
  "expires_in":3920,
  "refresh_token":"84406d40cc58e0ae8cc147c2650aa20a",
  "douban_user_id":"1000"
}

错误代码

如果在 API 使用过程中，有错误，则返回结果为：

{
  "code":113,
  "msg":"required_parameter_is_missing: client_id",
  "request":"GET /shuo/statuses/232323"
}
错误代码错误说明
800F0608不支持的请求授权类型
800F0609请求授权的应用不存在
800F0610请求授权应用的重定向地址与应用注册时回调地址非同源
800F0611未指定授权范围参数
800F0612请求的授权部分不存在，请重新确认授权范围
800F0613未指定请求授权响应类型(responseType)
800F0614未指定重定向参数(redirect_uri)
800F0615未指定应用Clientid参数
800F0616未指定应用授权范围参数(scope)
800F0617授权范围与应用授权不匹配，请重新确认授权范围(scope)
800F0618请求访问Token应用密钥参数未指定.(Client_secret)
800F0619请求访问Token应用密钥不匹配.(Client_secret)
800F0620请求访问Token授权类型未指定.(Grant_type)
800F0621请求访问Token授权类型指定错误，目前支持authorization_code和refresh_token两种方式
800F0622请求访问Token授权未指定授权码.
800F0623请求访问的授权码不存在.
800F0622请求访问的授权码无效.
800F0623请求访问的授权码不属于当前应用
800F0624请求访问Token授权未指定刷新Token
800F0625请求访问Token授权刷新Token不存在
800F0626请求访问Token授权刷新Token不属于当前应用
800F0627请求访问Token授权刷新Token无效
800F0639请求的重定向地址格式不正确
HTTP状态码说明
200表明 API 的请求正常
400表明 API 的请求出错，具体原因参考上面列出的错误码