ISV产品接入指南2.docx

ISV产品接入指南目 录1文档目的32ISV接入提交项33接口开发与测试环境34ISV接入工作内容45接口定义55.1接口实现形式55.2平台提供给ISV的接口55.2.1Web Service（参数为实体对象）55.2.2Web Service（参数为XML字符串）55.2.3Post方式55.3ISV需要实现的接口定义65.3.1实现方式1：Web Service（参数为实体对象）65.3.2实现方式2：Web Service（参数为XML字符串）65.3.3实现方式3：Post方式65.4ISV接口实现注意事项65.5接口调用示例75.5.1示例：Web Service（参数为实体对象）75.5.2示例：Web Service（参数为XML字符串）85.5.3示例：Post方式85.6接口消息格式105.6.1请求消息105.6.2返回消息115.7消息体加密处理135.8消息调用返回码定义136接口开发与产品改造指南166.1接口实现过程步骤166.2配置文件166.3接口实现176.3.1产品订购176.3.2用户授权196.3.3健康检查266.3.4产品登录286.3.5心跳保持306.3.6数据同步316.3.7客户端登录317接口测试指南327.1测试准备工作327.1.1基本数据准备327.1.2基本数据检查327.2加解密算法测试337.3开通企业客户测试337.4企业用户授权测试337.4.1集成授权测试1337.4.2集成授权测试2347.5产品登录测试3447 / 471 文档目的本文档用于帮助ISV了解其产品接入平台时需要进行哪些工作、如何进行这些工作、完成后如何进行测试等，ISV在开始接入工作前，请详细阅读此文档内容。2 ISV接入提交项类型提交项重要程度描述文档产品图标必需用户订购时显示的产品图标产品介绍必需产品简介，介绍产品的宣传亮点、在技术、功能、应用等方面的特点，以及产品能为用户在哪些方面带来价值等用户手册必需详细介绍产品的管理功能与应用功能的使用方法，指导企业的管理员与最终用户使用系统安装手册必需系统的安装部署说明文档，能让平台维护人员参照此文档即可自行完成产品部署FAQ可选提供最终用户在使用系统中遇到一些常见的问题时的一般解决方法多媒体培训材料可选Flash、视频或其它形式的多媒体培训材料程序系统程序必需产品可运行程序与数据库等接口程序必需产品接口可运行程序产品接口访问地址必需产品接口部署后的访问地址，其中的主机名与端口可替换为实际部署环境的主机名与端口产品系统访问地址必需产品部署后的访问地址，其中的主机名与端口可替换为实际部署环境的主机名与端口3 接口开发与测试环境资源描述5:7012沙箱环境平台登录地址5:7011/SaaS2ISVInterface.asmx沙箱环境平台Web Service地址5:7011/SaaS2ISVInterfaceURl.aspx沙箱环境接收Post数据地址5:7012/SSOLogin.aspx沙箱环境平台单点登录地址5:7009提供示例程序、加解密算法、接口调用日志查看、SDK等辅助调试资源4 ISV接入工作内容u ISV产品改造1) 平台中维护的数据，ISV产品中不可增加或删除，如企业、用户。2) 平台中维护的数据，ISV产品中仅可编辑平台中不包含的数据属性的值。3) 去掉登录页面4) 去掉注销、退出等功能5) 去掉修改密码、修改个人信息等功能6) 平台用户的ID为GUID，ISV需实现此ID与其产品中的用户身份的对应。7) 提供体验功能，能让用户点击产品体验链接后，以一个默认体验帐号的身份直接进入系统，让用户简单试用。u ISV接口实现1) 企业客户业务受理接口：企业订购时调用，平台会传送企业的信息给ISV；2) 企业客户员工业务受理接口：企业建立用户时调用，平台会传送用户信息给ISV；3) 角色列表同步（读取）接口：企业给用户分配权限时调用，如果产品无角色功能，可不实现。4) 用户角色权限同步（读取）接口：企业给用户分配权限时调用，如果产品无角色功能，可不实现。5) 用户角色权限同步（更新）接口：企业给用户分配权限时调用，如果产品无角色功能，可不实现。5 接口定义5.1 接口实现形式平台与ISV之间的交互接口的实现有三种形式，具体如下：1) 双方提供Web Service供对方调用，参数与返回值使用实体对象（实体类），较适用于.Net平台或Java平台。2) 双方提供Web Service供对方调用，参数与返回值使用字符串（XML文本），较适用于Java平台或其它异构平台。3) 双方提供接收Post数据的页面，Post的数据及返回值均为字符串（XML文本），较适用于Java平台或其它异构平台如PHP、ASP等。5.2 平台提供给ISV的接口5.2.1 Web Service（参数为实体对象）方法名称SaaSISVInterfaceXMLString参数数据类型RequestInfo返回值数据类型ResponseInfo5.2.2 Web Service（参数为XML字符串）方法名称SaaSISVInterfaceXMLString参数数据类型String返回值数据类型String5.2.3 Post方式请求方法POST参数形式Msg=xml格式的字符串参数数据类型String返回值数据类型String5.3 ISV需要实现的接口定义ISV从接口实现的三种方式中，选择一种适合自己平台的方式实现给平台调用的接口。5.3.1 实现方式1：Web Service（参数为实体对象）方法名称ISVSaaSInterface参数数据类型RequestInfo返回值数据类型ResponseInfo5.3.2 实现方式2：Web Service（参数为XML字符串）方法名称ISVSaaSInterfaceXMLString参数数据类型String返回值数据类型String5.3.3 实现方式3：Post方式请求方法POST参数形式Msg=xml格式的字符串参数数据类型String返回值数据类型String5.4 ISV接口实现注意事项1) Web Service方法只有一个参数，通过传递不同的参数Code来指定调用的功能。2) namespace 必须是：http:/SaaSInterface.Sispark.M/，包括最后一个反斜线。几种实现方式提供的接口方法的功能一样，只是参数和返回值类型不同。具体的业务功能和返回信息由请求消息头的操作码（操作码）决定，即接口调用只有一个入口。示例如下：public ResponseInfo ISVSaaSInterface(RequestInfo req) ResponseInfo resp = new ResponseInfo(); switch (req.Head.Code) /企业客户业务受理接口 case ISV10101: resp = ISV10101CorpBind.ExecuteBusiness(req); return resp; /企业客户员工业务受理接口 case ISV10102: resp = ISV10102StaffBind.ExecuteBusiness(req); return resp; /角色列表同步（读取）接口 case ISV10201: resp = ISV10201PullRoles.ExecuteBusiness(req); return resp; /用户角色权限同步（读取）接口 case ISV10202: resp = ISV10202PullUserRole.ExecuteBusiness(req); return resp; /用户角色权限同步（更新）接口 case ISV10203: resp = ISV10203SyncUserRole.ExecuteBusiness(req); return resp; /未知接口，非法调用 default: return null; 5.5 接口调用示例5.5.1 示例：Web Service（参数为实体对象） /构造RequestInfo对象并赋值 RequestInfo request = new RequestInfo(); RequestHeadInfo reqHead = new RequestHeadInfo(); reqHead.SubmitTime = 20080709094433779; reqHead.AppID = PRO200805270005; reqHead.Code = ISV10101; reqHead.CTID = 2008070900000055; reqHead.Priority = 10; reqHead.Version = 1; request.Head = reqHead; string body = 1变更原因; /加密Body并赋值，“ABCD1234”为密钥 request.Body = CrptographyHelper.ComEncrypt(body, ABCD1234); /实例化Web Service ISV2SaaSInterface service = new ISV2SaaSInterface(); /调用Web Service ResponseInfo response = service.ISVSaaSInterface(request); /解密ResponseInfo的Body，还原为XML string bodyXml = CrptographyHelper.ComDecrypt(response.Body, ABCD1234);5.5.2 示例：Web Service（参数为XML字符串） /构造Body的XML字符串 string bodyXML = 1开通; /加密Body的XML字符串，“ABCD1234”为密钥 string body = CrptographyHelper.ComEncrypt(bodyXML, ABCD1234); /构造请求消息XML字符串 string requestXML = ISV101012008070900000055PRO20080610000120080709094433779110 + body + ; /实例化Web Service ISV2SaaSInterface service = new ISV2SaaSInterface(); /调用Web Service string responseXML = service.ISVSaaSInterfaceXMLString(requestXML); /取出Body值 XmlDocument xmlDoc = new XmlDocument(); xmlDoc.LoadXml(responseXML); XmlNode root = xmlDoc.DocumentElement; string responseBody = root.SelectSingleNode(Body).InnerText; /解密Body，还原为XML string bodyXml = CrptographyHelper.ComDecrypt(responseBody, ABCD1234);5.5.3 示例：Post方式 / / Post方式请求Url,返回response字符串 / / 数据流 / Url地址 / 返回数据 private static string UrlPost(string postData,string postUrl) try HttpWebRequest RequestObject = WebRequest.Create(postUrl) as HttpWebRequest; / 设定Cookie RequestObject.CookieContainer = new CookieContainer(); RequestObject.Credentials = CredentialCache.DefaultCredentials; /RequestObject.Proxy = this._webProxy; / 设定请求头。 RequestObject.ProtocolVersion = new Version(1, 0); RequestObject.KeepAlive = true; RequestObject.PreAuthenticate = false; RequestObject.Accept = */*; /RequestObject.Referer = postUrl; RequestObject.Headers.Add(Accept-Language, utf-8); RequestObject.UnsafeAuthenticatedConnectionSharing = true; /RequestObject.UserAgent = SMPClient; RequestObject.Method = POST; RequestObject.ContentType = application/x-www-form-urlencoded; RequestObject.AllowAutoRedirect = true; / Post数据 byte postBuffer = Encoding.UTF8.GetBytes(Msg= + HttpUtility.UrlEncode(postData); RequestObject.ContentLength = postBuffer.Length; using (System.IO.Stream postStream = RequestObject.GetRequestStream() postStream.Write(postBuffer, 0, postBuffer.Length); postStream.Close(); /网络响应对象 HttpWebResponse resp = RequestObject.GetResponse() as HttpWebResponse; System.IO.Stream respStream = resp.GetResponseStream(); /获取返回数据保护包 System.IO.StreamReader streamRead = new System.IO.StreamReader(respStream, Encoding.Default); StringBuilder strRet = new StringBuilder(); strRet.Append(streamRead.ReadToEnd(); respStream.Close(); resp.Close(); return strRet.ToString(); catch (Exception ex) throw new Exception(URL方式调用错误. + ex.Message, ex); /return ex.Message; 接收方示例： protected void Page_Load(object sender, EventArgs e) string msg = RequestMsg;/对请求消息msg进行解析并做业务处理，生成返回消息。 Response.Clear(); Response.Write(SYS103012008031500000023 + PRO200805270005200804091619077500 + 1.010 + 30); 5.6 接口消息格式5.6.1 请求消息请求消息是指调用接口的一方发出的消息，即Web Service方法的传入参数。 ISV10101 2008070900000055 PRO200805270005 20080709094433779 1 10 id9#F9904sfLO(%)$DSKLDOFEKRXBFSDF#$LCL_+$LXV:SFLOW(#$DVS 消息头所有接口的请求消息的消息头格式相同，具体属性说明见下表：名称说明数据类型长度（字节）Code操作码String8CTID客户端交易序列号（在发起方唯一标识一个交易的流水号，客户系统内16位唯一标示号）组成方式：8位日期8位唯一数，每天从00000001开始，如2008031500000001String16AppID业务应用标识（标识是哪个ISV应用系统，由平台统一分配）String8SubmitTime提交时间，格式为：YYYYMMDDHHmmssfffString17Version版本号（保留字段）当前值: 1String10Priority优先级（保留字段）当前值: 10Int 消息体每一个接口的请求消息的消息体的格式各不相同，具体请参见各接口的详细消息格式说明。5.6.2 返回消息请求消息是指接口被调用的一方返回的消息，即Web Service方法的返回值。 ISV10101 2008070900000055 2008070900001987 PRO200805270005 20080709094433779 1 10 0 id9#F9904sfLO(%)$DSKLDOFEKRXBFSDF#$LCL_+$LXV:SFLOW(#$DVS 消息头所有接口的返回消息的消息头格式相同，具体属性说明见下表：名称说明数据类型长度（字节）Code操作码String8CTID客户端交易序列号（在发起方唯一标识一个交易的流水号，客户系统内16位唯一标示号）组成方式：8位日期8位唯一数，每天从00000001开始，如2008031500000001String16STID服务端交易序列号（在接受方唯一标识一个交易的流水号，平台系统内唯一20位唯一流水）组成方式：AppID + “_” + 8位日期8位唯一数，每天从00000001开始，如10012008031500000001String25AppID业务应用标识（标识是哪个ISV应用系统，由平台统一分配）String16RequestTime请求接受时间，格式为：YYYYMMDDHHmmssfffString17ResponseTime响应处理时间，格式为：YYYYMMDDHHmmssfffString17Version版本号（保留字段）当前值：1String10Priority优先级（保留字段）当前值：10(能转换为int的串)String16Status返回结果状态(能转换为int的串)(0: 正常；-1: 系统调用异常)String 消息体每一个接口的返回消息的消息体的格式各不相同，具体请参见各接口的详细消息格式说明。5.7 消息体加密处理消息体的原始数据为一段XML字符串，如：1变更原因PRO200805270005292008070900000000020090109000000000，在消息传输时，消息体需要加密后传输，即消息的Body部分为加密后的字符串。无论是请求消息还是返回消息的消息体都需经过加密处理，具体加密算法为：Base64(DES(MD5(消息体) + 消息体)5.8 消息调用返回码定义CodeResultCodeResultMessage描述所有消息0成功正常返回1对未定义错误的描述未定义错误101数据非法加密ISV应用系统私钥与SaaS中的私钥不一致102非法的XML格式消息格式与本规范中定义的不一致SSO鉴权消息11010101获取登录信息异常在获取当前登录用户信息时出错11010102用户Token不存在用户Token不存在，需要重新登录11010103用户Token 已失效用户Token过期，需要重新登录11010104用户Token非法用户Token非法，需要重新登录11010105用户登录未知系统SaaS对用户登录的系统未知11010106其他错误110101*编码定义鉴权消息其他错误SSO心跳消息11010202用户Token已失效用户Token过期，需要重新登录11010203用户Token不存在用户Token不存在，需要重新登录11010104用户Token非法用户Token非法，需要重新登录11010205获取用户登录信息信息出错在获取当前登录用户信息时出错11010206更新令牌错误更新令牌错误客户端登录接口消息11020101 用户名或密码出错用户名或密码出错11020103其他错误110201*编码定义产品访问鉴权消息其他错误产品访问鉴权消息11020201用户Token已失效用户Token过期，需要重新登录11020202用户Token不存在用户Token不存在，需要重新登录11020203用户Token非法用户Token非法，需要重新登录11020204获取用户登录信息信息出错获取用户登录信息信息出错11020205判断逻辑错误判断订购关系业务逻辑错误企业信息接口11030101取得用户信息错误获取企业管理员信息出错11030102未获得企业信息返回信息为空11030103获取企业信息异常获取企业信息发生业务错误企业员工信息接口11030201非法的UserIDsUserIDs为空11030202获取用户信息错误获取用户信息错误计费消息11040101数据非法加密 ISV应用系统私钥与SaaS中的私钥不一致11040102用户Token已失效用户Token过期，需要重新登录11040103用户Token不存在用户Token不存在，需要重新登录11010104用户Token非法用户Token非法，需要重新登录11040105用户订购关系不存在用户没有权限使用该功能11040106未知业务资费信息SaaS管理平台未设置该业务的计费策略11040107其他错误3*编码定义批价消息其他错误企业客户业务受理消息21010101业务配置参数错误业务订购配置不符合ISV应用系统的约定21010102业务功能点订购错误订购的功能点与ISV应用系统提供的不一致21010103License数量错误License可能不是非负的整数21010104未知操作类型ISV应用系统无法识别操作类型（订购、取消、暂停、恢复）21010105其他错误4*编码定义该类消息其他错误企业客户员工业务受理消息21010201未知企业客户帐号企业客户帐号在ISV应用系统中不存在21010202用户手机号码非法用户手机号码错误21010203其他错误5*编码定义该类消息其他错误6 接口开发与产品改造指南6.1 接口实现过程步骤序号工作内容1联系平台管理员，在平台中录入ISV和产品信息，获取ISVID、AppID、密钥2建立配置文件，填入平台管理员提供的ISVID、AppID、密钥、平台接口地址、平台单点登录地址3建立Web Service并声明好方法，发布在外网，然后将Web Service的地址和产品地址发给平台管理员，在平台的产品信息中录入。4实现产品订购功能5测试产品订购功能6实现用户授权功能7测试用户授权功能8实现产品登录功能9测试产品登录功能10实现心跳保持功能11测试心跳保持功能6.2 配置文件ISV需提供一个配置文件，其中包括以下可修改的配置参数：参数值Web Service接口地址(或Post数据的页面地址)正式环境的平台接口地址ISVIDISV在平台中的唯一标识码AppIDISV的某一产品在平台中的唯一标识码加解密密钥ISV分配的加解密密钥平台单点登录页面正式环境的平台单点登录页面.Net应用的Web.config文件中添加配置信息示例，其它平台类似： 6.3 接口实现6.3.1 产品订购 应用场景 企业客户业务受理接口（ISV实现，平台调用）企业客户业务受理接口由ISV提供给平台调用，平台向ISV输入待增加的企业客户，ISV给企业客户创建一个新的实例，并配置数据库等相关资源。注意事项如下：1) ISV给企业创建实例时如果需要特殊的参数，则需事先整理出来，交给平台管理员维护。这样用户在订购的时候就可以输入这些参数的值，然后平台会将这些参数值传递给ISV的Web Service，ISV再根据这些参数值给企业开通服务。2) 如果ISV的产品需要根据模块收费，则需要将模块信息整理并提交给平台管理员。这样用户在订购的时候就可以选择需要的模块。然后平台会将模块信息传递给ISV的Web Service。3) 企业可以多次订购一个产品，例如初次订购和续订，ISV产品需要做相应处理，续订时，注意新的时间区间的记录和处理。消息类型编码ISV10101请求消息消息格式Request通用消息头加密后的消息体未加密的消息体格式绑定标志绑定说明应用（产品）ID企业客户ID企业客户名称企业客户简称企业客户英文名称企业客户英文简称企业FQDN企业营业执照号 企业法人企业管理员GUID企业管理员联系电话企业管理员联系手机企业管理员联系邮件企业地址企业邮寄地址 邮编企业电话传真号码邮箱地址企业WEB网址企业LogoURL 变更时间业务配置参数代码业务配置参数值模块1,模块2,开始时间结束时间名称说明数据类型长度（字节）OPType受理标志:1 : 开通2 : 暂停3 : 恢复4 : 更新5 : 退订状态2、3、5只用企业客户ID和应用（产品）ID字段String8OPNote绑定说明，例如：业务变更原因String256AppID应用（产品）IDString16CorpInfo企业客户的企业信息String16ParamName业务订购配置参数名String64ParamValue业务订购配置参数值String256ModuleList订购模块列表（以逗号分割）StringStartTime开始时间（只对OPType: 1,4有效）格式为：YYYYMMDDHHmmssfffString17EndTime结束时间（只对OPType: 1,4有效）格式为：YYYYMMDDHHmmssfffString17返回消息消息格式Response通用消息头加密后的消息体未加密的消息体格式返回结果代码返回结果描述名称说明数据类型长度（字节）ResultCode返回结果代码（0:成功；1:失败）String16ResultDesc返回结果文字描述String2566.3.2 用户授权用户集成授权需要ISV实现4个接口，包括企业客户员工业务受理接口，及权限角色相关的三个接口：1) 企业客户员工业务受理接