MapGuide HTTP API

本节将介绍什么是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下的代码就可以找到每个操作的参数和响应结果类型。