home

=使用OAuth2.0访问豆瓣API=

豆瓣支持OAuth2.0协议的授权访问. 关于OAuth2.0协议规范，请参考[|这里].

使用OAuth2.0的流程可以简单概括为：

1. 应用向豆瓣请求授权 1. 豆瓣为用户显示一个授权页面，用户在此页面确认是否同意应用的请求 1. 如果用户同意授权，应用会获取到一个访问令牌(access_token)，通过此令牌，应用可以访问授权用户的数据.

豆瓣支持三种OAuth2.0的授权流程：


 * 直接在浏览器中运行的Javascript应用的授权流程（user-agent flow）
 * 有服务器的WEB应用的授权流程（server-side flow）
 * 桌面客户端应用、移动客户端应用的授权流程（native-application flow）

=授权流程=

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

{ –

– } 参数：
 * 参数名称 || 参数说明 ||
 * client_id || 必选参数，应用的唯一标识，对应于APIKey ||
 * redirect_uri || 必选参数，用户授权完成后的回调地址，应用需要通过此回调地址获得用户的授权结果. 此地址必须与在应用注册时填写的回调地址一致. ||
 * response_type || 必选参数，此值可以为 code 或者 token . 在本流程中，此值为 token ||
 * scope || 可选参数，申请权限的范围，如果不填，则使用缺省的scope. 如果申请多个scope，使用逗号分隔. ||
 * state || 可选参数，用来维护请求和回调状态的附加字符串，在授权完成回调时会附加此参数，应用可以根据此字符串来判断上下文关系. ||

注意：此请求必须是HTTP GET方式，此流程不会生成refresh_token

例如：

{ –

– } 返回结果：


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

{ –

– }
 * 当用户同意授权时，浏览器会重定向到redirect_uri，并附加access_token

{ –

– }

使用access_token
{ –

– }

server-side flow 与 native-application flow
这两种授权流程基本相同，需要通过两步来获取access_token.

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

{ –

– } 参数：
 * 参数名称 || 参数说明 ||
 * client_id || 必选参数，应用的唯一标识，对应于APIKey ||
 * redirect_uri || 必选参数，用户授权完成后的回调地址，应用需要通过此回调地址获得用户的授权结果. 此地址必须与在应用注册时填写的回调地址一致. ||
 * response_type || 必选参数，此值可以为 code 或者 token . 在本流程中，此值为 code ||
 * scope || 可选参数，申请权限的范围，如果不填，则使用缺省的scope. 如果申请多个scope，使用逗号分隔. ||
 * state || 可选参数，用来维护请求和回调状态的附加字符串，在授权完成回调时会附加此参数，应用可以根据此字符串来判断上下文关系. ||

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

例如：

{ –

– } 返回结果：


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

{ –

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

{ –

– }

获取access_token
{ –

– }
 * 参数名称 || 参数说明 ||
 * client_id || 必选参数，应用的唯一标识，对应于APIKey ||
 * client_secret || 必选参数，应用的唯一标识，对应于APIKey ||
 * redirect_uri || 必选参数，用户授权完成后的回调地址，应用需要通过此回调地址获得用户的授权结果. 此地址必须与在应用注册时填写的回调地址一致 ||
 * grant_type || 必选参数，此值可以为 authorization_code 或者 refresh_token 或者 password . 在本流程中，此值为 authorization_code ||
 * code || 必选参数，上一步中获得的authorization_code ||

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

例如：

{ –

– } 返回结果：

{{{#!highlight javascript}} { –

– } – }

使用access_token
{ –

– } =access_token有效期 与 refresh_token= 在OAuth2.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，需要单独申请，缺省情况下，应用没有refresh_token使用权限.

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

{ –

– }
 * 参数名称 || 参数说明 ||
 * client_id || 必选参数，应用的唯一标识，对应于APIKey ||
 * client_secret || 必选参数，应用的唯一标识，对应于APIKey ||
 * redirect_uri || 必选参数，用户授权完成后的回调地址，应用需要通过此回调地址获得用户的授权结果. 此地址必须与在应用注册时填写的回调地址一致 ||
 * grant_type || 必选参数，此值可以为 authorization_code 或者 refresh_token 或者 password . 在本流程中，此值为 refresh_token ||
 * refresh_token || 必选参数，刷新令牌 ||

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

例如：

{ –

– } 返回结果：

{{{#!highlight javascript}} { –

– } – }


 * 级别 || access_token有效期 || refresh_token有效期 || 说明 ||
 * L1 || 1天 || 无refresh_token ||
 * L2 || 30天 || 无refresh_token ||
 * L3 || 30天 || 60天 ||

=基于密码的高级授权方式= { –

– } 注意：此请求必须是HTTP POST方式
 * 参数名称 || 参数说明 ||
 * client_id || 必选参数，应用的唯一标识，对应于APIKey ||
 * client_secret || 必选参数，应用的唯一标识，对应于APIKey ||
 * redirect_uri || 必选参数，用户授权完成后的回调地址，应用需要通过此回调地址获得用户的授权结果. 此地址必须与在应用注册时填写的回调地址一致 ||
 * grant_type || 必选参数，此值可以为 authorization_code 或者 refresh_token 或者 password . 在本流程中，此值为 password ||
 * username || 必选参数，用户名 ||
 * password || 必选参数，密码 ||

例如： { –

– }

返回结果： {{{#!highlight javascript}} { –

– } – }

=访问速度控制= 在用户、应用、服务器IP、scope等维度对接口的访问速度进行限制.

针对服务器IP:
 * 级别 || 限制 ||
 * L1 || 5000次/小时 ||
 * L2 || 10000次/小时 ||
 * L3 || 20000次/小时 ||

针对单用户每应用每scope：
 * 级别 || 限制 ||
 * L1 || 60次/小时 ||
 * L2 || 150次/小时 ||
 * L3 || 300次/小时 ||

=错误代码= 如果在API使用过程中，有错误，则返回结果为： {{{#!highlight javascript}} { –

– } – }


 * 错误代码 || 错误说明 ||
 * 100 || invalid_request_scheme 错误的请求协议 ||
 * 101 || invalid_request_method 错误的请求方法 ||
 * 102 || access_token_is_missing 未找到access_token ||
 * 103 || invalid_access_token access_token不存在或已被用户删除 ||
 * 104 || invalid_apikey apikey不存在或已删除 ||
 * 105 || apikey_is_blocked apikey已被禁用 ||
 * 106 || access_token_has_expired access_token已过期 ||
 * 107 || invalid_request_uri 请求地址未注册 ||
 * 108 || invalid_credencial1 用户未授权访问此数据 ||
 * 109 || invalid_credencial2 apikey未申请此权限 ||
 * 110 || not_trial_user 未注册的测试用户 ||
 * 111 || rate_limit_exceeded1 用户访问速度限制 ||
 * 112 || rate_limit_exceeded2 IP访问速度限制 ||
 * 113 || required_parameter_is_missing 缺少参数 ||
 * 114 || unsupported_grant_type 错误的grant_type ||
 * 115 || unsupported_response_type 错误的response_type ||
 * 116 || client_secret_mismatch client_secret不匹配 ||
 * 117 || redirect_uri_mismatch redirect_uri不匹配 ||
 * 118 || invalid_authorization_code authorization_code不存在或已过期 ||
 * 119 || invalid_refresh_token refresh_token不存在或已过期 ||
 * 120 || username_password_mismatch 用户名密码不匹配 ||
 * 121 || invalid_user 用户不存在或已删除 ||
 * 122 || user_has_blocked 用户已被屏蔽 ||
 * 123 || access_token_has_expired_since_password_changed 因用户修改密码而导致access_token过期 ||
 * 124 || access_token_has_not_expired access_token未过期 ||
 * 999 || unknown 未知错误 ||