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