宜春市开放门户服务调用SDK使用指南.docx
宜春市开放门户服务调用SDK使用指南目录1 概述错误!未定义书签。1.1 预期读者错误!未定义书签。2 API开发规范错误!未定义书签。2.1 接口形式错误!未定义书签。2.2 请求规范错误!未定义书签。2.3 响应规范错误!未定义书签。2.3.1 响应模式错误!未定义书签。2.3.2 业务字段约定错误!未定义书签。2.3.3 响应状态码约定错误!未定义书签。2.4 接口安全加密错误!未定义书签。3 API注册指南错误!未定义书签。3.1 提交注册接口材料错误!未定义书签。4 API调用说明错误!未定义书签。4.1 接入前准备工作错误!未定义书签。4.2 授权认证流程错误!未定义书签。4.3 客户端授权认证流程错误!未定义书签。4.4 认证授权API错误!未定义书签。4.4.1 获取授权码错误!未定义书签。4.4.2 使用授权码方式token错误!未定义书签。4.4.3 使用客户端凭证方式获取token错误!未定义书签。4.4.4 使用RefreshToken获取新token错误!未定义书签。5 附录错误!未定义书签。5.1 API调用示例错误!未定义书签。5.1.1 SDK错误!未定义书签。5.1.2 调用示例代码错误!未定义书签。1概述本文主要描述开放门户接口网关管理平台提供的系统接口对接管理能力， 帮助应用系统开发商理解接入原理并快速上手对接工作。Ll预期读者相关系统接口开发人员：实际执行接口开发的人员，需要了解对接APl 开发细节规范，建议需要有2年以上程序开发经验。接口接入实施测试人员：同样需要了解的接入原理和规范，辅助进行 相关实施方案和测试用例的编制。2 API规范2.1 请求规范请求方式是采用常规的get. post,具体视实际API服务类型情况而定。必须采用post的话，请求体约定为key-value键值对的形式。2.1.1 请求头规范：参数名称是否必须类型描述Content-type是字符串application/x-www-form-urlencodedAuthorization是字符串Bearer access_token注:accessOken从认证授权APl中获取2.1.2 请求参数规范请求参数按照APl的实际要求进行填写，请求体约定为key-value键值对的形式参数名称是否必须类型描述Parml是字符串Parm2是字符串2.2 响应规范2.2.1 响应模式返回内容类型(COntent-TyPe) Content-type: text/plain;charset=UTF-8 返回内容编码(CharSet)为UTF-82.2.2 响应状态码约定请求层面的状态响应统一是在HTTP的响应头里处理，前端在获取到请 求返回的HTTP响应状态码后，对于非200的请求，可以根据不同的状态码 给出通用的错误处理。响应状态码意义说明如下：200表示请求成功，服务端返回业务数据。400被服务端安全模块拦截。服务端会返回一段错误信息，前端做通用的提示。 服务端返回的错误信息数据格式如下：<! DOCTYPE htl><! DOCTYPE htl> <html class"no-js" style"background-color: transparent"> <head>(title>安全拦截信息"title><style>.blockquote, body, button, code, dd, div, dl, dt, fieldset, form, hl, h2, h3, .sys-pael-coverposition: absolute;top: 0;left: 0;width: 10%;height: l%iback -top: -240px;.sys-panel(border-radius: 5p×jborder: lp× solid #cdcdcd;background -title.dangercolor: #a94442;.sys-panel .panel-hdborder-bottom: lp× solid WdCd， -panel .alert(padding: 10pxjt>rder-radius: 3px;line-height: 1.8jborder: lp× soli<head> <body><form id="forml"><div class-sys-panel-cover><div><div class="sys-panel in-center" id="err-panel"><div class"pael-hd mb20"><h4 class="panel-title danger”>安全提示<h4> <div> <div class"panel-bd mb20"> <p class=',alert alert-warn。)本次访问存在不安全除患，清联系管理员！<"/ >错误编号ESE0604006J<br />敏感字符from<p><div><div><form><body><htl>401无权限。服务端会返回一段错误信息，前端做通用的提示。服务端返回的 错误信息数据格式如下：<"error_description": "The access token is invalid or has expired", "error": "invalid token"404资源未找到。500服务端发生其他异常。服务端会返回一段错误信息，前端做通用的提示。服务端返回的错误信息数据格式如下：Pretty Raw Preview Text 2 ZP1 -error" :"/ by ero',)2.3接口安全加密接口在进行传输是一般推荐使用，加密密文保证整个传输过程中数据的安全性;详细加解密参考5.1调用示例其中需要注意的是接口的入参与出参需要进行整体加密;3 APl调用说明3.1 接入前准备工作根据开发者文档中的新手入门中的指引，注册开放门户账号，并注册应用， 应用审核通过后开发者会获得一个应用系统登录名和密码（APPKey和 AppSecret） 此帐号是一切与平台对接工作的前提。3.2 授权认证流程开放门户接口平台提供基于OAUth2.0的统一身份鉴权方式。第三方应用通过申请令牌token,来完成对APl的调用访问。其中对于所有 访问用户隐私API的请求，需要提供用户授权令牌来校验该第三方调用是否是 合法调用，而对于所有平台基础支撑API,需要提供客户端授权令牌来进行校验。关于OAUth2.0协议的详细介绍，可以参考W3C的官方文档。开发者可以先浏览OAUth2.0的接口文档，熟悉OAUth2的接口及参数的 含义，然后我们根据用户授权认证和客户端授权认证2种场景各自说明如何使用 OAuth2.0o33客户端授权认证流程客户端授权由于不需要最终用户参与，过程相较用户授权简单的多。一般情 况下，只有少量服务涉及用户资源，大部分的服务是无需用户授权的。所以客户 端授权认证流程为主要的认证模式。1）业务系统直接调用客户端凭证方式获取令牌token2）业务系统根据令牌即可调用业务API。3.4认证授权API3.4.1 使用客户端凭证方式获取token3.4.1.1 功能说明根据应用插件在新建时分配的key和secret,获取访问资源和管理api的token。3.4.L2接口调用说明3.4.1.2.1 URL服务调用 ½trestoauth2token3.4.1.2.2 HTTP 请求方式POST3.4.1.2.3 输入参数说明参数 Body 类型：x-www-fonn-urlencoded参数名称是否必须类型描述client_id是字符串应用标识client_secret是字符串应用密码grant_type是字符串固定值：Clienccredentials34.1.2.4返回参数说明Content-type: te×tplainjcharset=UTF-8文本内容采用json格式，可以解析出一下参数:参数名称描述accessOken最终获取到的tokenexpiresntoken有效期时长refresh_token刷新token票据3.41.2.5正确返回示例"accesS-token"f,gAAAAAYk-NLKDVX5Fhx903-dAabRFPrMRPVOAmuuPbiHwjE., ,expiresjn":" 120000",3.4.2 使用 RefreshToken 获取新 token3.4.2.1 功能说明根据刷新票据计算生成新的tokeno3.42.2接口调用说明3.4.2.2.1 URL服务调用地址restoauth2token3.4.2.2.2 HTTP 请求方式POST342.2.3输入参数说明参数名称是否必须类型描述refreshOken是String用于刷新Token用的Refresh Tokengrant_type是字符串固定值：refreshtoken342.2.4返回参数说明参数名称描述accessOken最终获取到的tokenexpiresjntoken有效期时长refresh_token刷新token票据3.4.2.2.5 正确返回示例"accessJoken"'gAAAAAYk-NLKDVX5Fhx903-dAabRFPrMRPVOAmuuPbiHwjE., "expiresJn,'"l20000",3.5API调用示例3.5.1 SDKepoint-ipaas-sdk-93.2JarIog4j-1.2.17_ch.jar.commons-logging-1.0.4.jar352调用示例代码demo.java
