联通WO+开放平台提供者指南—API策略介绍.doc

联通WO+开放平台提供者指南（1）API策略介绍目录：1、 流量控制策略1.1、速率控制2、 安全控制策略2.1、IP接入控制2.2、Token认证2.3、开发者身份认证3、 数据映射3.1、XMLtoXML3.2、XMLtoSOAP3.3、SOAPtoXML3.4、SOAPtoSOAP4、 脚本增强4.1、MVEL4.2、XSLT1、流量控制策略1.1、速率控制使用场景此策略控制API的全局并发调用速率。指调用部署在商用环境的API所有请求速率之和不能超过此处配置的值。并发请求数超限时，超过的请求将被拒绝并返回错误响应。此策略可用于保护后端API服务器免受大数据量冲击，能力提供者可以根据后端API服务器性能调整来修改策略中的配置值。配置说明在流程编排图中单击此策略图标，并参考表1配置速率控制策略。表1参数说明参数说明TPS您可以配置10至500的TPS值。说明：此策略默认值为100TPS。即如果您不配置此策略，WO+能力共享平台按100TPS控制商用环境API请求速率。2、安全控制策略2.1、IP接入控制使用场景此策略通过配置IP地址白名单或IP地址黑名单的方式对所有的API调用请求进行鉴权，允许来自IP白名单中的访问请求接入系统，或拒绝来自IP黑名单中的访问。您可以通过配置此策略提升安全性。例如在发现网络攻击后，可以通过配置此策略拒绝来自攻击地址的API调用请求。或者开发API时配置IP白名单，仅允许来自IP白名单的请求消息接入。配置说明将IP接入控制策略图标拖拽至流程编排图中，并根据表1配置IP接入控制策略。表1IP策略配置示例场景填写说明仅允许单个IP如0的IP访问API。“允许访问的IP地址”填写为允许访问的IP地址，子网掩码设为“55”。仅拒绝某段地址如10.10.10.*的所有地址访问API。“拒绝访问的IP地址”填写为拒绝访问的IP地址，子网掩码设为“”。2.2、Token认证使用场景此策略表示开发者调用API时，首先需要调用WO+能力共享平台提供的获取Token接口来获取“Token”。开发者应用调用业务接口时携带已获取的“Token”信息，WO+能力共享平台对“Token”进行鉴权认证。认证通过后WO+能力共享平台处理开发者应用的接口请求，认证失败则拒绝处理开发者应用的接口请求。配置说明您只需将Token认证策略图标拖拽到流程编排图中，无需为此策略配置任何参数。2.3、开发者身份认证使用场景此策略表示开发者调用API时，需提供“UserID+API调用密码”用于身份认证，认证通过后才处理开发者应用的接口请求，认证失败则拒绝处理开发者应用的接口请求。配置说明您只需将开发者身份认证策略图标拖拽到流程编排图中，无需为此策略配置任何参数。3、数据映射3.1、XMLtoXMLXMLtoXML策略是WO+能力共享平台提供的一种将App发送的HTTP+XML格式的请求消息转换为另外一种HTTP+XML格式消息的控制策略。能力提供者无需编码，只需要应用该策略即可快速实现XML格式消息之间的字段转换、映射、屏蔽。实现原理XMLtoXML策略的实现原理如图1所示。图1实现原理使用场景能力提供者无需编码，通过拖拽额策略即可实现XML格式消息之间的字段转换、映射、屏蔽等。此策略可以应用于如图2所示的几种场景。图2使用场景配置说明在配置此策略前，能力提供者需要准备好XML消息定义文件。WO+能力共享平台支持的XML消息定义文件后缀名为“.xsd”。完成消息文件的定义后，能力提供者可以将图标拖拽至策略编排流程图中并按照界面提示进行操作即可。3.2、XMLtoSOAPXMLtoSOAP数据映射是WO+能力共享平台提供的一种将App发送的HTTP+XML格式消息转换为SOAP格式消息的控制策略。能力提供者无需编码，只需应用该策略即可快速实现对API的接口字段映射、屏蔽和消息格式转换。此策略通常和SOAPtoXML策略配合使用，例如发送请求消息时配置XMLtoSOAP策略将请求消息从XML转换为SOAP，则同时需要配置SOAPtoXML策略将响应消息从SOAP转换为XML格式。实现原理XMLtoSOAP策略的实现原理如图1所示。图1实现原理使用场景能力提供者无需编码，通过拖拽额策略即可实现XML格式消息到SOAP格式消息之间的字段转换、映射、屏蔽等。此策略可以应用于如图2所示的几种场景。图2使用场景配置说明在配置此策略前，能力提供者需要准备好XML消息定义文件和SOAP消息定义文件。WO+能力共享平台支持的XML消息定义文件后缀名为“.xsd”，SOAP消息定义文件后缀名为“.wsdl”或“.xsd”。完成消息文件的定义后，能力提供者可以将图标拖拽至策略编排流程图中并按照界面提示进行操作即可。3.3、SOAPtoXML后端API消息格式和希望开放给开发者的消息协议不符合时，能力提供者可通过配置SOAPtoXML策略实现XML格式消息和SOAP格式消息之间的字段转换、映射、屏蔽，无需编码实现，提升了开发效率。此策略通常和XMLtoSOAP策略配合使用，例如发送请求消息时配置SOAPtoXML策略将请求消息从XML转换为SOAP，则同时需要配置XMLtoSOAP策略将响应消息从SOAP转换为XML格式。配置说明请参见XMLtoSOAP。3.4、SOAPtoSOAPSOAPtoSOAP策略是WO+能力共享平台提供的一种将App发送的SOAP格式的请求消息转换为另外一种SOAP格式消息的控制策略。能力提供者无需编码，只需要应用该策略即可快速实现SOAP格式消息之间的字段转换、映射、屏蔽。实现原理SOAPtoSOAP策略的实现原理如图1所示。图1实现原理使用场景能力提供者无需编码，通过拖拽额策略即可实现SOAP格式消息之间的字段转换、映射、屏蔽等。此策略可以应用于如图2中所述的几种场景。图2使用场景配置说明在配置此策略前，能力提供者需要准备好SOAP消息定义文件。WO+能力共享平台支持的SOAP消息定义文件后缀名为“.wsdl”或“.xsd”。完成消息文件的定义后，能力提供者可以将图标拖拽至策略编排流程图中并按照界面提示进行操作即可。4、 脚本增强4.1、MVELMVEL是一种强大的脚本编辑语言，当WO+能力共享平台预置API策略无法满足需求时，能力提供者开发者可以上传MVEL脚本为API自定义控制功能。WO+能力共享平台可以校验您输入的MVEL脚本语法是否正确，但是不会处理死循环等逻辑错误。您可以访问MVEL官网地址/了解更多。注意：MVEL脚本处理消息体时会替换消息体中的全部字段。若希望只替换某一个字段，请使用数据映射策略或者XSLT脚本策略。WO+能力共享平台支持的MVEL对象详解WO+能力共享平台支持的MVEL对象及其属性如表1所示。表1MVEL对象及其属性对象属性说明inHttpRequest：指开发者发送给WO+能力共享平台的请求消息对象。outHttpRequest：指WO+能力共享平台发送给能力提供者的请求消息对象。httpMethodHTTP请求方法，包括Get、Put、Post、Delete。httpUrlHTTP请求消息中的URL地址。httpQueryParamsHTTP请求参数字符串。httpHeadHTTP消息头。httpBodyHTTP消息体。OutHttpResponse：指WO+能力共享平台返回给能力提供者的响应消息对象。inHttpResponse：指WO+能力共享平台返回给开发者的响应消息对象。httpHeadHTTP消息头。httpBodyHTTP消息体。httpRspCodeHTTP返回码。httpRspReasonHTTP返回码说明。inHttpRequest和outHttpRequest对象支持的方法如表2所示。表2inHttpRequest和outHttpRequest对象支持的方法方法类型说明操作属性MVEL代码示例public String获取HTTP请求方法。httpmethodinHttpRequest.httpmethod;public void设置HTTP请求方法。httpmethodinHttpRequest.httpmethod =PUT;public String获取HTTP URL。httpUrlinHttpRequest.httpUrl;public void设置HTTP URL。httpUrlinHttpRequest.httpUrl =/test/url;public MapString, List获取HTTP请求字符串。httpQueryParamsinHttpRequest.httpQueryParamstestkey0;public void设置HTTP请求字符串。httpQueryParams增加：inHttpRequest.httpQueryParams.put(testkey, testvalue1, testvalue2);删除：inHttpRequest.httpQueryParams.remove(testkey);修改：inHttpRequest.httpQueryParamstestkey = testvalue1, testvalue2;public Map获取HTTP消息头。httpHeadinHttpRequest.httpHeadtestkey;public void设置HTTP消息头。httpHead增加：inHttpRequest.httpHead.put(testkey, testvalue1);删除：inHttpRequest.httpHead.remove(testkey);修改：inHttpRequest.httpHeadtestkey = testvalue2;public byte获取HTTP消息体。httpBodyinHttpRequest.httpBody;public void设置HTTP消息体。httpBodyinHttpRequest.httpBody = testdata.getBytes(UTF-8);inHttpResponse和outHttpResponse对象支持的方法如表3所示。表3inHttpResponse和outHttpResponse对象支持的方法方法类型说明操作属性MVEL代码示例public String获取HTTP返回码。httpRspCodeinHttpResponse.httpRspCode;public void设置HTTP返回码。httpRspCodeinHttpResponse.httpRspCode =201;public String获取HTTP返回码说明。httpRspReasoninHttpResponse.httpRspReason;public void设置HTTP返回码说明。httpRspReasoninHttpResponse.httpRspReason =OK;public Map获取HTTP消息头。httpHeadinHttpResponse.httpHeadtesthead1;public void设置HTTP消息头。httpHead增加： inHttpResponse.httpHead.put(testhead1, testvalue1);删除： inHttpResponse.httpHead.remove(testkey1);修改： inHttpResponse.httpHeadtestkey1=testvalue2;public byte获取HTTP消息体。httpBodyinHttpResponse.httpBody;public void设置HTTP消息体。httpBodyinHttpResponse.httpBody = testdata.getBytes(UTF-8);配置说明将MVEL策略图标拖拽到流程编排图中，并在打开的编辑框中输入MVEL脚本。表4给出了几种常见的使用场景和对应MVEL脚本示例。表4MVEL脚本示例使用场景脚本示例从请求消息头中删除部分字段。例如，某开发者发送的请求中含有鉴权认证信息，请求如下所示：Get /testcuc/v1 HTTP/1.1 Authorization: WSSE realm=SDP,profile=UsernameToken X-WSSE: UsernameToken Username=35000001, PasswordDigest=D6ri9fAmdFhGijaU6c+9myLB/9s=, Nonce=2013042718472200001, Created=2013-04-27T18:47:22Z Host: 25:14312 Content-Type: application/xml; charset=UTF-8 Content-Length: 12345 若希望从请求消息中删除Authorization和X-WSSE字段，则可以使用如下MVEL脚本实现：outHttpRequest.httpHead.remove(Authorization); outHttpRequest.httpHead.remove(X-WSSE); 使用了如上MVEL脚本后，通过WO+能力共享平台发送至后端API服务器的请求消息如下所示：POST /testcuc/v1 HTTP/1.1 Host: 25:14312 Content-Type: application/xml; charset=UTF-8 Content-Length: 12345 在请求URI中增加参数。例如，某开发者发送的请求如下所示：Get /testcuc/v1?q=11111111 HTTP/1.1 Authorization: WSSE realm=SDP,profile=UsernameToken X-WSSE: UsernameToken Username=35000001, PasswordDigest=D6ri9fAmdFhGijaU6c+9myLB/9s=, Nonce=2013042718472200001, Created=2013-04-27T18:47:22Z Host: 25:14312 Content-Type: application/xml; charset=UTF-8 Content-Length: 12345 若希望通过MVEL脚本实现在请求URI中增加ak参数并设置参数的值，可以通过如下MVEL脚本实现:outHttpRequest.httpQueryParams.put(ak, 2383a70a3bcbb7b979fc03b7a9910746)使用了如上MVEL脚本后，通过WO+能力共享平台发送至后端API服务器的请求消息如下所示：Get /testcuc/v1?q=11111111&ak=2383a70a3bcbb7b979fc03b7a9910746 HTTP/1.1 Authorization: WSSE realm=SDP,profile=UsernameToken X-WSSE: UsernameToken Username=35000001, PasswordDigest=D6ri9fAmdFhGijaU6c+9myLB/9s=, Nonce=2013042718472200001, Created=2013-04-27T18:47:22Z Host: 25:14312 Content-Type: application/xml; charset=UTF-8 Content-Length: 12345 根据请求参数设置请求参数的类型。例如，某API支持查询根据手机号码、身份证号码、IP地址查询归属地。开发者发送的请求消息如下所示：Get /testcuc/v1?q=111111111111 HTTP/1.1 Authorization: WSSE realm=SDP,profile=UsernameToken X-WSSE: UsernameToken Username=35000001, PasswordDigest=D6ri9fAmdFhGijaU6c+9myLB/9s=, Nonce=2013042718472200001, Created=2013-04-27T18:47:22Z Host: 25:14312 Content-Type: application/xml; charset=UTF-8 Content-Length: 12345 若希望使用MVEL脚本根据传入的参数长度为11位时查询手机号归属地，参数长度为18位时查询身份证归属地，其他情况查询IP地址归属地，可以使用如下MVEL脚本实现：len= inHttpRequest.httpQueryParamsq0.length(); if(len=11) outHttpRequest.httpQueryParams.put(type,mobile); else if(len=18) outHttpRequest.httpQueryParams.put(type,id); else outHttpRequest.httpQueryParams.put(type,ip); 使用了如上MVEL脚本后，通过WO+能力共享平台发送至后端API服务器的请求消息如下所示：Get /testcuc/v1?q=11111111&type=mobile HTTP/1.1 Authorization: WSSE realm=SDP,profile=UsernameToken X-WSSE: UsernameToken Username=35000001, PasswordDigest=D6ri9fAmdFhGijaU6c+9myLB/9s=, Nonce=2013042718472200001, Created=2013-04-27T18:47:22Z Host: 25:14312 Content-Type: application/xml; charset=UTF-8