1、教育中台2.0接入指南

测试: https://xzzj.zjjy.xyz/zhuji-platform-api-test
正式: https://xzzj.zjjy.xyz/zhuji-platform-api

1.1、接入流程（必看）

接入方注册登录【开发者平台】，申请成为开发者；

创建应用，并选择需要访问的接口，应用通过审核后，在应用详情页查看分配AppKey和AppSecret；

接入方使用上述AppKey和AppSecret，参考[生成接入token实践示例]生成认证字符串访问对应的接口。

1.2、获取AppKey和AppSecret

在下方开发者中心注册成为开发者后，申请应用通过，在应用详情可获取到AppKey和AppSecret；
【开发者中心】
【测试环境】https://xzzj.zjjy.xyz/developer-center-test/login?redirect=/apps
【正式环境】https://xzzj.zjjy.xyz/developer-center/login?redirect=/apps
【开发者中心使用说明】https://www.kdocs.cn/l/cjyjR9xHyqY0

1.3、使用AppKey、AppSecret

每个应用申请成功后，会分配唯一AppKey和AppSecret。每个AppKey绑定创建应用时选择的api接口，应用上架表示该应用在中台系统中具有这些接口的访问权限。

以访问中台A接口为例：
前置条件：应用已通过审核，应用已上架（上架代表A接口已授权）。
A接口：https://xzzj.zjjy.xyz/zhuji-platform-api-test/service/v1/person/info/teachers

使用AppKey和AppSecret以及A接口的路由/service/v1/person/info/teachers，参考[生成接入token实践示例]生成token；

将token放入Header中的Authorization，即可访问成功。

1.4、接口调用规范

访问教育中台api接口时，必须包含以下header首部字段（必须携带认证字符串）：

名称	类型	是否必填	参数示例	说明
Authorization	string	yes	***	认证字符串

认证字符串（token）示例：

"readboy-edu-middle-v2/1610350572982010/2023-12-05T06:53:40Z/1800/host/9118c4f33c0224a7ea2fa4203011d4edb9dc68e986b72618cc1be6349d8b8d00"

到此处相信你已经可以成功接入教育中台api接口了^-^
如需关注细节，或者自己实现生成接口认证token，可继续往下读。

2、如何使用AppKey，AppSecret生成认证字符串（参考）

2.1、认证字符串规范格式

中台认证的规范字符串结构如下：

authStringPrefix/signedHeaders/signature

其中，authStringPrefix表示前缀字符串。signedHeaders表示选择签名的头域。signature表示签名摘要。

2.2、生成认证字符串编码指南

各个应用侧选择的语言各不相同，提供规范的生成认证字符串编码流程参考：

认证字符串Authorization的结构由以下三部分组成：

authStringPrefix/signedHeaders/signature

其中，authStringPrefix表示前缀字符串。signedHeaders表示选择签名的头域。signature表示签名摘要。

第一步：生成规范化请求和前缀字符串

规范化请求canonicalRequest
规范化请求canonicalRequest由四个部分组成，结构如下：

HTTP Method
CanonicalURI
CanonicalQueryString
CanonicalHeaders

HTTP Method

指HTTP协议中定义的GET、PUT、POST等请求方法，必须使用全大写的形式。

CanonicalURI

CanonicalURI是对URL中的绝对路径进行编码后的结果，即CanonicalURI = UriEncodeExceptSlash(Path)。要求绝对路径Path必须以"/"开头，不以“/”开头的需要补充上，空路径为"/"。

CanonicalQueryString

CanonicalQueryString是对于URL中的Query String（Query String即URL中"?"后面的"key1 = value1 & key2 = value2 "字符串）进行编码后的结果。

编码步骤如下：

提取URL中的Query String项，即URL中"?"后面的"key1 = value1 & key2 = value2 "字符串。
将Query String根据&分隔符拆开成若干项，每一项是key=value或者只有key的形式。
对拆开后的每一项进行编码处理，分以下三种情况。

当该项的key是authorization时，直接忽略该项。
当该项只有key时，转换公式为UriEncode(key) + "="的形式。
当该项是key=value的形式时，转换公式为 UriEncode(key) + "=" + UriEncode(value) 的形式。这里value可以是空字符串。
将每一项转换后的字符串按照字典顺序（ASCII码由小到大）排序，并使用& 符号连接起来，生成相应的CanonicalQueryString。
编码示例：

获取URL为https://readboy.com/example?text&text1=测试&text10=test的CanonicalQueryString。

提取URL中的Query String，得到 text&text1=测试&text10=test。
根据&对Query String进行拆分，得到text 、text1=测试、 text10=test三项。
对拆分的每一项进行编码。

对text项进行编码：UriEncode("text") + "="，得到"text="
对text1=测试项进行编码：UriEncode("text1") + "=" + UriEncode("测试")，得到"text1=%E6%B5%8B%E8%AF%95"
对text10=test项进行编码：UriEncode("text10") + "=" + UriEncode("test")，得到"text10=test"
对上面三项编码后的字符串进行（按照ASCII码由小到大）排序，得到结果是text10=test 、text1=%E6%B5%8B%E8%AF%95 、text= ，然后用&连接起来，得到CanonicalQueryString为text10=test&text1=%E6%B5%8B%E8%AF%95&text=。

CanonicalHeaders

CanonicalHeaders是对HTTP请求中的Header部分进行选择性编码的结果。
在这个步骤中，可根据Header部分确定签名头域（signedHeaders)。签名头域是指签名算法中涉及到的HTTP头域列表。HTTP头域名字一律要求小写且头域名字之间用分号（;）分隔，如host;range。选择哪些Header进行编码不会影响API的功能，但是如果选择太少则可能遭到中间人攻击。
对Header进行编码获取CanonicalHeaders，编码步骤如下。
将Header的名字变成全小写，注意仅改名字。
将Header的值去掉开头和结尾的空白字符。
经过上一步之后值为空字符串的Header忽略，其余的转换为 UriEncode(name) + ":" + UriEncode(value) 的形式。
把上面转换后的所有字符串按照字典序进行排序。
将排序后的字符串按顺序用\n符号连接起来得到最终的CanonicalHeaders。

规范化请求示例：
请求方法为POST，路径为/v1/test/myapi，参数为name=hello，选择的头域有Host:www.host.com，Content-Type:application/json。
则规范化请求为：

POST
/v1/test/myapi
name=hello
content-type:application%2Fjson
host:www.host.com

前缀字符串authStringPrefix
前缀字符串由四个部分组成，结构如下：
readboy-edu-middle-v2/AccessKeyId/时间戳/签名有效期

readboy-edu-middle-v2
固定字符串。

AccessKeyId
由中台下发给应用。

时间戳
生成签名的UTC时间，格式为yyyy-mm-ddThh:mm:ssZ，例如：2020-04-27T08:23:49Z。

签名有效期
签名有效期限，从timestamp所指定的时间开始计算，单位为秒。

前缀字符串示例：
readboy-edu-middle-v2/3752769628817301/2023-08-08T08:42:26Z/1800

第二步：生成派生签名密钥signingKey

派生签名密钥的生成方法为：

signingKey = HMAC-SHA-256-HEX("SecretAccessKey", authStringPrefix)

其中，SecretAccessKey由中台下发给应用。authStringPrefix是前文介绍的前缀字符串。HMAC-SHA256-HEX是HMAC SHA256算法函数。

第三步：生成签名摘要signature

签名摘要的生成方法为：
signature = HMAC-SHA-256-HEX(signingKey, canonicalRequest)
其中，signingKey是前文介绍的派生签名密钥。canonicalRequest是前文介绍的规范化请求。

第四步：拼接出认证字符串authorization

认证字符串的拼接方法为：
Authorization = authStringPrefix/signedHeaders/signature
其中，signHeaders填写方法为，把进行了编码的Header名字转换成全小写之后按照字典序排列，然后用分号（;）连接。

认证字符串示例：

readboy-edu-middle-v2/3752769628817301/2023-08-08T08:42:26Z/1800/content-type;host/c8c841262d106a9657543b37f02095d289290783c3329a92b4dbb036db119593

教育中台API-接入指南

1、教育中台2.0接入指南#

1.1、接入流程（必看）#

1.2、获取AppKey和AppSecret#

1.3、使用AppKey、AppSecret#

1.4、接口调用规范#

2、如何使用AppKey，AppSecret生成认证字符串（参考）#

2.1、认证字符串规范格式#

2.2、生成认证字符串编码指南#

第一步：生成规范化请求和前缀字符串#

第二步：生成派生签名密钥signingKey#

第三步：生成签名摘要signature#

第四步：拼接出认证字符串authorization#