1.API产品介绍

平台API是基于INDICS平台的面向应用开发、应用运行及设备/产品/服务接入的应用程序或函数, 旨在为企业开发者和个人开发者提供标准化、服务化和集约化的功能集合。API中心是负责对平台对外发布的API进行管理及调度, 体现了INDICS对外提供开发的能力,向合作伙伴、开发者开放服务和数据,向上提供各类工业相关应用支撑制造业全生命周期、全产业链、全要素应用开发及管理, 向下提供接口可以接入各类设备和服务,实现设备数据采集和设备运行监控,使各类应用快速开发与集成,更好的融入航天云网生态圈。

1.1 产品概述

API中心提供直观的使用API进行开发的场景及能够解决的问题,并提供清晰的API列表及开发流程, 同时,提供托管服务,涵盖API注册、发布、管理、监控和运维的全生命周期管理。 API中心为企业开发者和个人开发者提供标准化、服务化和集约化的功能接口,用户基于API可简单、快速、低成本、低风险的实现微服务聚合、前后端分离、系统集成, 向合作伙伴、开发者开放功能和数据。

1.2 功能概述

1. API中心提供总体概览,包括对注册中心上微服务的监控、整个平台API的监控。
2. API中心提供API发布功能,主要为开发者提供API发布的功能,实现API的注册、调试、监控、流量控制等功能。
3. API中心提供API发现功能,主要为开发者提供API调用的入口,开发者在可用的API里申请使用API,在获得授权后,可在应用中调用API。

1.3 产品优势

1. 用户通过API网关调用API,作为服务调用的唯一入口,极大方便API的调用者,基于API实现业务应用的快速开发与集成。
2. API中心进行集中权限认证管理,提供防攻击、防重放、请求加密、身份认证、权限管理、流量控制等多重手段保证 API 安全, API请求到达网关需要经过严格的身份认证和权限认证才能到达后端服务,降低API 开放风险。
3. 提供API全生命周期管理:覆盖 API 的定义、测试、发布的整个生命周期管理,便捷的日常管理、版本管理,支持热升级和快速回滚。
4. 提供在线页面调试功能,结果执行调试操作即可实时获取接口返回结果,并提供列表形式展示,便于请求者直观形象的获取到返回的数据结果。
5. 提供便捷、可视化的监控功能,可查看API的运行状态,便于运维人员快速了解API的运行状况和用户的行为习惯。
6. 提供请求参数管理功能,通过参数校验过滤无效请求,通过参数转换实现 API 高度复用,一套 API 多种服务。
7. 多端兼容,提供丰富的API种类。

1.4 目标群体

API中心面向的用户群体包括:

角色用户 功能说明
应用开发者 包括个人开发者和企业开发者。个人开发者可实现业务应用的快速开发与集成,共享数据和用户, 付出更少的成本来开发有价值的应用; 企业开发者可快速构建企业应用,为企业提供设备接入到智能化服务的能力,实现应用部署、监控与持续集成服务。
设备运维人员 包括设备制造商和设备集成商。设备制造商接入和管理设备, 基于数据API实现设备的可预测性维护,并对设备运行情况进行监控,提供增值服务,带来全新业务模式,加快产品创新速度;设备集成商基于数据API, 可实现集成整个产业链上不同数据结构,MES、ERP等。
数据分析人员 数据分析人员籍由开放标准的接口开发网关,连接第三方设备,基于设备接入类API快速实现数据的采集,基于数据类API实现数据处理, 以便分析和统计数据。

2.产品功能模块
2.1 功能架构
2.2 功能特点
2.2.1 API全生命周期管理

API中心提供全套的API托管服务,覆盖 API 的定义、测试、发布的整个生命周期管理,便捷的日常管理、版本管理,支持热升级和快速回滚。

2.2.2 在线页面调试及调试结果可视化

API中心提供在线调试的功能,调试界面输入API要求的参数值,执行调试操作即可实时获取接口返回结果, 并提供列表形式展示结果,便于请求者直观形象的获取到返回的数据结果。开发者使用页面调试工具可简化API开发, 降低API的开发维护成本。

2.2.3 便捷、可视化的API监控功能

API中心提供便捷、可视化的API监控功能,帮助用户深入监控API,识别可能影响业务的潜在风险。 用户可实时查看API的运行状态,并支持历史情况查询,以便统筹分析。其中,既支持对整个平台API访问量的监控, 按照访问总量,API分组访问量以及各地区对平台的访问量进行统计,也支持对单个API进行监控, 可监控调用次数与使用的网络流量。

2.2.4 请求参数管理功能(参数校验及参数转换)

API中心提供请求参数管理功能,通过参数校验过滤无效请求,通过参数转换实现 API 高度复用,一套 API 多种服务。
1. 参数校验:创建API需填写入参定义,定义您 API 的请求入参,包含参数名称、参数位置、类型、是否必填、默认值、示例、描述。 请求经过API网关,可根据您的配置进行参数类型、参数值(范围、枚举、正则、Json Schema)的校验, 减少后端对非法请求、无效请求的资源消耗和处理成本。

2. 参数转换:您可以在API网关定义参数映射规则,用户请求到达网关后,网关会根据您的后端配置映射为对应实际 后端服务的请求形式,去请求您的后端。网关通过映射规则将后端服务映射翻译成任何形式,以满足不同的用户的不同需求, 从而避免功能重复开发。

2.3 工业API种类
2.3.1 接口模型

平台API接口分为上行的工业应用接入接口层与下行的工业设备/产品/服务接入接口层,其中, 上行API接口提供各类工业相关应用支撑制造业全生命周期、全产业链、全要素应用开发及管理; 下行API接口提供可以接入各类设备和服务,实现设备数据采集和设备运行监控, 支持工业设备/产品和工业服务提供者自行接入平台,支持第三方企业开发接入产品。 平台API接口模型如下图1所示:

图1 工业互联网平台CAPI接口模型

2.3.2 上行API

▲ 模型类接口

模型类包含流程模型类和仿真模型类接口。通过该类接口可实现对流程、仿真等模型的定义、运行和监控管理, 业务系统通过调用模型类API,实现业务在流程引擎、仿真引擎中的运转过程。

▲ 数据类接口

数据类包含数据获取类、数据分析类、数据处理类和数据存储类接口。通过该类接口可实现获取并存储设备、 租户、网关和采集点信息,并对采集的数据信息进行加工,持续加强平台的数据分析处理能力。

▲ 服务类接口

服务类包含统一消息类、统一缓存类、统一搜索类、人工智能类、服务注册类、服务编排类、服务监控类和服务治理类接口。 通过该类接口可实现平台对外提供服务的能力,获取平台服务中间件以及实现对服务的管理,包括服务实例注册、实例获取、跟踪、注销、熔断、降级等。

▲ 应用管理类接口

应用管理类包含部署发布类、监控管理类、中间件接入类、持续迭代类接口。 该类接口是基于CF建立的全生命周期管理,企业开发者可基于API实现应用部署、监控与持续集成服务。

▲ 安全类接口

安全类包含身份认证类、权限管理类、访问控制类、密钥管理类和数据加解密类等接口。 通过该类接口为用户应用提供防攻击、防重放、请求加密、身份认证、权限管理、流量控制等多重安全防御功能。

2.3.3 下行API

▲ 标识类接口

标识类包含设备标识类、网关标识类和数据采集点标识类接口。通过该类接口可对设备标识类信息进行处理,实现设备的快速接入和设备数据的采集。

▲ 运行类接口

运行类包含设备状态类、设备运行类和设备能耗类接口。通过该类接口用户可对设备运行状况进行有效监控和处理,实现对设备的预测性维修和故障监控。

▲ 事件类接口

事件类包含消息事件类和报警事件类接口。通过该类接口用户可对事件类进行有效监控和处理,实现对设备的报警事件及时响应。

▲ 安全类接口

安全类包含设备认证类接口。通过该类接口为设备提供防攻击、设备认证等多重安全防御功能。

2.3.4 接口清单

平台API接口详见  http://developer.casicloud.com/index/product/api.ht

3.开发使用指南
3.1认证开发者

若您想使用INDICS平台提供的API时,需要按如下流程完成开发者认证:

步骤1.注册云网企业用户

新注册用户 : 用户登录航天云网官方网站(www.casicloud.com),在网站首页上点击【免费注册】,如下图所示:


您需要按如下页面提示完成企业用户注册,依次操作:用户注册->立即注册->成为企业用户->提交申请。 如下图所示:

已注册用户 : 若用户已有账户并且已做过企业认证,则直接输入账号密码,登录航天云网系统,跳过步骤1,直接进入步骤2。 若用户已有账户但未做过企业认证,则可输入账号密码,登录航天云网系统,进行企业认证。

步骤2.开发者认证

注册成为云网企业用户后,进入INDICS平台(网址:os.casicloud.com),如下图所示:

通过以上步骤选择开发者模块进入开发者中心主页面,点击主页上的【开发者认证】,进入开发者认证页面,如下图所示:

注意: 此操作需要使用您注册的云网帐号登录到云网系统中,在所打开的页面中只要【登录】按钮均可登录;若您未登录, 则在认证开发者时会自动跳转到统一登录界面,登录完成后,系统自动返回到认证页面。

在认证页面,按页面提示输入相应信息,完成开发者认证,如下图所示:


若您未审核通过,在进入【开发者认证】时会有未审核提示,如下图所示:

步骤3.开发者中心后台审核

开发认证完成后,初始状态是“待审核”,需要 后台管理员 审核后,开发者认证才生效,如下图所示:

步骤4.申请使用产品

开发者认证审核通过后,选择【产品服务】-->【API服务】-->【UAPI(集团外部)】,如下图所示:

进入“API中心”产品详细页面,点击页面中【申请使用】,进入开发者中心控制台,如下图所示:

开发者中心控制台界面:系统自动进入该产品的控制台,如下图所示:

注意: 此操作是从产品的角度进入开发者中心控制台,也可在登录后,直接在开发者中心首页点击【进入控制台】,再选择要使用的产品。

选择要使用的产品“API中心”,如下图所示:

3.2 发布API

认证成为开发者后,您需要依次完成以下步骤才能成功提供API服务:

步骤1.创建API分组

API 分组是 API 的管理单元,先创建API 分组,然后在分组下创建 API。 目前API分组规划整体由系统管理员负责,普通用户无法任意创建。 若您在创建API选择分组时现有分组不满足您的需求,您可以直接联系系统管理员, 由系统管理员根据您的实际需要创建/修改相应分组。

步骤2.创建API

您可以展开左侧树形【API提供者】,选中【API列表】,右侧显示下图所示信息,点击【创建API】按钮,输入信息完成API创建。

创建 API 需要录入 API 的基本信息、服务信息、请求信息、返回信息。 此外,公共服务API系统支持您配置常量参数、系统参数,这些参数对您的用户不可见, 但是API网关可以在中转时将常量参数、系统参数加入请求中,传递至后端服务, 满足您后端的一些业务需求。比如您可以将orgId定义为 系统参数 , 网关会根据用户的登录信息自动配置该参数值。API创建分为以下4步:
① 定义基本信息
API 基本信息包括 API 分组、 API 名称、是否需要登录、 API 类型、描述,如下图所示:

▲ API 创建时需要选择分组。分组是 API 的管理单元,创建 API 之前您需要先创建分组( API 分组的详细说明见 API分组创建)。
▲ API 名称:API名称标识,需要手工录入。
▲ 是否需要登录:是指使用API时是否要先登录,如一些API要用到登录人的信息或对安全有要求,则在定义API时要选择“是”。
▲ API类型:分为公有和私有
   1. 私有 类型的 API ,是指该API是内部使用,不对外开放,API调用者无法看到该API。
   2. 公开 类型的 API ,所有用户均有机会在 发现API  页面看到 API 的部分信息。 公开 类型的 API 都会跟 API 分组上架到API中心,供用户购买和调用。
▲ 描述: API 功能描述。
② 定义 API 请求
这部分是定义用户如何请求您的 API ,包括协议、Method、Path、入参的定义,如下图所示:

▲ 域名:API网关的地址。
▲ 请求路径:请求的方法名,如path1。
▲ API前缀:在请求路径中增加的API路径,如api/v1/path1,其中api即为路径中的前缀。
▲ 版本号:当前API对应的版本号,版本号会被拼接到请求路径中,如api/v1/path1,其中v1即为版本号,只需输入1即可。
▲ HTTP方法:支持标准的 HTTP Method,可选择 PUT、GET、POST、DELETE、HEAD。
▲ 入参定义:定义您 API 的请求入参,包含参数名称、参数位置、类型、是否必填、默认值、示例、描述。
    ➤ 参数名。展示给用户的参数名称。
    ➤ 参数位置。参数在请求中的位置,包含Head、Query、Body、Path(Parameter Path),
当您在 Path 中配置了动态参数,存在参数位置为Parameter Path的同名参数。
    ➤ 类型。字段的类型,支持:String、Int、Long、Float、Double、Boolean。
    ➤ 是否必填。指此参数是否为必填指,当选择为是时,网关会校验用户的请求中是否包含了此参数,若不存在则拒绝用户请求。
    ➤ 默认值。当“是否必填”为否时生效,在用户请求中不包含此参数时,网关自动添加默认值给后端服务。 若用户传递,则按用户请求传递给后端服务。
    ➤ 示例。指参数的填写示例。
    ➤ 描述。参数的用途描述及使用的注意事项。
③ 定义后端服务信息
这部分主要是定义一些参数的前后端映射,具体描述的是您后端真实服务的 API 配置。 用户请求到达网关后,网关会根据您的后端配置映射为对应实际后端服务的请求形式,去请求您的后端。 包括后端服务地址、后端Path、后端超时时间、系统参数,如下图所示:

▲ 后端服务地址。后端服务的 host,可以是一个域名,也可以是 http(s)://host:port 的形式。填写时,必须填写http://、https://
▲ 后端请求路径。Path 是您的 API 服务在您后端服务器上的请求路径,实际请求路径。若您后端 Path 需要接收动态参数,那么需要声明该参数是调用者从哪个位置哪个参数传入的,即声明映射关系。
▲ 后端服务类型:目前支持HTTP/HTTPS两种。
▲ 后端超时时间。指 API 请求到达网关后,网关去调 API 后端服务的响应时间。由网关请求后端开始到网关收到后端返回结果。
▲ 系统参数。指 API 网关的系统参数,这些参数默认不会传递给您,但是如果您需要获取,您可以在 API 里配置接收位置和名称。具体内容如下表:

注意: 所有参数在请求时输入出现一次。
④ 定义返回结果
您需要录入返回结果类型、返回结果示例、失败返回结果示例和错误码定义,如下图所示。

步骤3.调试API

您可以展开左侧树形【API提供者】,选中【API列表】,右侧显示下图所示信息。

选中一个API,点击【管理】按钮,在如下页面中,选择【API调试】,输入信息,点击【发送请求】。

步骤4.发布API

您可以展开左侧树形【API提供者】,选中【API列表】,选中一个API,点击【管理】按钮,选择【API信息】,API信息页面,选择【发布】,完成API发布。

步骤5.为调用者授权

您可以展开左侧树形【API提供者】,选中【API授权】,右侧显示待授权的调用者申请的API,选中一条数据, 点击【授权】,在弹出的窗口中输入相应信息,点击【授权】完成API授权操作。

3.3 调用API

通过 API 网关调用由其他 API 提供者开放的 API 服务,您需要依次完成以下步骤:

要调用 API 需要三个基础条件:
(1)API:您即将要调用的API,明确API参数定义。
(2)应用 app:作为您调用API时的身份,有 AppKey 和 AppSecret 用于验证您的身份。
(3)API 和 App 的权限关系:App 想调用某个 API 需要具有该 API 的权限,这个权限通过授权的功能来建立。
步骤1.创建应用APP
应用APP是您调用 API 服务时的身份。每个 APP 有一组 Key 和 Secret,您可以理解为账号密码,您调用 API 的时候需要将 AppSecret 做参数传入。
调用 API 需要这个 APP 具备调用该API的权限,这个授权和鉴权也是面向 APP 的。
您可以展开【API调用者】,选中【APP列表】,右侧显示下图所示信息,选择【创建APP】,输入信息完成APP创建。

创建成功后,系统会为 APP 分配一对 AppKey 和 AppSecret。点击【修改】可查看AppKey 和 AppSecret。
步骤2.获取API清单
您可以展开【API调用者】,选中【发现API】,右侧显示下图所示信息。

步骤3.申请使用API
您可以展开【API调用者】,选中【发现API】,右侧显示下图所示信息。点击【申请API调用】,在弹出窗口中输入调用周期。

步骤4.授权后调用API
授权成功后的API,您可以参照下面的方法来调用API。
请求地址: http://apigateway.paas.cosimcloud.com/api/v1/getAllOrgs(要调用的API地址)
方法:POST
请求体:appsecret=123456789&apisecret=JFKLDAFIJFDLSAJFD393K这两个值是您创建APP及申请API时获取的。
               HttpClient httpClient = buildHttpClient(false);
               // post请求
               HttpPost method = new HttpPost(url);
               // 执行响应操作
               HttpResponse result = httpClient.execute(method);
               String data= EntityUtils.toString(result.getEntity());

4.用户解决方案
4.1客户价值
4.1.1 开放能力、服务和数据

为融入航天云网生态圈的企业开发者和个人开发者提供标准化、服务化和集约化的功能接口(Open API),开放平台的能力、服务和数据,共建生态。

4.1.2 快速构建企业应用

企业开发者基于INDICS云平台提供的API,可快速构建企业应用,降低成本,提升效率,解放生产力。

4.1.3 提供工业智能制造解决方案

提供设备接入到智能化服务的能力,为高端装备智能制造行业、能源行业、机器人行业及智慧企业提供解决方案。

4.1.4 方便运维和全面监控

基于CF建立的全生命周期管理,为开发者提供基于API的应用部署、监控与持续集成服务,方便运维和监控,可及时发现报警并快速定位问题。

4.2解决方案
4.2.1 基于INDICS APIs工业应用开发


面向全球应用开发者,包括个人开发者和企业开发者,注册成为平台开发者后便可申请API,授权通过后便可调用。具有以下特色:
▲ 提供各类工业相关应用支撑制造业全生命周期、全产业链、全要素应用开发及管理,目前API中心已对外提供100多个API,包括数据类、模型类、服务类和应用管理类API等;
▲ 用户可根据业务灵活、快速开发APP,开放性和灵活性良好,可基于应用管理类API可实现应用的全生命周期管理。

4.2.2 基于INDICS APIs工业应用部署


面向全球应用开发者,提供应用云端部署运行环境和工具,具有以下特色:
▲ 用户基于应用管理类接口可实心工业应用的快速部署和持续迭代,实现应用发布、测试、部署、销毁的全生命周期管理,并支持绑定中间件和对应用运行情况进行监控;
▲ 通过INDICS云平台安全产品保障运行环境和应用安全。

4.2.3 基于INDICS APIs设备接入、数据采集、处理及存储


面向工业应用开发者和终端用户,提供基于大数据分析和人工智能决策的工业大数据服务,具有以下特色:
▲ 设备服务商可基于设备接入类API快速实现数据的采集,基于数据API实现设备的预测性维护;
▲ 提供基于人工智能的解决方案,提升效率、减低成本、提升产值;
▲ 提供设备实时工况监控、实时故障报警、OEE分析等智能服务;
▲ 提供PB级别大数据存储。