网站接入

网站接入流程示例图
  • A.你的网站用户通过浏览器正常访问网站,在某次访问过程中,网站需要使用该用户的麦库数据。此时你的网站代码应当检查固定存储(如数据库)中是否有该用户访问麦库的凭证(access token),如果有则跳到步骤F,否则跳到步骤B。

  • B.你的网站指示用户浏览器跳转到麦库授权服务(http://open.note.sdo.com/authorize),跳转时携带的参数如下:

    • 1. response_type 必需参数,且为固定值 code

    • 2. client_id 必需参数,你的网站申请接入麦库后获得的应用id

    • 3. state 可选参数但推荐使用,在整个授权过程中state参数会一直被保留,当授权过程完成回到你的网站时根据state参数可以很容易地继续授权前的操作

    • 4. scope 可选参数,表示你的网站需要请求麦库用户的哪些权限,如果不传那么默认只能操作你的网站产生的数

    • 5. 其他参数一律被忽略

  • 一个正确的跳转地址例子:

    http://open.note.sdo.com/authorize?response_type=code&client_id=demo&state=/home/test
  • C.用户的浏览器被重新定向到麦库授权服务,麦库将确认用户身份并引导用户完成对你的网站的授权。

  • D.麦库授权服务将用户浏览器重定向到你的网站的回调地址(申请接入时填写的回调地址),跳转时携带的参数如下:

    • 1. code 本次授权的令牌,有效期为10分钟

    • 2. state 如果步骤B中包含了state参数的话将会原样返回

    一个成功授权的例子:

    http://www.yoursite.com/oauth/entry?code=A2SP9FR&state=/home/test

    异常处理:如果用户在步骤C中拒绝对你的网站授权,那么跳转到你的回调地址时的参数如下:

    • 1. error 错误类型,它的可能值参照麦库开放API错误类型定义,这里通常是access_denied

    • 2. error_descriptiton 可读的错误描述文本

    • 3. state 如果之前的请求包含了这个参数的话

    一个拒绝授权的例子:

    http://www.yoursite.com/oauth/entry?error=access_denied&state=/home/test
  • E.你的网站令牌入口收到了本次授权的令牌,通过服务器端代码发起一次请求到麦库授权服务,用令牌换取凭证。将请求的Authorization头信息的值设置为你的client secret经过UTF8编码再转为base64的字符串,即 base64(utf8(secret)),请求时携带的参数如下:

    • 1. grant_type 必需参数,且为固定值 authorization_code

    • 2. code 必需参数,本次授权的令牌请求成功后麦库授权服务将返回一段包含凭证信息的json。在此之后你应该保存这个凭证,这样下次步骤A可以直接跳到步骤F而不用总是重复步骤B~步骤E。

    一个换取凭证的例子:

    GET HTTP/1.1 
    Host: open.note.sdo.com 
    Authorization: czZCaGRSa3F0MzpnWDFmQmF0M2JW 
    Content-Type: application/x-www-form-urlencoded; charset=UTF-8
    
    http://open.note.sdo.com/authorize?grant_type=authorization_code&code=A2SP9FR
                    

    一个成功返回凭证的例子:

    HTTP/1.1 200 OK 
    Content-Type: application/json; charset=UTF-8
    
    { 
       "open_id" : "123432153", 
       "access_token" : "2YotnFZFEjr1zCsicMWpAA", 
       "expires_in" : 36000
    } 
                    

    注:open_id 是该麦库用户对外的唯一标识,在某些特殊情况下你的网站可能会用到它。expires_in表示该凭证的过期时间,单位为分钟。当用户的凭证过期时,你需要重新引导用户授权。

    一个获取凭证失败的例子,这通常是由于code过期/无效/被重复使用引起的:

    HTTP/1.1  400 Bad Request
    Content-Type: application/json; charset=UTF-8
    
    {
       "error" : "invalid_request",
       "error_description" : "this code is invalid or expired"
    }
                    
  • F.你的网站通过用户的凭证访问当前用户的麦库数据,操作接口详见《麦库开放API接口文档》(下载链接)。