通达OA系统对接

1 概述

1.1 目的

本文档主要描述《高校统一数据开放平台》管理系统的使用说明。主要内容包括概述和使用说明两个方面，适用产品使用者、测试人员、系统维护人员以及相关评审专家等，下面将展开相关说明。

1.2 读者对象

本文档适用产品使用者、测试人员、系统维护人员以及相关评审专家等。未经产品经理许可，该文档不得提供给规定对象以外的人员阅读或使用。

2 使用说明

开发者是平台应用的开发者，开发者可以新增或查看自己在平台上添加的应用；同时，平台用户也可以访问数据集市，浏览数据集市中的数据，根据自己的需要申请调用数据，支持API接口、直连数据库和计算数据集等多种方式，管理员审批通过后，开发者可以调用数据。

2.1 开发者中心

开发者登录平台后默认进入到开发者中心的页面，开发者可以在开发者中心创建应用、为应用申请数据以及查看已创建的应用数据调用情况，开发者中心提供了多种使用文档，可帮助开发者快速了解并使用平台申请、调用数据。

2.1.1 应用管理

应用管理汇总展示了开发者自己在平台中新建的应用，该页面可根据应用状态（全部/已上架/未上架/已下架）或在右上角检索栏输入应用名称进行快速筛选。如图2-1-1。

图2-1-1

点击右上角的创建新应用可跳转到新增应用的页面，带“*”号的内容为必填项，信息填写完毕后点击保存按钮，保存成功即应用创建成功。新建的应用默认状态为未上架，运行情况为开发中。如图2-1-2。

图2-1-2

在应用管理页面点击右上角的开发者操作指南可打开开发者快捷指南，快捷指南中包含了开发者常用操作的操作说明。如图2-1-3。

图2-1-3

在应用管理页面操作栏中点击预览，可跳转到应用地址页面，预览该应用。

在应用管理页面操作栏中点击查看按钮可查看该应用的具体信息，在该页面可以申请应用上架、编辑/修改应用的基本信息、管理API、数据开放、数据计算等操作。如图2-1-4。

图2-1-4

在应用查看页面点击右上角的申请上架，将跳转到应用申请上架的页面，填写表单信息后保存，该申请会推送给后台管理员进行审核，审核通过后，该应用的状态将变为已上架。如图2-1-5。

图2-1-5

如应用已经上架，点击应用查看进入应用详情页，右上角的申请上架按钮将展示为申请下架按钮。如图2-1-6。

图2-1-6

除下架功能外，已上线的应用支持通过开启维护按钮进入维护期，应用进入维护期后，平台用户在前台应用大厅预览该应用时会进入已设定好的维护页面。如图2-1-7。注：该功能主要用于学校应用升级或处于某种特殊时期时，应用无法访问又不想下架或隐藏应用时使用，应用进入维护期后，开启维护按钮将变为结束维护按钮，开发者可自行结束应用维护阶段。

图2-1-7

在应用管理页面操作栏中点击删除按钮，再次确认之后该应用将从应用列表中移除。如图2-1-8。注：运行中/维护中的应用操作区域的删除按钮为灰色，无法删除，需要先申请下架之后才可以删除。

图2-1-8

（一）管理基本信息

在查看应用详情页（见图2-1-4），开发者可以点击基本信息区域的管理基本信息按钮对应用详情进行编辑。如图2-1-9。注：如该应用已经上线，修改应用基本信息之后会向后台提交一条应用变更申请，管理员可对该申请进行审核，审核同意后该修改生效。

图2-1-9

已上架的应用在基本信息区域会存在一个查看上架信息的按钮，点击查看上架信息可以查看应用的上架信息。如图2-1-10。注：未上架的应用没有该按钮。

图2-1-10

在查看应用详情页点击基本信息区域的“APP Key”按钮可以查看该应用唯一对应的App Key和App Secret，点击复制按钮可快速将对应内容复制到剪切板。图2-1-11。

图2-1-11

（二） API管理

在查看应用详情页（图2-1-4），通过API管理区域的“申请API”按钮可跳转到申请API的页面，页面左侧支持根据API分类进行筛选，API分类后的括号中展示的内容是指：分类下有数据的API数量/分类下API总数量；页面右侧展示了该API分类中的API明细信息，API名称后的括号中展示该API的数据条目数，右上角的检索功能支持通过API名称进行快捷检索；调用类型分为：全量、查询、新增、修改（全量指该支持对该接口进行查询、新增以及修改操作；查询指该接口只支持查询操作；新增指该接口支持查询和新增操作；修改指该接口支持查询和修改操作）；状态（指API申请状态）分为：待审批、审批通过、未授权；如开发者已经获得该API全部字段的授权，则申请按钮会灰色显示，不可再点击申请按钮。如图2-1-12。

图2-1-12

如果开发者在申请API的页面没有看到可供申请的API可能有两种情况，第一，管理员没有在自定义API页面中发布自定义API。第二，当前用户不具备使用API的权限，如想申请API进行使用，可以联系管理员把该用户加入到相应的角色组，即可浏览体验该角色组下的API进行申请使用。

在申请API页面，点击API名称可以查看接口调用请求、请求参数说明、返回参数说明，以及下载该API的数据字典、查看JSON返回示例。如图2-1-13。该部分逻辑同数据集市API数据集部分一致，此处不再赘述。

图2-1-13

点击右上角的请求示例和JSON返回示例可以查看对应说明。如图2-1-14

图2-1-14

在申请API页面，点击操作区域的申请按钮，可跳转到申请窗口，申请窗口展示了当前API的字段总数，选择需要申请的字段，填入申请理由（选填），勾选我已阅读并同意《API申请协议》后即可点击提交申请按钮。图2-1-15。API申请提交后，页面会停留到申请API的页面。

图2-1-15

在申请API页面点击操作区域的测试按钮，可进入到API测试工具中，页面左上角可修改选定测试的API，右上角可查看参数约定、查看调用示例、查看完整API信息，点击添加API参数可设置API测试参数，支持添加多个测试参数，点击测试按钮后，可查看请求参数和返回请求内容。如图2-1-16。

注：为了保障学校数据安全，申请API页面进行API测试，返回请求中的内容是经过加密处理的脱敏数据。且该处地址使用的是测试地址，复制到浏览器访问时，不一定能够请求成功，而且测试地址无法直接用于应用开发，如需用于应用开发，请先申请API，获得授权后，使用API管理中的URL地址进行应用开发。

图2-1-16

其中返回请求可成Json格式进行查看。如图2-1-17。注：为了保障学校数据安全，API测试仅会返回三条脱敏后的的数据，如需使用真实数据请先申请API，管理员审核通过后即可查看真实数据。

图2-1-17

在查看应用详情页面API管理区域点击API管理，可跳转到API管理页面。已经申请并审核通过的API会出现在API管理页面中，该页面可通过API分类、API名称或授权状态（授权中/已失效）进行快捷筛选。如图2-1-18。

点击页面右上角的一键下载数据字典按钮可以一次性将该应用已申请成功的API接口数据字典打包压缩之后下载到本地。

图2-1-18

点击API管理页面列表中的API名称可打开到数据集市中API详情的页面，该页面逻辑同申请API页面中点击API名称一致，此处不再赘述。

今日调用指应用今日调用该API的次数；调用总次数指应用调用该API的总次数，鼠标悬浮在列表中调用总次数上可以趋势图展示了近七日应用调用API的趋势；申请人指申请该API的申请人；状态指当前该API的状态，状态分为：正常使用、无数据、停用；API限制次数指应用调用该API的限制次数，“无”表示不限制调用次数，鼠标悬浮在列表中API限制次数上可查看限制次数明细。

点击授权字段可展示该API已授权的字段明细。如图2-1-19。

图2-1-19

在API管理页面列表中点击URL信息可展示调用该API的URL地址。如图2-1-20。将URL地址复制到浏览器中转到网址，可预览API数据，默认返回十条未加密的数据，可通过输入请求参数per_page调整每次请求返回的数据条数（详细调用方式请参考API文档）。注：如管理员授权时进行了字段加密，那么对应字段会返回加密后的数据。

图2-1-20

点击问题上报，可给管理员进行留言，该留言会推送给后台管理员并提示API异常。如图2-1-21。

图2-1-21

在查看应用详情页面API管理区域点击申请记录按钮可跳转到API申请记录页面，该页面汇总展示了该用户提交的所有API申请记录，页面支持通过API分类、API名称或申请时间进行筛选，申请状态中显示该申请目前的状态。如图2-1-22。

图2-1-22

在申请记录页面点击操作栏的查看按钮可查看API申请详情。如图2-1-23。

图2-1-23

（三）数据开放

为了满足不同开发者多元化的数据使用需求，平台除了API接口外还提供了数据开放的功能，可以将不同数据源的表集合在一个数据集中供开发者选用，数据开放采用直连数据库的形式实现，开发者申请数据表数据成功后，平台将提供对应数据库的链接方式供开发者使用。

点击查看应用详情页面（图2-1-4）数据开放区域的申请数据按钮可进入到数据开放申请页面，左侧可选择数据集，右侧展示了数据集中的数据表明细，勾选数据表后右上角已选择的数据表数字会相应的变化，开发者可以选取不同数据集中的数据表统一进行申请。如图2-1-24。注：数据开放采用的直连数据库的方式，如已经授权了开发者某张表的数据开放（以开发者为单位，不区分应用），则该开发者下的所有应用都无法对已经授权的数据表进行数据开放申请。

图2-1-24

如果开发者在申请数据开放的页面没有看到可供申请的数据表可能有两种情况，第一，管理员没有在数据集分类页面中添加数据集和数据表。第二，当前用户不具备使用数据表的权限，如想申请数据表进行使用，可以联系管理员把该用户加入到相应的角色组，即可浏览体验该角色组下的数据表进行申请使用。

需要申请的表勾选完毕后，开发者可点击右上角的已选择数据表按钮弹出申请列表窗口，点击删除可以移除已勾选的数据表，可以设置申请时间（永久或自定义期限），具体的有效时间以管理员审核时选择的审核时间为准，必填项填写完毕后提交申请会变成可点击状态。如图2-1-25。

图2-1-25

在数据开放申请页面点击列表中的查看详情按钮可查看数据表字段详情。如图2-1-26。

图2-1-26

在查看应用详情页面数据开放区域点击申请记录按钮，可跳转到数据开放申请记录的页面，可以查看提交的数据开放申请，列表中显示了数据开放申请的申请日期、申请结果、审批时长和使用状态（生效中/未生效）。如图2-1-27。

图2-1-27

点击操作栏的详情按钮，可以查看该条记录的申请详情。如图2-1-28。

图2-1-28

在查看申请详情页面点击授权详情区域的获取链接按钮可弹窗显示该数据库的连接方式。如图2-1-29。注：只有已授权的数据表支持获取链接和下载字典，如授权未通过，则显示为暂未授权；查看数据链接有防爬虫校验，需验证通过后方可查看链接信息。

图2-1-29

在查看申请详情页面点击授权详情区域点击下载字典可以将该数据表的数据字典下载到本地环境。

（四）数据计算（高级版）

大数据平台具有高负载和海量数据处理能力，可以基于多种类型数据源进行异构数据计算，开发者可以向平台申请数据计算，平台可以直接将数据计算后的结果以API接口或文本数据的形式提供给开发者进行使用，该功能在高级版平台中可以使用。

高级版平台开发者在查看应用详情页面点击数据计算区域的申请计算按钮可跳转到申请数据计算的页面，页面右上角的检索功能支持根据数据源/数据表/表注释进行筛选，左侧数据源区域展示平台开放数据计算的数据源列表，右侧数据表区域显示了所选数据源中包含的数据表。勾选数据表之后，右上方已选择数据表后的数字会同步变化。如图2-1-30。

图2-1-30

数据表选择完毕之后点击已选择数据表可弹窗显示申请列表窗口。如图2-1-31。

点击删除可以移除已勾选的数据表，申请时间可选择永久或自定义（具体的使用时间已管理员审核时审批时间为准），填写申请名称和申请说明后即可提交申请，提交申请后页面会自动跳转到数据计算申请记录页面。

图2-1-31

在申请计算页面点击数据表后的查看详情按钮可预览数据表中数据详情，平台会展示五条脱敏后的样例数据供开发者参考。如图2-1-32。

图2-1-32

在应用详情页面数据计算区域点击任务管理，列表可查看数据计算任务及其状态，也可以点击新建任务创建新的数据计算任务，新创建的任务为等待执行状态，需在操作栏点击提交任务，再次确认之后才可执行任务。该页面可通过右上角的检索栏输入任务名称进行快速检索。如图2-1-33。

图2-1-33

在任务管理页面点击右上方的新建任务按钮，可跳转到新建数据计算任务的页面。如图2-1-34。

新建任务页面开发者只能看到管理员已授权的数据表，右侧可选择数据表（支持通过表名进行检索），右侧可预览数据表中的数据或查看字段说明；数据计算任务可根据任务周期分为单次任务或周期任务（周期任务可自定义设置周期循环时间），可以根据开发者的实际需求进行选择。

开发者输入数据计算的SQL语句后，可点击验证SQL按钮可进行SQL语句验证，验证通过点击保存任务即创建成功。新创建的数据计算任务状态为等待提交状态。

图2-1-34

    在任务管理页面的操作栏中点击提交任务按钮可将任务提交计算，提交计算后该任务开始执行。

在任务管理页面的操作栏中点击任务详情可查看该任务的详细说明。如图2-1-35。

图2-1-35

在任务管理页面的操作栏中点击计算结果可查看该数据计算计算之后的结果和API的访问地址。如图2-1-36。

图2-1-36

    在任务管理页面的操作栏中点击删除会再次确认是否删除该数据计算任务，确认之后该任务会从列表中移除。

在查看应用详情页面数据计算区域点击申请记录，可以查看数据计算的申请列表，列表中显示了数据计算申请名称、申请日期、申请结果（已通过、待审核）、使用状态（生效中、未生效）。如图2-1-37。

图2-1-37

点击操作栏的详情按钮可查看该申请的详细信息。图2-1-38。

图2-1-38

2.1.2 文档中心

文档中心是平台提供的一系列说明类文档集合，开发者可以通过文档中心了解到如何正确的和平台进行对接以及出现问题之后错误的排查，文档中心默认展示调用类型说明页面，该页面支持通过右侧导航栏进行快速检索。如图2-1-39。

图2-1-39

API在提供数据的过程中在识别到二进制流格式字段后会自动进行加密处理，在文档中心调用类型说明页面可以下载二进制流解密示例代码，开发者可以通过该文档了解如何进行二进制流格式解密。如图2-1-40。

图2-1-40

文档中心会根据开发者常见问题预先提供相应的文档手册供开发者查询，目前已有的文档分别有：调用类型说明、授权方式、调用频率设置、错误码、调用示例，其中调用示例中Puby调用示例、python调用示例准备了配套的教学视频，开发者可以点击下载教学视频，通过教学视频学习如何调用。如图2-1-41。 

图2-1-41

2.2 用户中心

2.2.1 消息中心

消息中心汇总显示管理端向前端推送的消息合集，包括审批类消息的结果、公告类的消息、留言回复信息等，除了在用户中心可以进入外，另外一个入口是导航栏的铃铛标记，铃铛的数字提示未读消息的数量，当未读消息数量为0时，该铃铛灰色显示。如图2-2-1。在该页面点击一键已读可以将所有未读消息标记为已读状态，右上角的铃铛数字清零且灰色显示。

图2-2-1

（一）系统消息

系统消息汇总展示审核类消息的审批结果，已读消息展示为灰色，未读消息展示为黑色。操作区域支持对未读消息进行操作，点击标为已读按钮后该消息将置为已读，且导航栏的数字相应减少一位。如图2-2-2。

图2-2-2

（二）平台公告

平台公告汇总显示管理员对开发者群体推送的消息通知，新增API分类、数据分类或新增/修改API时，也会推送平台公告给开发者，开发者进入该页面后，默认将所有未读平台公告置为已读。如图2-2-3。

图2-2-3

（三）留言回复

用户在使用过程中有任何问题，都可以通过页面下端的“联系我们”给管理员留言，管理员回复的留言会在此页面显示。如图2-2-4。

图2-2-4

2.2.2 基本资料

基本资料页面显示用户的基本信息，开发者可以自行编辑除账号之外的信息。如图2-2-5。

图2-2-5

2.2.3 修改密码

修改密码页面可以修改用户的密码，如果接受不到邮箱验证码，说明该校并没有配置发送邮箱验证码的邮箱，可以与管理员取得联系，或者由管理员操作将密码修改为其他复杂密码。如图2-2-6。

图2-2-6

2.3 数据集市

   开发者可以在数据集市中根据自己的需求寻找需要的数据，数据集市中可根据数据分类：API数据集/文本数据集/计算数据集进行快捷检索，点击数据集市，开发者会进入到查看该API数据集详情页面。如图2-3-1。

图2-3-1

2.3.1 API数据集

API数据集中展示了当前开发者可申请的全部API数据集，开发者可以通过API数据集浏览到目前学校开放的所有API分类，包括分类中具体的API接口名称，该页面可以通过API名称或API分类名称进行快速筛选。鼠标悬停在API分类上可以显示该API分类的描述，点击API分类可进入到该API分类中，可查看该分类中API的明细和数据量，数据量表示当前API中数据的条目数。如图2-3-2。

图2-3-2

开发者可以通过点击API列表中的API名称查看API接口调用请求说明、请求参数说明、返回参数说明。如图2-3-3。

图2-3-3

如管理员在发布该API的时候为该API的某个或某几个字段适配了代码表，开发者可以在请求参数说明的页面预览或下载对应字段的代码表查看代码含义。如图2-3-4。

注：学校有些特殊的字段可能采用的特殊的编码写入数据库中，代码表即这些特殊字段的内容注释。如民族字段，学校储存在数据库中可能是56个数字编码，代码表则是一一注释每一个数字编码代表的民族是什么，如没有代码表，开发者则不清楚每个数字代表的是什么含义。

图2-3-4

API调用说明页面右上角可下载该API的数据字典以及查看该API的JSON返回示例。如图2-3-5。

图3-3-5

2.3.2 文本数据集

文本数据集对应查看应用详情页面-数据开放中的数据，开发者可以通过文本数据集浏览到目前学校所有开放的数据集合，包括数据集中包含的数据表数量/有数据的表数量，页面右上角可以通过数据集名称进行快速检索。如图2-3-6。

图2-3-6

点击数据集名称可以对数据集中表的数据进行预览或查看数据表的字段说明，开发者可以快速判断是否需要该数据。注：为保障学校数据安全，数据预览提供十条脱敏后的数据进行查看。

数据选取完毕后，开发者可以在查看应用详情页面-数据开放区域-申请数据，快速的申请自己需要的数据。如图2-3-7。

图2-3-7

2.3.3 计算数据集

开发者可以在数据计算集中查看学校目前已开放数据计算的数据源。如图2-3-8。

图2-3-8

点击数据计算集名称可以查看该数据计算集的详情，可以对数据进行预览（脱敏后的样例数据）以及查看字段说明。图2-3-9。

图2-3-9

2.4 全局按钮

2.4.1切换角色

平台用户可以申请成为开发者，因此部分的开发者同时具备平台用户和开发者的身份，平台登录时默认身份为平台用户，因此平台提供了快捷的身份切换方式，开发者可以点击右上角的登录账号-平台用户角色进行快速的身份切换。如图2-4-1。

图2-4-1

2.4.2退出登录

当用户在平台操作完毕需要关闭该界面的时候，可通过该功能进行注销登录，点击右上角的登录名可打开退出登录按钮。如图2-4-2。

图2-4-2

2.4.3联系我们

用户在使用平台的过程中如遇问题或有需要联系管理员的地方，可通过点击下方的联系我们按钮打开留言窗口，输入留言信息提交后会推送给后台管理员。如图2-4-3。

管理员回复的留言可在用户中心/留言回复中进行查看。

图2-4-3

2.4.4操作手册

为方便使用者了解并使用平台，平台提供快捷操作手册下载入口，点击页面左下角操作手册按钮，可将平台操作手册下载到本地，方便阅读。如图2-4-4.

图2-4-4

2.4.5API文档

为方便开发者快速了解如何和平台进行对接，平台除提供文档中心供开发者进行阅读外，平台支持将文档中心中的内容导出为PDF文档进行阅读，点击页面左下角的API文档，可将平台API文档下载到本地，方便阅读。如图2-5-5。

图2-5-5