SuperMap iServer REST API介绍

作者：MR

    SuperMap iServer (以下简称iServer)采用 REST 架构，提供了基于标准 HTTP 协议的应用编程接口——iServer REST API，这些接口封装了大部分的 GIS 功能，包括地图功能、数据功能、分析功能、三维功能等。SuperMap iServer 将这些 GIS 功能以资源的形式提供给客户端，客户端使用 iServer REST API 对资源进行操作，能够获取到相应的 GIS 能力。

    使用 iServer REST API 大致要分为以下三个步骤：

1. 查询 SuperMap iServer REST API 帮助，确定应用所需的 REST 资源，确定每个所需传递的参数和资源的响应结构；
2. 按照资源的 URI 和所需传递的参数构建 HTTP 请求访问资源。
3. 参照资源的响应结构，解析服务器响应，提取所需的信息。

    已知的iServer REST API主要应用：各种版本的iClient 、iServer管理页面（浏览器访问 http://{IP}:{端口}/iserver/manager 开头的页面）、iServer JAVA API(部分)等，帮助文档示例位置在 开始 > iServer 开发与扩展指南 > 使用 iServer API > 使用 REST API 目录下。

    主要应用场景：

1. iServer服务管理资源（需要安全认证），比如不通过iServer管理页对服务进行管理，包括发布、修改、删除服务；切图任务；监控；服务器配置(不包括重启)等等。
2. 现有iClient不能满足开发需求的，比如其他后端语言使用REST API、对接现有或扩展的iServer服务等。

    iServer REST API访问被保护资源点此。

    iServer REST API分为服务资源和管理资源。

###一、服务资源
    服务资源即iServer发布的各种服务，iClient对接的就是这个资源。服务资源层次结构点此，服务资源根节点点此。
    除了使用iClient来访问iServer服务资源，也可以使用iServer JAVA API。

    这里简单举一个例子，比如，在浏览器直接访问以下地址：

http://support.supermap.com.cn:8090/iserver/services.rjson

    会返回support.supermap.com.cn:8090/iserver这个iServer发布的所有服务的RJSON表述（缩进的JSON字符串，便于查看，支持HTML、JSON等表述，iServer支持的表述格式点此），而上述URL末尾不写 .rjson 则默认返回html表述，也就是我们平常看到的服务列表页。
    参考services服务资源的帮助，可以知道，该资源支持HTTP GET、HEAD方法，GET方法没有需要设置的参数。其他资源以此类推，基本每个资源在帮助文档中都有请求示例。
###二、管理资源
    管理资源即对iServer进行管理的服务资源，代表应用就是iServer管理页面。管理资源层次结构点此，管理资源根节点点此
    前面的服务资源根据设置可能需要安全认证也可能不需要，但是管理资源时一定需要安全认证的，并且需要设置的认证用户有对应的权限，比如， PUBLISHER 角色的用户只能发布服务，无权创建切图任务等。
    安全认证的方式有两种，一种是token（使用iServer用户名密码生成），另一种是先使用登陆服务，再设置请求头，多为后端进行，因为浏览器有限制。

    使用JAVA访问iServer管理资源设置请求头通过安全验证的代码如下：

	/**
	 * 登陆iServer
	 * 
	 * @param ipport
	 *            iServer服务根目录，比如："http://localhost:8090"
	 * @param username
	 *            登陆iServer的用户名
	 * @param passwor
	 *            登陆iServer的密码
	 * @return String cookie
	 */
	private String login( String ipport, String username, String passwor )
	{
		try
		{

			String json = "{\"username\": \"" + username + "\",\"password\": \"" + passwor
					+ "\",\"rememberme\": \"true\"}";

			URL url = new URL( ipport + "/iserver/services/security/login.json" );
			HttpURLConnection connection = (HttpURLConnection) url.openConnection( );
			connection.setDoInput( true );
			connection.setDoOutput( true );
			connection.setRequestMethod( "POST" );
			connection.setUseCaches( false );
			connection.setInstanceFollowRedirects( true );
			connection.setRequestProperty( "Content-Type", "application/x-www-form-urlencoded; charset=UTF-8" );
			connection.connect( );
			DataOutputStream out = new DataOutputStream( connection.getOutputStream( ) );

			out.writeBytes( json );
			out.flush( );
			out.close( );

			BufferedReader reader = new BufferedReader( new InputStreamReader( connection.getInputStream( ) ) );
			String lines;
			StringBuffer sbf = new StringBuffer( );
			while ( ( lines = reader.readLine( ) ) != null )
			{
				lines = new String( lines.getBytes( ), "utf-8" );
				sbf.append( lines );
			}
			System.out.println( "//" + sbf + "//" );

			String cookie = connection.getHeaderField( "set-cookie" );

			reader.close( );
			connection.disconnect( );

			return cookie;
		} catch ( MalformedURLException e )
		{
			e.printStackTrace( );
		} catch ( IOException e )
		{
			e.printStackTrace( );
		}
		return "";
	}

    拿到cookie后，使用别的iServer管理资源时设置请求头"cookie"(connection.setRequestProperty("cookie", cookie);)为拿到的cookie就可以正常使用iServer管理资源了。当然，使用token也是可以的。
    其他，某些REST API没有列出的iServer管理资源可以在iServer管理页对应页面抓网络请求获取。