名词解释

名词 解释

{domain}

需要接入的第三方的域名

{platform}

河南省职业教育公共服务平台的域名

概述及通用规则

为了使用职教资源公共服务平台提供的API(应用程序接口),首先第三方应用需要向平台申请一个专属的App IDApp Secret

AppIdAppSecret的使用方式跟其他一些协议中的公钥私钥的方案相类似,您可以使用你所熟悉的编程语言将AppIdAppSecret结合,为发出的每个请求添加签名,以此来向职教资源公共服务平台表明自己身份的合法性。

目前职教资源平台使用的用户授权协议是OAUTH2.0版本。

该文档描述了职教资源平台为第三方应用所提供的接口,接口主要分为以下三大类:

  • 授权服务

  • 用户类服务

用户鉴权流程

  1. 用户登录职教资源平台并点击要进入的第三方应用。

  2. 职教资源平台跳转到第三方应用的入口URL,第三方应用请求用户给予进入应用的授权。

  3. 用户同意授权,平台返还给第三方应用授权码。

  4. 应用使用上一步获得的授权码,向职教资源平台申请令牌,调用申请令牌接口。

  5. 职教资源平台对第三方应用的授权码进行认证以后,确认无误,发放令牌。

  6. 应用使用令牌,向职教资源平台申请获取资源,调用查询授权用户信息接口。

  7. 职教资源平台确认令牌无误,返回给第三方应用登录用户的相关信息。

授权服务API

该类接口遵循OAuth 2.0标准,有关该协议的详细内容,请参考 OAuth标准

用户授权-请求授权

向职教资源公共服务平台请求授权,该接口将用户引导到登录页面,并请求用户对应用授权。

接口URL

[GET]{domain}/oauth2/authorize

请求参数

参数字段 必选 类型及范围 说明

response_type

true

String

表示授权类型,此处的值固定为 code

client_id

true

String

表示平台分配的 AppId

redirect_uri

false

String

表示成功重定向URI。

scope

false

String

表示申请的权限范围。

state

false

String

表示应用的当前状态,可以指定任意值,认证服务器会原封不动地返回这个值。

返回数据

点击授权登录后,页面会重定向到redirect_uri所指定的页面,并在url后加入下面的参数

返回值字段 必选 类型及范围 说明

code

true

String

授权码。该码的有效期应该很短,应用只能使用该码一次,否则会被授权服务器拒绝。该码与client_id(appId)和redirect_uri,是一一对应关系。

state

false

String

如果应用的请求中包含这个参数,认证服务器的回应也包含一模一样的这个参数值。

示例

GET请求:{domain}/oauth2/authorize?client_id=client&response_type=code&redirect_uri=http:///samplecloud/oauth2success
同意授权后,服务器会重定向请求中的redirect_url:{platform}/oauth2success?code=hOnH3k

用户授权-申请用户授权令牌

应用向职教资源平台申请访问令牌(access token)。

接口URL

[post]{domain}/oauth2/token
此处的appIdappSecret是职教资源平台颁发给第三方应用的,每个应用均唯一。

请求参数

参数字段 必选 类型及范围 说明

grant_type

true

String

表示授权类型,此处的值固定为 authorization_code

client_id

true

String

表示应用的 AppId

redirect_uri

true

String

表示重定向URI,必须与 请求授权 中的参数值保持一致。

code

true

String

表示请求授权中获取的授权码。

返回数据

返回值字段 必选 类型及范围 说明

access_token

true

String

表示访问令牌。

token_type

true

String

表示令牌类型,该值大小写不敏感,平台固定返回bearer。

示例

同意授权后会重定向请求中的redirect_url 返回JSON参数:
	HTTP/1.1 200 OK
	Content-Type: application/json;charset=UTF-8
	Cache-Control: no-store
	Pragma: no-cache
	{
	 "access_token":"2YotnFZFEjr1zCsicMWpAA",
	 "token_type":"bearer",
	 "expires_in":32,
	 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
	 "scope":"basic"
	}

应用授权-申请应用授权令牌

职教资源平台除了提供以用户为中心的授权接口外,还提供了一些数据层面上的集成服务,如待办集成、数据视图集成等。对于这些接口的调用,则需要先调用应用授权API,获取access token后,才可以调用相关API。

接口URL

[get]{domain}/oauth2/token
此处的appIdappSecret是职教资源平台颁发给第三方应用的,每个应用都不一样。

请求参数

参数字段 必选 类型及范围 说明

grant_type

true

String

表示授权类型,此处的值固定为 client_credentials

client_id

true

String

表示应用的 AppId

返回数据

返回值字段 必选 类型及范围 说明

access_token

true

String

表示访问令牌。

token_type

true

String

表示令牌类型,该值大小写不敏感,平台固定返回bearer。

用户类服务

以用户为中心的相关接口服务

查询授权的用户信息

根据从用户授权中得到的access_token向服务器查询用户的基本信息。

接口URL

[get]{platform}/sns/userinfo

请求参数

参数字段 必选 类型及范围 说明

access_token

true

String

表示访问令牌。

返回数据

返回值字段 必选 类型及范围 说明

unionid

true

String

第三方唯一标识。

nickname

true

String

用户姓名

headimgurl

true

String

用户头像

sex

true

Int

1:“男”|2:“女”

返回的用户信息(JSON格式数据):
	{
	    "unionid ":"100000",
	    "nickname":"隔壁老王"
	    "headimgurl":"/img/1.jpg",
	    "sex":1
	 }
								
openid为用户在职教资源平台中的唯一标识,第三方应用应保存并维护其和自己系统用户的对应关系,便于后续调用职教资源API时传入。