MS RFC 134:OGC API支持¶
- 作者
史蒂夫·莱姆
- 联系
- 作者
汤姆克拉利迪
- 联系
- 作者
杰夫麦克纳
- 联系
- 状态
正在进行中
- 最后更新
2021-06-23
- 版本
MapServer 8.0版
概述¶
OGC正在进行革命性的努力,使其API规范现代化,以与当前的技术和设计模式保持一致:
REST
JSON
OpenAPI(和Swagger)
这个 OGC API 这些努力代表了与第一代WXS规范的彻底决裂。本RFC试图描述MapServer对(最初)OGC API-Feature服务器规范的支持。OGC API的模块化特性将允许重复使用共享功能(登录页面、一致性、集合、可查询、过滤等)。跨越在MapServer中实现的各种OGC API。
OGC API请求/响应设计模式由对特定查询参数使用GET(KVP)或POST(JSON)方法的HTTP操作组成。GET/POST(PUT、DELETE等)之外的HTTP方法被设想为事务处理能力的可选扩展。
下面是在MapServer套件中实现的WXS规范与相关新兴OGC API标准之间的映射。
WXS |
OGC API |
---|---|
OWS通用 |
OGC API-通用 |
WMS |
OGC API-地图 |
WMTS |
OGC API-Tiles |
WFS |
OGC API-功能 |
WCS |
OGC API-覆盖范围 |
SLD |
OGC API-样式 |
建议的方法¶
支持OGC API规范所需的大部分底层功能已经存在于MapServer中,并通过WXS支持公开。WXS支持很复杂,这主要是因为所支持的服务规范的版本各不相同。代码充满了条件,因此根据版本的不同表现不同,或者公开新的功能。WXS规范在很大程度上依赖于查询字符串(GET/POST)来配置请求和响应的XML。
虽然肯定会有机会利用部分现有的OWS/WXS代码,但进一步复杂化主要的WXS功能是没有意义的。我们还可以使用C++开发新功能,并可以利用现代C++库,如nlohmann/json和Inja。在“干净中断”模式下工作也遵循OGC API方法来实现API的现代化。
CGI/FastCGI集成¶
为了支持基于REST、基于资源/路径的请求方法,我们需要依赖查询字符串或POST-Body之外的其他CGI组件:具体地说,信息存储在 PATH_INFO 环境变量我们还需要一个映射文件和一些正在使用的API规范的指示。我们建议采用以下方法:
http(s)://maps.dnr.state.mn.us/cgi-bin/mapserv/mapfile/api/route
在哪里:
/mapfile/api/route=路径信息
Mapfile=引用全路径映射文件名的环境变量
Api=接口签名(如ogcapi),支持多个接口
ROUTE=API路径(例如/Collection/layer/id)
PATH_INFO变量是CGI标准的一部分,并且(至少在APACHE中)已经可用于MapServer。此外,MapServer已经支持基于环境变量的映射文件定义。事实证明,检查是否存在PATH_INFO并在必要时将处理重定向到API调度器是相对简单的。标准工作流在很大程度上不受此更改的影响,因此应该不会有向后兼容性问题。
此设置还允许API使用查询字符串,因此您可以组合如下内容:
http(s)://maps.dnr.state.mn.us/cgi-bin/mapserv/mapfile/ogcapi/conformance?f=html
配置¶
与其他OGC WXS服务一样,OGC API支持将通过Web和层对象元数据进行配置。一个新的命名空间- oga (OGC地理空间API)将被识别,并且只要可能,OGC API支持将利用现有的OWS |wfs| WMS|GML元数据。OGA命名空间将优先用于元数据查找。
与其他OGC WXS服务一样,需要在地图和层级别使用元数据“OGA_ENABLE_REQUEST”(或“OWS_ENABLE_REQUEST”)值显式启用OGC API支持。当前全部或无(“OGA_ENABLE_REQUEST”“OGCAPI”)。
元数据元素命名应该反映API规范,以避免遗留命名约定的新实现。但是,也应该引用WXS元数据作为后备,以便利用现有配置。这是一个API描述示例,我们将在映射级别查找OGA_DESCRIPTION,如果找不到则回退到OWS|WFS_ASTRAGE。
新元数据密钥(OGA命名空间):
钥匙 |
水平 |
含义 |
---|---|---|
在线资源 |
地图 |
API根URL,无法重复使用WXS值 |
html_template_directory |
地图 |
Html模板目录的完整路径或相对路径(到映射文件) |
描述 |
地图 |
服务描述,回退到OWS/WFS_ASTRACT |
链接 |
地图,层 |
逗号分隔的链接键列表-对其他元数据的引用 |
link_{key}_title |
地图,层 |
链接标题 |
link_{key}_href |
地图,层 |
链接HREF(URL) |
html_tags |
地图 |
要向HTML模板公开的以逗号分隔的标记键列表-对其他元数据的引用 |
tag_{key} |
地图 |
与标记相关联的值,添加到template.tag对象中的JSON数据 |
关键词 |
图层 |
逗号分隔的关键字列表,回退到OWS/WFS_Keywordlist |
max_limit |
地图,层 |
地图或图层级别的最大限制值(整数) |
JSON支持¶
OGC API规范严重依赖JSON。最优秀的 nlohmann/json 将使用C++库为每个请求类型构造响应对象。该库是同类中最好的,并被其他OSGeo项目广泛使用,如Proj。更重要的是,集成很简单:只需包含一个 .hpp 文件。我建议实际上分发 nlohmann/json.hpp 文件,然后根据需要进行升级。在这种情况下,不需要复杂的cmake配置。
Nlohmann/json拥有麻省理工学院的执照。
超文本标记语言支持¶
虽然不是必需的,但强烈建议您支持HTML语言。我建议使用一系列模板来支持HTML响应,而不是尝试从MapServer内部存储和输出HTML。这为我们(和用户)提供了极大的灵活性来控制API文档的外观。基本OGC API模板将随MapServer一起提供,默认情况下使用Bootstrap 4构建。还将提供第二套纯HTML模板,并将为MSAutotest支持提供稳定的基础。模板位于MapServer分发版中的新版本中 分享 目录,并按API签名(SO share/ogcapi/templates )。用户要配置HTML响应,只需将模板的基本路径记为元数据值( oga_html_template_directory )或环境变量( OGCAPI_HTML_TEMPLATE_DIRECTORY )。
C++ Inja templating library 用于处理HTML响应。INJA依赖于nlohman/json,因此API响应总是首先用JSON编写,然后使用INJA呈现为HTML。Inja功能齐全,支持表达式、条件句、循环和Include等。与nlohmann/json一样,Inja很容易使用单个 .hpp文件 。我再次建议使用MapServer分发Inja。
Inja也有麻省理工学院的执照。
MapScrip支持¶
供考虑: SWIG MapScript类是否应该 OWSRequest 增强为还允许动态修改OGC API服务?
新的源文件¶
- mapogcapi.cpp/mapogcapi.h
核心实施。
- 第三方/Include_nlohmann_json.hpp
Nhlohmann/json库的包装器。
- 第三方/INCLUDE_PANTOR_INJA.hpp
Inja库的包装器。
备注
将需要编辑以引用nlohmann/json的本地实例。
源文件已更改¶
- mapserv.c/mapserv.h
将对msCGIIsAPIRequest()的调用添加到主CGI工作流。为msIsAPIRequest()和msCGIDispatchAPIRequest()添加了函数原型。添加了设置PATH_INFO的命令行挂钩。
- mapservutil.c
添加msIsAPIRequest()和msCGIDispatchAPIRequest()函数。更新msCGILoadMap()以加载由API定义的映射文件--基本上是环境变量用例。
- cgiutil.c
已更新以使用msSetError(),而不是直接写入错误消息。适当地扩展cgiRequestObj init/free函数。
- cgiutil.h
向cgiRequestObj添加PATH_INFO、API_PATH和API_PATH_LENGTH属性。
- maperror.c/maperror.h
向msGetVersion()添加了OGC API支持。新增接口错误码和错误信息。请注意,特定的OGC API错误处理是在mapogcapi.cpp内本地处理的。
生成文件已更改¶
- CMakeLists.txt
典型的新功能集成。
- mapserver-config.h.in.中的
添加了USE_OGCAPI_SVR。
限制/注意事项¶
输入/输出SR仅为EPSG:4326。
功能属性支持GML项和常量配置。未实现组。
向后兼容性问题¶
没有预料到的--新功能。
安全注意事项¶
API路由处理¶
最复杂的路线:
/{mapfile}/ogcapi/collection/{collectionId}/item/{itemId}
固定API路由元素必须精确匹配并且区分大小写。任何偏离都将导致错误。
变量API路由元素的处理方式如下:
- {映射文件}
引用在环境中定义的映射文件。如果没有找到映射文件,则返回标准的CGI错误消息。
- {集合体ID}
引用层名称,并且必须完全匹配。如果没有找到该层,或者如果该层不符合条件(例如栅格),则抛出404错误(作为JSON)。
- {itemid}
引用由定义的要素ID gml_featureid 元数据。或者,使用层验证块中提供的正则表达式验证值。如果验证失败,则抛出404错误(作为JSON)。(还会检查名称字母OGA、OWS和WFS,例如OGA_Featureid)
METADATA
"gml_featureid" "myid"
...
END
VALIDATION
"myid" "^[0-9]{2}$" # limit to 2-digit integers
...
END
备注
我们可以考虑将这样的验证扩展到接受 filters._
参数处理¶
在此初始实施中支持的参数相对较少:
- F
响应的格式,支持的值为json和html。返回带有任何其他值的错误。默认为html。
- BBox
边界框过滤器。返回错误,返回错误的值、大于/小于4个数字、退化边界或如果在后面/后面没有给出值。默认是指使用地图的默认范围。
- 限制
要返回的结果数。返回错误,返回格式错误的值。其他值被剪裁到1到10,000(根据等级库)的范围。
- 开始
页码。返回错误,返回格式不正确的值。
模板处理¶
模板包含 Inja template markup 。文件名在代码中是固定的(例如Collection-items.html)。包含模板的目录在webObj元数据中给出,或者(可选)通过环境变量给出。目录规范可以是绝对的(例如,/opt/mapserver/ogcapi/plates),也可以是相对于映射文件位置的。到目前为止,执行工作允许使用Inja {包含“文件”} 标签。使用通用元素(如页眉、页脚等)来维护模板是不切实际的。如果没有这种功能。如果对模板的访问不受限制,则当前的INJA实施允许文件属性的任何值,这表示存在安全风险。已有针对Inja的增强请求来添加此功能,或者我们需要更新库以将包含内容限制在指定的目录或子目录中。
大数据集处理¶
尚不清楚可以通过nlohmann/json和/或INJA处理多大的数据集(见上文)。默认的最大限制值10,000在许多情况下可能不合适。可以使用设置地图和/或图层限制 oga_max_limit 元数据。层值优先。利用为WFS所做的工作,支持分页的驱动程序可以使用分页。
性能影响¶
对整体性能的影响应该非常小。将单个函数添加到 mapserv.c 用于检测API请求的工作流。该函数检查 PATH_INFO 环境变量,查看该值(如果有)是否与前面描述的API调用的最小模式匹配。如果是这样,则 CgiRequestObj 一旦加载了映射文件,请求就会被快速推送到OGC API处理工作流中。
票证ID和引用¶
现状¶
支持 |
状态 |
---|---|
功能:登录页面 |
🚧 |
功能:JSON和HTML输出 |
✔️ |
功能:集合(图层列表) |
🚧 |
功能:集合(单层:链接(摘要) |
🚧 |
功能:集合(单层:查询) |
🚧 |
功能:集合(单层:列出可查询字段) |
🛑 |
要素:集合(单层:地图) |
🛑 |
功能:API文档 |
🛑 |
功能:MS自动测试 |
🚧 |
功能:mapserver.org上的用户文档 |
🛑 |
问题/任务/愿望清单¶
- 问题
清理“?”的在线资源。或“/”结束字符,因为这会导致在HTML登录页中出现问题(链接中的双斜杠或“?”实际上会断开所有链接)
- 问题
编译在未启用的情况下失败 -DUSE_WFS_SVR (以及显而易见的 -DUSE_OGCAPI_SVR )
- 任务
将OWS_CONTACT*信息添加到登录页面(来自映射文件中设置的关联值)
- 愿望清单
除了接口签名/ogcapi(对于功能、地图..支持),还允许使用/Feature(开发者只能请求向量集合),例如:
http://127.0.0.1/cgi-bin/mapserv.exe/demo-ogcapi/features
(请注意,这就是Geoserver实现的工作方式)
- 愿望清单
在登录页面上包含MapServer徽标
- 愿望清单
为所有HTML页面设置MapServer收藏夹图标
- 愿望清单
允许收集项的其他链接类型(是否通过映射文件中的MIMETYPE/输出格式设置?)
- 愿望清单
不使用文本链接,而是使用类型(JSON、HTML、KML等)的下拉列表
- 愿望清单
对于单层地图,包括一个下拉列表以设置地图中显示的默认要素数:
10 [default] 100 1000
- 愿望清单
对于单图层地图,在地图下方显示当前的MapServer比例值(当用户放大时,使用CGI更新比例 [比例尺] 价值)