中国电信集团公司技术标准
Q/CT XXXX.01-2012
能力开放合作管理平台(EMP一期) 技术规范分册——能力接口规范
v1.0
2012- 2 -XX 发布
2012-XX -XX实施
中国电信集团公司 发布
目 录
1 2 3 4
适用范围 ................................................................................................................ 5 规范性引用文档 .................................................................................................... 6 术语定义 ................................................................................................................ 7 EMP能力开放接口概述....................................................................................... 8
4.1 EMP基本架构方案 ......................................................................................................... 8 4.2 EMP能力接口访问模式 ................................................................................................. 9
4.2.1 HTTP协议 ........................................................................................................... 10
4.2.1.1 重定向访问模式 ....................................................................................... 10 4.2.1.2 代理访问模式 ........................................................................................... 11 4.2.2 HTTPS协议 ........................................................................................................ 12
4.2.2.1 重定向访问模式 ....................................................................................... 12 4.2.2.2 代理访问模式 ........................................................................................... 12
5 EMP能力开放接口规范..................................................................................... 13
5.1 接口风格 ........................................................................................................................ 13 5.2 接口承载协议 ................................................................................................................ 14 5.3 接口资源操作 ................................................................................................................ 14 5.4 接口参数编码 ................................................................................................................ 14 5.5 参数传递方式 ................................................................................................................ 14 5.6 接口请求系统参数 ........................................................................................................ 15 5.7 接口请求业务参数 ........................................................................................................ 16 5.8 返回数据格式 ................................................................................................................ 16 5.9 接口返回系统参数 ........................................................................................................ 17 5.10 接口返回业务参数 ........................................................................................................ 17 5.11 其他注意事项 ................................................................................................................ 18
5.11.1 能力平台侧接口地址 .......................................................................................... 18 5.11.2 接口调用运行时异常 .......................................................................................... 18
6 EMP数据编码规范............................................................................................. 19
6.1 接口返回码定义 ............................................................................................................ 19 6.2 预定义返回码 ................................................................................................................ 19
内部资料，注意保密，未经同意，请勿翻印 版本：v1.0
文档信息
文档名称 EMP技术规范分册——能力接口规范 文件编号 编制人 保密级别
修改过程 版本号 2011-10 2011-11 2011-12 2012-1 2012-1 2012-2 日期 0.1 0.3 0.4 0.5 0.6 1.0 负责人 王大中 王大中 王大中 王大中 王大中 王大中 接口规范初稿 接口参数更新 概述 补充HTTP和HTTPS两种接口调用方式的说明 补充缓冲重定向机制说明 补充接口调用参数传递方式的说明 补充接口返回参数说明
评审过程
版本号 日期 评审者 概述
分发范围
前 言
中国电信能力开放合作管理平台主要面向以开发者为主体的互联网合作伙伴，提供一站式、标准化的能力合作管理服务。合作伙伴在平台注册签约后，可使用平台提供的开放能力接口进行合作应用开发。
能力开放合作管理平台同时为以天翼帐号用户为主体的合作应用使用者提供能力授权服务。通过该服务，登录合作应用的用户可为合作应用授权，以允许合作应用通过开放能力接口调用，访问或使用与用户相关的信息或开放功能。
能力开放合作管理平台还提供集约化、标准化的互联网式能力接口注册登记、开放接口调用统计分析等集约化能力管控功能。各基地业务平台、专业公司平台均可作为能力提供平台，将封装好的开放API注册到能力开放合作管理平台，实现面向合作伙伴的规模化能力服务提供。
本规范由中国电信集团公司创新业务事业部组织制定和颁布，集团公司具有对本业务规范的解释权和修订权，如与此前颁布相关规范或规定有冲突，以本规范为准。
本规范起草单位：中国电信股份有限公司上海研究院
1 适用范围
本规范适用于中国电信能力开放合作管理平台的建设与部署，是中国电信能力开放合作管理平台招标采购、工程设计、网络运营、维护管理等方面的技术依据，并可作为设备提供商和集成商能力开放合作管理平台系统设计、设备开发的技术依据。
纳入EMP平台管理的能力提供方须依据本规范进行能力接口开发，以保证各能力提供方所提供的能力以统一形式提供给EMP合作开发者使用。
2 规范性引用文档
下列标准所包含的条文，通过在本标准中引用而构成为本标准的条文。本标准出版时，所示版本均为有效。使用本标准的各方应探讨使用下列标准最新版本的可能性。
【1】《中国电信能力开放合作管理平台－业务规范》 【2】《中国电信能力开放合作管理平台－技术规范总册》 【3】《中国电信用户数据库－接口与流程规范v2.0》
3 术语定义
名 称 能力开放合作管理平台 能力提供方 能力提供平台 合作应用 合作应用用户 App ID App Secret 能力 能力接口 描 述 Enabler Management Platform，简称EMP平台，负责能力接口的合作与管控 Enabler Provider，简称Enabler，对外提供接口调用，使第三方能够利用接口调用其特有功能的企业或单位 Enabler Platform，简称EP或能力平台，由Enabler建设的能力平台，负责能力功能的具体实现 简称App，签约合作伙伴在EMP平台上创建的合作应用 简称用户，合作伙伴应用(App)的使用者 EMP平台为特定版本的App分配的唯一标识序列号 EMP平台为特定版本的App分配的共享密钥，用于认证其身份 由Enabler指定的一组可调用功能的集合 由Enabler定义的一组可调用功能接口的集合，即一组API接口的集合，一个能力接口可对应多个具体的能力实现 开放用户授权协议v2.0，用于使获取过用户授权的应用可以在无需用户名和用户密码的条件下访问用户相关的私有资源 用户对于合作应用能否通过开放能力接口调用、使用其私有在线信息或资源的许可 简称Token，合作应用可对开放能力接口进行合法调用的凭访问令牌 据；合作伙伴应用在调用开放能力接口之前须出示令牌并通过鉴权。访问令牌由由EMP集中颁发、统一管理，由各Enabler负责分布式鉴权。 UDB NSAG/ISAG
中国电信用户数据库 全国/综合业务接入网关 OAuth v2.0 用户授权
4 EMP能力开放接口概述
4.1 EMP基本架构方案
中小企业开发者个人开发者最终用户运营商开放能力管理者能力开放合作管理平台（EMP）合作管理信息同步用户能力授权能力调用统计上报UPC基地/专业公司UDBEnablersEnablersEnablersEnablers管理平台NMSC/ISMP能力平台NSAG/ISAG位置平台等 ? 全国中心UDB：UDB作为认证网元，为EMP平台提供天翼帐号用户认证功能。 ? 综合管理平台（NMSC/ISMP/NSAG）：EMP平台视其为各电信能力综合管理及基础电
信能力提供平台，为各Enabler平台提供综合电信基础能力管控及策略配置服务。EMP一期暂不直接对接NMSC/ISMP/NSAG。
? 各垂直/横向能力提供平台（基地、支付、POI、领航平台等）：EMP平台将向各Enabler
平台同步能力签约、能力授权信息，并由其自行负责能力的鉴权。同时，EMP平台还将从各Enabler平台接受能力调用统计信息，以进行汇总分析。EMP平台与Enabler平台之间将会涉及到部分接口适配改造，以实现二者的对接，从而实现集中签约、授权。EMP一期暂不直接对接领航平台。
4.2 EMP能力接口访问模式
EMP合作应用(APP)能力调用能力开放合作管理平台（EMP）能力调用路由分发能力提供平台（Enabler)
应用调用EMP对外统一提供的能力接口，EMP根据能力注册信息，使用相应策略将应用的能力接口调用请求路由分发至各Enabler的接口网关，完成能力调用。
EMP支持重定向访问模式及代理访问模式等两种接口调用请求路由分发机制，且这两种机制均同时支持HTTP和HTTPS调用方式。
能力接口具体采用何种访问模式，由EMP平台运营方根据接口管控的需求决定。EMP平台运营方可随时切换具体能力接口的访问模式，以满足能力管控需要。
原则上，具体能力接口的访问模式对于EMP合作应用及能力平台保持透明。即，合作应用对于能力接口所采用的具体访问模式是无感知的；同时，各能力平台对于EMP所指定的能力接口所采用的具体访问模式也是无感知的。因此，各能力平台须充分保障自身开放能力调用的HTTP端对端特性，其内部实现机制宜避免依赖于合作应用与自身能力接入网关之间的任何网络拓扑假设。
4.2.1 HTTP协议 4.2.1.1 重定向访问模式
应用1、应用调用能力请求时,浏览器/控件检查本地是否存在重定向缓存响应,若缓存已存在，则转第4步2、调用EMP发布的能力接口3、返回重定向响应(HTTP 307临时重定向)，并设定缓存有效期，将应用重定向至能力接口实际地址E M P能力平台4、调用能力接口实际地址5、返回调用结果
重定向访问模式下能力接口调用流程：
1. 应用调用能力请求时，检查本地HTTP缓存中是否已存在重定向缓冲响应，若缓存
存在，则直接读取本地缓冲的重定向响应，获悉其中的EP侧真实网关接口地址，转第4步
2. 应用使用标准化的开放能力接口地址，面向EMP发起能力调用请求
3. EMP收到接口调用请求，判断其接口的当前访问模式为重定向模式，继而向应用
返回HTTP 307应答（临时重定向），指向EP侧能力接口的实际地址，该307应答消息的头部需携带HTTP缓冲首部，以指明307重定向的有效期 4. 应用在重定向的引导下，向能力接口实际地址再次发起能力接口调用请求 5. 能力平台向应用返回接口调用结果
能力平台在注册上挂能力接口时，需登记自身实际的能力接口网关的互联网地址，以便EMP平台将标准格式的开放能力接口调用（如http://api.189.cn/iMusic/Album/getInfo）转换成为实际的EP侧能力接口网关地址调用（如http://www.118110.cn:8091/Album/getInfo）。
当应用向EMP发起接口调用请求时，EMP将首先根据管理策略，判断其API调用是否属于重定向模式，如果是，则EMP向应用应答HTTP 307重定向消息，将其临时重定向至能力平台侧接口网关地址，并设置该重定向响应的缓存有效期（如60秒）。该有效期的取值将由EMP平台根据负载情况动态配置。
在重定向响应的本地缓存有效期内，应用将通过本地缓存直接将请求重定向至能力平台，而无需由经EMP平台再次重定向，以保障接口调用性能；缓存失效后（如HTTP缓存被清空或缓存已过有效期），应用的调用请求将再次被发送到EMP平台，并在后者重定向响应的指引下，访问能力平台实际接口。 4.2.1.2 代理访问模式
应用1、调用EMP发布的能力接口E M P能力平台2、EMP转发应用调用请求3、能力平台向EMP返回调用结果4、EMP向应用返回调用结果
代理访问模式下能力接口调用流程： 1. 应用发起能力调用请求
2. EMP收到接口调用请求，根据管理策略配置，判断其接口的当前访问模式为代理
模式，继而向能力平台代理转发接口调用请求 3. 能力平台向EMP返回接口调用结果 4. 能力平台向应用返回接口调用结果
根据开放能力接口管控需要，EMP平台运营方将有可能随时切换具体能力接口的访问模式。因此，原则上，能力平台的开放能力接口实现宜严格遵循HTTP接口调用的端对端原
则，不应依赖于任何基于具体开放能力接口调用方式的假设。 4.2.2 HTTPS协议 4.2.2.1 重定向访问模式
该模式下的调用流程与 4.2.1.1 章节所述流程一致。在该模式下，EMP、能力平台均向应用提供HTTPS接口访问服务。
能力平台提供的接口支持该模式时，需要向EMP提供能力接口的EP侧实际地址；同时，能力平台所使用的SSL证书建议与EMP平台保持一致，从而避免合作应用或最终用户侧需要确认多次安全风险警告的情况，从而最大限度地保障用户体验。 4.2.2.2 代理访问模式
该模式下的调用流程与 4.2.1.2 章节所述流程一致。在该模式下，由EMP向应用提供HTTPS接口访问服务，同时由能力平台向EMP平台提供HTTPS接口访问服务。
与 4.2.1.2 章节中的HTTP场景类似的，原则上，开放能力接口的对应实现宜严格遵循HTTPS的端对端原则，不应依赖于任何基于具体开放能力接口调用方式的假设。
5 EMP能力开放接口规范
5.1 接口风格
EMP对外能力开放接口采用HTTP/HTTPS标准协议形式，并且遵循互联网业界通行的REST接口设计风格（Representational State Transfer，表征状态转移）。
REST是一种接口设计风格，而非某一具体的协议标准。REST接口设计风格主张采用HTTP、URI、XML以及HTML等互联网通行的标准协议。其同时主张从资源的角度来观察整个互联网，分布在互联网个各处的资源由URI唯一确定，而客户端的应用则通过URI来获取资源的表征。应用对资源的获取和修改将使得自身状态发生连续、有序的迁徙。
REST接口设计风格具有以下基本特点： ? ?
一项资源是由一个URI来唯一引用，二者是一一对应的关系
对资源的操作包括获取、创建、修改和删除等四类操作，其对应着HTTP协议提供的GET、POST、PUT和DELETE等四种方法 ?
以XML或者JSON作为资源的描述形式
在REST基本风格的基础上，建议接入EMP的能力平台采用如下2种API命名风格： 1. 严格的RESTful接口风格
http(s)://api.189.cn/Enabler标识/API分类1/API分类2/资源名(名词，宾语) 例如：音乐基地的唱片内容信息接口 http://api.189.cn/iMusic/ActorAlbum 调用范例：获取id为3的唱片所对应的信息
HTTP GET Method：http://api.189.cn/ iMusic/ActorAlbum?id=3
2. 宽泛的RESTful接口风格
http(s)://api.189.cn/Enabler标识/API分类1/API分类2/API名称(动词，动宾结构) 例如：音乐基地的唱片内容信息接口 http://api.189.cn/iMusic/ActorAlbum/getInfo 调用范例：获取id为3的唱片所对应的信息
HTTP GET Method：http://api.189.cn/ iMusic/ActorAlbum/getInfo?id=3
5.2 接口承载协议
在一般情况下，建议能力平台所提供的开放能力接口必须支持HTTP协议访问方式，可选支持HTTPS接口访问方式。
在安全性要求较高的情况下，特别是涉及到授权、计扣费、用户敏感信息等相关接口时，可以仅支持HTTPS访问方式，以保证接口调用传输的安全性。
采用HTTPS代理访问模式时，由EMP对外提供HTTPS接口访问服务，同时能力平台亦须向EMP提供HTTPS接口访问服务。
5.3 接口资源操作
对于资源读取等的幂等操作，建议采用HTTP标准协议中的GET方法。
对于资源新增、修改、删除等非幂等操作，建议采用HTTP标准协议中的POST方法。
5.4 接口参数编码
对于接口的输入、返回参数，统一采取UTF-8编码。
5.5 参数传递方式
接口调用请求参数可采用如下三种具体传递方式。其中，方式A与方式B是目前最为常见的两种HTTP/REST参数传递方式。
A. 通过URI参数形式传递给能力平台 B. 通过POST form形式传递给能力平台 C. 通过HTTP header形式传递给能力平台
方式A利用URI传递请求参数，其有助于提高开放能力接口对开发者调用、调试的友好性，但并不适合传递较多、较长的参数，因此建议仅在开放API接口相对简单的情况下使用。
方式B使用POST form表单形式传递参数，其最大优点在于对于请求参数的数量和长度没有限制，可用于传递复杂参数，但与方式A相比，其接口调用的过程略显繁琐。
方式C借助于HTTP首部扩展机制来传递参数，在一般的接口调用场合下，其较方式A、B相对少见，同时在协议兼容性和参数定义方面也存在一定的限制，不及方式A、B易于扩展，因此在开放系统环境下宜避免过度使用。
在参数传递过程中，对于某些安全性要求较高的特定API调用场合而言（例如认证授权接口、支付接口等），应当考虑采用HTTPS机制，以保障其端对端传输的安全性。HTTPS协议对于上述三种方式的HTTP传输负载均能给予充分保护。但值得指出的是，由于方式A采用URI明文进行参数编码，即便是在使用HTTPS协议的前提下，其在客户端侧依然存在着一定的安全隐患（如客户端存在URL缓冲或历史记录、从而导致参数泄露等），因此建议在安全性要求较高的场合下，优先选择方式B进行参数传递。
原则上，接口参数的具体传递方式可由能力提供方自行指定。一般而言，建议遵循业界接口惯例，在HTTP GET等幂等操作的接口场合下，使用方式A传递参数；在HTTP POST等非幂等操作的API调用场合下，优选方式B进行参数传递。对于同一开放接口，不建议混合使用不同的参数传递方式。
以URI形式传递参数的开放API接口调用范例如下：
http://api.189.cn/iMusic/ActorAlbum/getInfo? access_token= XXXX&sign=YYYY 以POST form表单形式传递参数的开放API接口调用范例如下。对于多表单场合或者是既需传递参数又需同时上传数据的参数传递场合，统一采用multipart/form-data编码方式。
POST /iMusic/ActorAlbum/setInfo HTTP/1.1
Host:www.testapp.com
Content-Type:application/x-www-form-urlencoded; charset=UTF-8
access_token= XXXX&sign=YYYY&info=”INFORMATION” 以HTTP header首部形式传递参数的开放API接口调用范例如下：
GET /iMusic/ActorAlbum/getInfo HTTP/1.1 Host:www.testapp.com
Content-Type:application/json;charset=UTF-8 access_token: XXXX sign: YYYY
5.6 接口请求系统参数
合作应用在调用任一EMP开放API接口时，均须携带以下公共系统参数：
参数名 access_token app_id format timestamp cacheable 必选 true false false false false 类型 string string string string string 说 明 完成应用-用户-能力授权的令牌 应用注册时分配的应用ID 指定响应格式，可选JSON或XML，默认为JSON 请求时间戳。以提升安全性，用于防止replay等攻击。 cacheable参数仅用于重定向访问模式。默认取值为true。 cacheable为true时，EMP重定向响应将包括HTTP缓冲
首部，在缓存有效期内，应用可使用本地缓存的重定向响应，直接访问EP侧接口，而无需EMP介入调用请求过程。cacheable为false时，将强制EMP重定向响应不包括HTTP缓冲首部，应用的每次请求均将由经EMP重定向至实际的EP侧调用接口。 state false string 用于区分应用请求-响应的对应关系。 若应用发起的调用请求中包含该参数，则EP将在应答响应中加上原封不动地加上该参数，以表示请求与响应之间的对应关系。 sign false string APP_ID+ACCESSS_TOKEN+TIMESTAMP(如果存在)+STATE(如果存在)+APP_SECRET组成的字符串进行MD5散列所得到的取值。建议应用在调用HTTP接口调用时携带该参数，以增强安全性，防止调用参数被篡改。 5.7 接口请求业务参数
接口业务参数主要指除EMP公共系统参数之外的其他接口调用参数，可由能力平台所提供的开放API自行指定。
5.8 返回数据格式
接口返回的格式统一为JSON或XML。建议以轻量级的JSON格式为默认首选格式，或者是同时支持两种数据格式。
接口返回参数由包括系统返回参数与业务返回参数两部分组成。其中，所有开放API接口的数据返回均须包含系统返回参数，系统返回参数的定义详见 5.1.9 节。业务返回参数则可由各能力提供方在具体API中自行定义。
JSON数据格式返回范例如下：
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {
“res_code”:0,
“res_message”:”成功”,
\ \}
XML数据格式返回范例如下： HTTP/1.1 200 OK
Content-Type: application/xml;charset=UTF-8 Cache-Control: no-store Pragma: no-cache
5.9 接口返回系统参数
接口返回系统参数指各开放API接口均必须返回的公共参数。其定义如下：
参数名 res_code res_message 类型 unsigned int string 说 明 接口返回码。具体返回码含义详见6.1节。 如果错误，返回错误信息，详见6.1节定义，建议返回英文信息。
5.10 接口返回业务参数
接口返回业务参数指除系统返回参数之外的其他返回参数，取决于各开放API接口的具体定义，由能力提供方自行指定。
对于某些以资源获取为目的的开放API接口（如获取图片、音乐、电子书籍等），建议在接口返回业务参数中返回该资源在专用下载服务器中的url，由合作应用另行下载，而不是直接返回资源二进制数据流，以提高开放接口调用效率，同时减轻代理访问模式下EMP系统的数据传输负载。其典型范例如下：
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {
“res_code”:0,
“res_message”:”成功”,
\ \}
5.11 其他注意事项
5.11.1 能力平台侧接口地址
能力平台在注册上挂能力接口时，需登记自身实际的能力接口网关的互联网地址，以便EMP平台将标准格式的开放能力接口调用（如http://api.189.cn/iMusic/getMusicInfo）转换成为实际的EP侧能力接口网关地址调用（如http://api.118110.cn/getMusicInfo）。
EP侧能力接口网关地址一经登记，除非相关能力接口全部下线，否则不可更改。因此，建议能力提供方在登记自身实际的能力接口网关地址时采用域名形式，而非IP地址形式，以保持EP侧能力接口网关地址的稳定性，在满足能力提供方自身部署调整的需求的同时，保障EMP接口调用不会受到能力平台网关部署调整的影响。 5.11.2 接口调用运行时异常
合作应用在接口调用的过程中，有可能会碰到授权令牌运行时失效、从而导致开放API接口调用失败的情况。合作应用开发者须在编码过程中自行添加适当的防卫代码，以捕捉此类运行时异常，在确认授权令牌失效的情况下，使用刷新令牌重新获取授权令牌，或调用接口重新获取授权令牌。
6 EMP数据编码规范
6.1 接口返回码定义
接口返回码共10位用于向开发者返回系统信息。编号规则如下：
N0 N1 N2 N3 N4 N5 N6 N7 N8 N9 ? N0保留，现取值为0
? N1代表能力提供方来源分类标志位，0为电信自有能力；1为第三方能力； ? N2~N5序列号用于标识能力提供方，其中，通用系统的标识为：0000；EMP系统
的标识为：0001；
? N6~N9序列号用于标识能力提供方自定义的返回码，其中0表示成功。 前导“0”可以省略不写，当N1~N9均为0时，只填写一个“0”。
6.2 预定义返回码
预定义返回码即通用系统返回码，其N2-N5位为0000，如下表所示。其主要用于描述非专属于特定能力提供者的共性接口返回情况。若能力提供方自定义的接口返回码与预留的通用系统返回码语义相同，建议直接使用通用系统返回码。
返回码 0 1 2 3 4 5 6 7 100 101 104 105 106 107 109 110 111 成功 错误描述（中文） 未知错误 服务暂不可用 未知的方法 接口调用次数已达到设定的上限 请求来自未经授权的IP地址 无权限访问该用户数据 来自该refer的请求无访问权限 请求参数无效 api key无效 无效签名 请求参数过多 未知的签名方法 timestamp参数无效 无效的用户资料字段名 无效的access token access token过期 Error Description (English) Success Unknown error Service temporarily unavailable Unsupported openapi method Open api request limit reached Unauthorized client IP address No permission to access user data No permission to access data for this referer Invalid parameter Invalid API key Incorrect signature Too many parameters Unsupported signature method Invalid/Used timestamp parameter Invalid user info field Access token invalid or no longer valid Access token expired
210 211 212 800 801 802 803 804 805 900 用户不可见 获取未授权的字段 没有权限获取用户的email 未知的存储操作错误 无效的操作方法 数据存储空间已超过设定的上限 指定的对象不存在 指定的对象已存在 数据库操作出错，请重试 访问的应用不存在 User not visible Unsupported permission No permission to access user email Unknown data store API error Invalid operation Data store allowable quota was exceeded Specified object cannot be found Specified object already exists A database error occurred. Please try again No such application exists