入门与指南专题介绍帐号管理营销资产广告管理数据洞察人群管理数据接入接口清单
授权认证 帐号管理 营销资产 广告管理 数据洞察 辅助工具 用户行为数据 用户人群数据 用户标签数据 用户属性数据
附录

授权认证

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

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

注:微信账号授权获得的token,目前仅支持异步任务下载广告报表、表单线索查询、用户行为数据上报、人群上传四种接口,其他接口暂不支持。

本章节将详细为您介绍以下内容:


一、如何通过 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(可选)。

详细描述如下:
Step 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(详见下一步),并在跳转后的页面对客户给出相应的提示或跳转指引。

Step 2:使用 authorization_code 获得 access_token 和 refresh_token

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

名称 类型 描述
client_id
integer 应用 id,在开发者官网创建应用后获得,可通过 [应用程序管理页面] 查看
client_secret
string 应用 secret,在开发者官网创建应用后获得,可通过 [应用程序管理页面] 查看
字段长度最小 1 字节,长度最大 256 字节
grant_type
string 请求的类型,可选值: authorization_code (授权码方式获取 token )、 refresh_token (刷新 token )
字段长度最小 1 字节,长度最大 64 字节
authorization_code
string OAuth 认证 code,可通过获取 Authorization Code 接口获取,当 grant_type=authorization_code 时必填
字段长度最小 1 字节,长度最大 64 字节
refresh_token
string 应用 refresh token,当 grant_type=refresh_token 时必填
字段长度最小 1 字节,长度最大 256 字节
redirect_uri
string 应用回调地址,当 grant_type=authorization_code 时, redirect_uri 为必传参数,仅支持 http 和 https,不支持指定端口号,且传入的地址需要与获取 authorization_code 时,传入的回调地址保持一致
字段长度最小 1 字节,长度最大 1024 字节

请求示例:
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天

二、如何更新 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会自动续期。

三、如何更新 refresh_token

如果 refresh_token 失效,您需要重新通过 OAuth 2.0 获得新的 access_token 和 refresh_token 。

关于 OAuth 2.0 相关接口说明,可以参考接口清单中的 OAuth 相关接口