授权认证

本节将为您介绍如何进行 Marketing API 的授权认证。

Marketing API目前支持基于QQ和微信两种账号进行授权鉴权。所有接口均通过请求参数中传递的 access_token（授权令牌）来进行身份认证和鉴权，系统会在校验 access_token有效、接口调用配额未用完、接口调用频次未超限3个条件符合后接受此次请求进行具体业务处理并做出响应。

1. 如何通过 OAuth 2.0 获得 access_token

客户需要通过您的应用进行推广操作时，您的应用需要先引导客户完成至少一次 OAuth 2.0 认证操作，以便获得调用接口操作的客户的推广帐号所必须的 access_token 。Marketing API的 OAuth 2.0 遵循业界通用的规范和流程，完成 OAuth 2.0 认证（当前只支持 server-side 模式）需要完成以下步骤：

• A、引导客户进入 OAuth 2.0 登录界面；
• B、客户用推广帐号登录（基于QQ号的使用开户QQ或自理管理员QQ，基于微信号的使用微信公众号或代理商管理员对应的微信账号扫码），；
• C、登录成功并确认授权后腾讯广告将向您的应用程序返回一个授权码（Authorization Code）；
• D、应用程序调用接口用授权码（Authorization Code）获得 access_token，同时获得一个用于刷新 access_token 的 refresh_token；
• E、在 access_token 过期后，使用 refresh_token 获得新的 access_token（可选）。

详细描述如下：

步骤1：引导客户完成OAuth 2.0认证获得authorization_code

获得 authorization_code 需要引导客户完成 OAuth 2.0 的认证。调用 OAuth 2.0 授权页面的URL形如：
https://developers.e.qq.com/oauth/authorize?client_id=123456&redirect_uri=https%3a%2f%2fwww.example.com%3fpara1%3da%26para2%3db&state=&scope=ADS_MANAGEMENT&account_type=ACCOUNT_TYPE_QQ

其中：

• client_id：开发者创建的应用程序的唯一标识id，必填，可通过【应用程序管理页面】查看；
• redirect_uri：回调地址，由开发者自行提供和定义（地址主域需与开发者创建应用程序时登记的回调主域一致），用于跳转并接收回调信息，必填，该字段需要做UrlEncode，确保后续跳转正常；
• state：开发者自定义参数，可用于验证请求有效性或者传递其他自定义信息，回调的时候会原样带回，可选；
• scope：授权的能力范围，可选，不传时表示授权范围为当前应用程序所拥有的所有全部权限；
• account_type：授权用的账号类型，可选，包括QQ号和微信号，不传时默认为QQ号

OAuth 2.0 授权页面如下图所示：

其中页面右侧为应用程序信息，左侧为请求授权的帐号信息，客户可以切换选择是用QQ号还是用微信号，推荐开发者直接在引导客户进入授权页时通过account_type指定要授权的账号类型。

右侧显示的是应用程序的logo、名称、以及可授权的权限组分类。

• 其中logo、名称是创建应用程序时开发者自行上传的信息，可授权的权限组分类是根据开发者调用oauth/authorize接口同步的scope生成的权限组信息；
• 授权客户可通过列表选择授权给开发者的操作权限。

左侧是提供给授权客户进行身份验证的入口。如客户同意授权，需要登录其对应的 QQ 帐号或者用微信号扫码，并点击同意授权。
登录后，页面将会显示请求授权的 账号信息。

值得注意的是，请求授权的 QQ 帐号需要是商务管家、代理商或直客广告主的开户 QQ，或者是子客户的自理管理 QQ，微信账号需要是微信广告账号对应的公众号管理员微信，或者微信广告代理商的管理员微信，否则将会授权失败。

不同类型的帐号在同意授权后，应用可操作的推广帐号不同，具体规则如下：

• 如果请求授权的是 QQ代理商帐号，代理商用 开户 QQ 登录并同意授权，完成 OAuth 2.0 后应用获得 access_token，该应用会获得 当前代理商所有子客户的推广帐号 的操作权限；
• 如果请求授权的是 QQ直客帐号，客户用 开户 QQ 登录并同意授权，完成 OAuth 2.0 后应用获得 access_token，该用户会获得 当前客户推广帐号 的操作权限；
• 如果请求授权的是 QQ商务管家帐号，客户用 开户 QQ 登录并同意授权，完成 OAuth 2.0 后应用获得 access_token，该用户会获得 当前商务管家账号下推广帐号 的操作权限；
• 如果请求授权的是 QQ代理商子客户，用子客户的 自理管理员 QQ（由代理商分配）登录并同意授权，完成 OAuth 2.0 后应用获得 access_token，该应用会获得 当前子客户推广帐号 的操作权限。
• 如果请求授权的是 微信广告代理商帐号，代理商用 管理员微信 扫码并同意授权，完成 OAuth 2.0 后应用获得 access_token，该应用会获得 当前代理商及所有代理客户的推广帐号 的操作权限；
• 如果请求授权的是 微信广告主帐号，客户用 微信公众号对应的管理员微信 扫码并同意授权，完成 OAuth 2.0 后应用获得 access_token，该用户会获得 当前客户推广帐号 的操作权限；

当引导客户在上述登录界面完成登录身份验证后，系统会携带 authorization_code（有效期5分钟）和state两个参数在浏览器端发出GET请求，形如： http://www.example.com/response?authorization_code=6a6b6c6d&state=112233

当上述请求完成或请求链接超出3秒时，系统会自动跳转到刚才定义的回调地址中。您的应用程序在收到上述返回后，应当在 authorization_code 有效期内，利用 authorization_code 获得 access_token（详见下一步），并在跳转后的页面对客户给出相应的提示或跳转指引。

步骤2：使用 authorization_code 获得 access_token 和 refresh_token

用 authorization_code 获得 access_token 和 refresh_token 的接口地址为 https://api.e.qq.com/oauth/token，接口输入参数如下表所示：

请求示例：

curl -G 'https://api.e.qq.com/oauth/token' \
    -d 'client_id=<CLIENT_ID>' \
    -d 'client_secret=<CLIENT_SECRET>' \
    -d 'grant_type=authorization_code' \ 
    -d 'authorization_code=<AUTHORIZATION_CODE>' \
    -d 'redirect_uri=https://www.example.com'

返回示例：

{
    code: 0,
    message: ,
    data: {
        access_token: 228bd56b7ee039540953352f766b40d31651487e,
        refresh_token: 854e744a1f4c6fc20f498e366b9aabd2c4b971fd,
        access_token_expires_in: 86400,
        refresh_token_expires_in: 2592000 
    }
}

获得 access_token 后，您可用此调用接口对相关的推广帐号进行操作，如果发起Marketing API请求可通过发起请求章节进行了解。

值得注意的是，一旦 access_token 失效，您将无法调用接口。access_token 和 refresh_token 的有效期可以通过 oauth/token 接口的返回字段获取，默认情况下 access_token 和 refresh_token 的有效期如下：

• access_token默认有效期为24小时
• refresh_token默认有效期为30天

2. 如何更新 access_token

在refresh_token有效期内，您可以用 refresh_token 通过 auth/token 接口刷新 access_token。请求示意如下：

curl -G 'https://api.e.qq.com/oauth/token' \
    -d 'client_id=<CLIENT_ID>' \
    -d 'client_secret=<CLIENT_SECRET>' \
    -d 'grant_type=refresh_token' \
    -d 'refresh_token=<REFRESH_TOKEN>'

特别注意，每次刷新access_token时， refresh_token会自动续期。

3. 如何更新 refresh_token

如果 refresh_token 失效，您需要重新通过 OAuth 2.0 获得新的 access_token 和 refresh_token 。 关于 OAuth 2.0 相关接口说明，可以参考接口清单中的 OAuth 相关接口。