本节将介绍什么是HTTP API,HTTP API与MapGuide Web API的关系,以及如何使用HTTP API。一般情况下,我们并不需要使用HTTP API,而且Viewer API已经包装了某些必需的HTTP API。如果不打算对Viewer API进行一些修改的话,可以忽略本节的内容。
1.1.1 什么是HTTP API?
如果查看客户端API的JavaScript源代码,我们会发现类似如下所示的一些字符串。
OPERATION=<OperationName>&VERSION=1.0.0&... |
例如,当用户使用AJAX Viewer选择一个要素时,会调用客户端JavaScript函数RequestSelectionImage,从下面的代码可以看到这个函数就用到了这样的字符串。
function RequestSelectionImage(reqId, viewParams) { url = webAgent + "?OPERATION=GETDYNAMICMAPOVERLAYIMAGE&FORMAT=PNG&VERSION=2.1.0&SESSION=" + sessionId + "&MAPNAME=" + encodeComponent(mapName) + "&SEQ=" + Math.random() + "&CLIENTAGENT=" + encodeComponent(clientAgent) + "&BEHAVIOR=5&SELECTIONCOLOR=" + selectionColor; url += viewParams; document.getElementById('selOverlay').innerHTML = '<img class="mapImage" name="' + reqId + '" id="selectionImage" src="' + url + '" width=' + mapDevW + ' height=' + mapDevH + ' border=0 vspace=0 hspace=0 style="visibility: hidden; width: ' + mapDevW + 'px; height: ' + mapDevH + 'px;" οnlοad="return OnSelectionOverlayImageLoaded(event)">'; if (opera) document.getElementById("selectionImage").src = document.getElementById("selectionImage").src; } |
执行函数RequestSelectionImage后,会得到类似于如下所示的一个字符串。
http://hostname/mapguide/mapagent/mapagent.fcgi?OPERATION=GETDYNAMICMAPOVERLAYIMAGE&FORMAT=PNG&VERSION=2.1.0&SESSION=a4b1042a-d99e-11de-8000-005056c00008_en_7F0000010AFC0AFB0AFA&MAPNAME=Smoke%20Test%20Map&SEQ=0.9236688035011565&CLIENTAGENT=Ajax%20Viewer&BEHAVIOR=5&SELECTIONCOLOR=0x0000FFFF |
很明显,这是一个HTTP请求,它包含了参数OPERATION、FORMAT、VERSION、SESSION、MAPNAME、CLIENTAGENT、BEHAVIOR和SELECTIONCILOR,Web应用服务器端名为mapgent.fcgi的应用程序会处理这个HTTP请求,当处理完请求后,Web应用服务器会返回一张PNG格式的图像,这张图像是被选中要素的渲染结果。
这个HTTP请求使用的就是MapGuide服务HTTP API,MapGuide服务HTTP API定义了MapGuide客户端与MapGuide Web应用服务器的通信接口,为客户端通过Web应用服务器访问MapGuide服务器提供了一条通道。
1.1.2 HTTP API和MapGuide Web API的关系
MapGuide服务HTTP协议和MapGuide Web API有什么关系呢?他们的相同之处是都提供了一种访问MapGuide站点服务、资源服务、要素服务等服务的途径。不同之处是MapGuide Web API是Web应用服务器端接口,由Web应用服务器端的.NET、Java或PHP模块所调用,服务请求被直接发送到MapGuide服务器;而MapGuide服务HTTP协议是一种客户端接口,由客户端来调用,服务请求由部署在Web应用服务器上的MapAgent转发到MapGuide服务器。
目前,MapGuide Studio就是使用MapGuide服务HTTP协议来访问MapGuide服务器上的资源的,所以我们在使用MapGuide Studio的时候只需要知道Web应用服务器的地址,而不需要知道MapGuide服务器的地址,因为部署在Web服务器上的MapAgent知道MapGuide服务器的地址,会将服务请求转发给MapGuide服务器。
1.1.3 使用HTTP API
MapGuide HTTP API中定义的所有操作由如下几部分组成:
l 操作名称:操作的名称,例如“ENUMERATERESOURCES”。
l 操作参数:操作的参数,例如“RESOURCEID”。
l HTTP状态码:它反映了操作是否成功执行,例如“HTTP/1.1 200”,表示操作执行成功。
l 响应结果:操作返回的数据,可以是XML、PNG、JPG、DWF、W2D等。
HTTP API几乎为MapGuide站点服务、资源服务、要素服务等服务的所有方法都定义了一个对应的操作,这些操作的名称、参数、响应结果基本上和对应方法的名称、参数、返回值一致。HTTP API定义的所有操作使用了一些共同的参数,例如“VERSION”、“LOCALE”等,表 5‑1列出了这些共同的参数。从实现的角度来看,大部分HTTP API中定义的操作最终调用了MapGuide服务中对应的方法。
参数名称 | 是否可选 | 描述 |
OPERATION | N | 操作的名称。 |
VERSION | N | 操作的版本号,例如“1.0.0”。 |
LOCALE | Y | 本地化信息, |
表 5‑1 HTTP API中操作共同的参数
下面我们以枚举资源操作为例来介绍HTTP API,资源服务中有如下的方法用于枚举资源:
MgByteReader MgResourceService::EnumerateResources (
MgResourceIdentifier resource,
INT32 depth,
CREFSTRING type);
HTTP API也为枚举资源提供了对应的操作,操作的名称和参数如表5‑2所示。
参数名称 | 是否可选 | 参数值 |
OPERATION | N | EnumerateResources |
VERSION | N | 1.0.0 |
RESOURCEID | N | Library:// |
TYPE | Y | FeatureSource |
DEPTH | N | 3 |
表 5‑2 HTTP API枚举资源操的参数列表
如果发送此操作请求,会得到类似于如下所示的一个字符串。
http://hostname/mapGuide/mapagent.fcig?OPERATION=EnumerateResources&VERSION=1.0.0& RESOURCEID=Library:// &TYPE=FeatureSource&DEPTH=3 |
执行此操作后,Web应用服务器会返回表5‑3所示的HTTP状态码之一。
状态码 | 描述 |
HTTP/1.1 200 OK | 成功地获得的资源列表。 |
HTTP/1.1 401 Unauthorized | 用户认证失败。 |
HTTP/1.1 403 Forbidden | 用户没有权限访问被枚举的资源。 |
表 5‑3 HTTP API枚举资源操的HTTP状态码
如果成功地执行此操作,那么最后的响应结果为一个XML,这个XML文件描述了枚举得到的所有资源,在下面的列表中我们省略了这部分内容。
HTTP/1.1 200 OK Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?> …… |
非常遗憾的是,MapGuide没有为HTTP API提供一个参考手册。幸运的是大部分的操作都对应于MapGuide服务中的一个方法,这些操作的名称、参数、响应结果基本上和对应方法的名称、参数、返回值一致,所以猜也可以猜个八九不离十。如果实在搞不定,可能就需要参考MapGuided源代码,查看文件夹<MgSourceCodeDir>/MgDev/Web/src/HttpHandler下的代码就可以找到每个操作的参数和响应结果类型。