T/ZGCSC 001-2023 全民健身信息服务平台接口要求

团体标准

T/ZGCSC001—2023

全民健身信息服务平台接口要求

Nationalfitnessinformationserviceplatforminterfacerequirements

2023-02-01发布2023-02-02实施

中关村智慧城市产业技术创新战略联盟发布

T/ZGCSC001—2023

目次

前言II

1范围1

2规范性引用文件1

3术语和定义1

4缩略语2

5数据类型2

6总体要求2

平台接口架构2

认证与安全3

接口全局描述4

7设备管理4

概述4

请求参数4

8运动报告管理6

概述6

请求参数6

9训练任务管理7

概述8

请求参数8

10区域管理9

概述9

请求参数9

11设备组管理10

概述10

请求参数10

12用户信息管理11

概述11

请求参数11

13用户组管理12

概述12

请求参数12

附录A（资料性）添加新用户示例14

参考文献17

I

T/ZGCSC001—2023

前言

本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定

起草。

本文件由中关村智慧城市产业技术创新战略联盟提出并归口提出。

本文件起草单位：北京格灵深瞳信息技术股份有限公司、首都体育学院、北京理工大学、首都医科

大学附属北京朝阳医院、普天数字健康城市科技有限公司、悦动奇点（北京）健康科技有限公司、北极

星云空间技术股份有限公司、北京柏睿数据技术股份有限公司、北京启迪区块链科技发展有限公司、特

斯联科技集团有限公司、天津智诚智慧城市运营管理有限公司、崇左市数字经济创新研究院。

本文件主要起草人：夏鹏飞、刘彤、陈天博、张涛、段海涛、张诚、张慧慧、李翰霖、盖晓宇、段

鑫源、申浩杰、张子涛、肖英杰、隋英杰、李晓伟、王金益、孟宪科、吴晚冬、李柱臣、高阳、朴晟宏、

苗雨新、杨钰、陈阳、刘艳蓉。

II

T/ZGCSC001—2023

全民健身信息服务平台接口要求

1范围

本文件给出了全民健身信息服务平台接口的总体要求以及区域管理、设备组管理、设备管理、用户

信息管理、运动报告管理用户组管理和训练任务管理的接口描述。

本文件适用于全民健身信息服务平台的应用与运维。

2规范性引用文件

下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，

仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本

文件。

GB/T19851.1—2022中小学体育器材和场地第1部分：体育器材的通用要求和试验方法

GB/T35273—2020信息安全技术个人信息安全规范

GB/T35295—2017信息技术大数据术语

GB/T38672—2020信息技术大数据接口基本要求

3术语和定义

GB/T35273—2020、GB/T35295—2017、GB/T38672—2020界定的以及下列术语和定义适用于本文

件。

数据同步datasynchronization

建立源和目标数据存储之间的一致性的过程。

[来源：GB/T38672—2020,3.6]

数据治理datagovernance

对数据进行处置、格式化和规范化的过程。

注1：数据治理是数据和数据系统管理的基本要素。

注2：数据治理涉及数据全生存周期管理,无论数据是处于静态,动态、未完成状态还是交易状态。

[来源：GB/T35295—2017,2.1.43]

公共请求头requestheader

调用接口时，公共的附加请求头字段，如指定的URI和HTTP方法所要求的字段。

个人信息personalinformation

以电子或者其他方式记录的能够单独或者与其他信息结合识别特定自然人身份或者反映特定自然

人活动情况的各种信息。

注1：个人信息包括姓名、出生日期、身份证件号码、个人生物识别信息、住址、通信通讯联系方式、通信记录和内

1

T/ZGCSC001—2023

容、账号密码、财产信息﹑征信信息﹑行踪轨迹、住宿信息﹑健康生理信息、交易信息等。

注2：关于个人信息的判定方法和类型参见附录A。

注3：个人信息控制者通过个人信息或其他信息加工处理后形成的信息,例如,用户画像或特征标签,能够单独或者

与其他信息结合识别特定自然人身份或者反映特定自然人活动情况的,属于个人信息。

[来源：GB/T35273—2020,3.1]

4缩略语

下列缩略语适用于本文件。

API：应用程序接口（ApplicationProgrammingInterface）

GMT：格林尼治标准时间（GreenwichMeanTime）

HTTP：超文本传送协议（HyperTextTransferProtocol）

URL：统一资源定位符（UniformResourceLocator）

5数据类型

本文件涉及的数据类型包括：

a)基本数据类型：

1)Int：整型数值类型；

2)String：字符串类型。

b)派生类型：

1)File：文件类型；

2)[]String：数组类型；

3)Event：结构化类型(struct)；

4)[]Event：结构化数组类型；

5)[]ContentGroup：结构化数组类型；

6)[]TrainingContent：结构化数组类型；

7)[]Image：结构化数组类型；

8)Image：结构化类型(struct)；

9)ContentGroup：结构化类型(struct)；

10)TrainingContent：结构化类型(struct)；

11)Map：键值对类型。

6总体要求

平台接口架构

本文件中涉及的所有接口如图1所示。

2

T/ZGCSC001—2023

图1全民健身信息服务平台接口示意图

全民健身信息服务平台自下而上包括基础层和应用层，其中：

a)基础层提供平台的基本功能模块，包括用于区分物理或逻辑区域的区域模块，用于设备分类管

理的设备组模块，用于人员管理的用户信息管理模块和对用户进行分组管理的用户组管理模

块，开发者可以通过接口调用这部分功能；

b)应用层提供平台的运动数据与物联网应用模块，包括设备管理模块，运动包括管理模块和训练

任务管理模块，开发者可以通过接口方式对设备进行相应操作，获取设备产生的运动报告信息

和训练任务等信息。

认证与安全

6.2.1鉴权机制

本文件设计的鉴权机制主要内容如下：

a)创建API时，应选择鉴权类型为“密钥对鉴权”。当选择密钥对鉴权类型的API发布时，只

有使用正确密钥对发起的访问能够通过API网关的校验，不携带密钥或携带错误的密钥对不

能通过API网关的鉴权；

b)API创建完成后，可以使密钥对与API或API所在服务进行绑定。

6.2.2密钥内容

密钥包括以下两种表现形式：

a)secret_id：用于标识所使用的哪个密钥，并参与签名计算，传输过程中体现；

b)secret_key：用于签名计算，传递过程中无体现。

6.2.3数据安全要求

3

T/ZGCSC001—2023

本文件涉及数据任何组织、个人应当采取合法、正当的方式使用，不得窃取或者以其他非法方式获

取数据，对于个人信息的处理活动应遵循合法、正当、必要的原则，应符合GB/T35273—2020各项要求。

接口全局描述

本文件系统总体要求应符合GB/T19851.1—2022中5.6.2的规则，其中系统接口的公共请求头按表

1要求编制，接口按照接口概述和请求参数描述展开，附录A为接口调用和使用示例。

表1公共请求头

参数名类型长度约束是否必填参数说明

AcceptString-否指定客户端能够接收的内容类型

Accept-CharsetString-否浏览器可以接受的字符编码集

SourceString36是组织ID，对应org_id

GMT格式的HTTP请求构造时间，例如Mon,19Mar201812:08:40

X-DateString-是

GMT

AuthorizationString-是签名内容见6.2.2

7设备管理

概述

本文件中此类接口主要与设备管理各项命令相关联，包括：

a)添加设备，在平台中添加新设备；

b)修改设备，更新设备信息；

c)删除设备，删除未被使用的设备；

d)设备列表，获取设备列表；

e)设备详情，根据条件查询单条设备信息；

f)设备变更日志，包括设备启动、运动执行、参数变更等,排序为时间倒序；

g)设备控制指令，可向指定的设备发送上传背景图、打开调试模式等控制指令事件，事件依次异

步执行；

h)设备历史状态，可通过时、分维度查看状态；

i)修改部分配置，远程参数配置，具体参数配置等确定后补充；

j)设备类型列表，获取设备类型列表；

k)请求参数配置，可查询设备配置参数。

请求参数

设备管理的请求参数见表2。

表2请求参数

参数名称类型是否必选参数说明备注

area_idString否所属区域ID

4

T/ZGCSC001—2023

表2请求参数（续）

参数名称类型是否必选参数说明备注

device_group_ids[]String否关联设备组ID

tags[]String否标签不支持模糊匹配

device_idString是设备序列号

device_nameString是设备名称

device_descString否设备描述

extendsMap<String,String>否可扩展字段

device_typeString是设备类型

device_ipString否设备IP当设备类型是IPC相机时，必填

user_nameString否用户名称当设备类型是IPC相机时，必填

passwordString否密码当设备类型是IPC相机时，必填

action_idString否运动项目ID

离线

device_stateString否设备状态

在线

pageInt否页码默认为第1页

page_sizeInt否每页条数默认50条，上限为100条

change_typeString否日志变更类型

start_timeInt是指定查询时间窗口的开始时间Unix系统时间戳毫秒数

end_timeInt是指定查询时间窗口的结束时间Unix系统时间戳毫秒数

events[]Event是指令事件集

from_dateString是开始时间日期

算法引擎，动作规则，渲染相

part_configMap<String,Object>是参数配置

关，系统运行，报警

type_nameString否类型名称

其中Event结构化类型见表3。

表3Event结构化类型

参数名称类型是否必选参数说明

cmdString是控制命令

paramString否指令参数

5

T/ZGCSC001—2023

8运动报告管理

概述

本文件中此类接口主要关联运动报告中各项指标，包括：

a)查询运动报告列表，根据指定的时间范围查询注册用户的运动报告，默认按照报告生成时间倒

序输出；

b)注册报告推送地址，该接口接收用户自定义的HTTPs报告接收服务地址，满足条件的报告生

成后以POSTBody的形式主动推送到相应