MS RFC 134：OGC API支持

作者

史蒂夫·莱姆

联系

steve.lime@state.mn.us

作者

汤姆克拉利迪

联系

tomkralidis@gmail.com

作者

杰夫麦克纳

联系

jmckenna@gatewaygeomatics.com

状态

正在进行中

最后更新

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

在哪里：

  1. /mapfile/api/route=路径信息

  2. Mapfile=引用全路径映射文件名的环境变量

  3. Api=接口签名(如ogcapi)，支持多个接口

  4. 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更新比例 [比例尺] 价值)

初始屏幕封装

登录页

../../_images/ogcapi-draft-ms4w-landing.png

收藏

../../_images/ogcapi-draft-ms4w-collections.png

集合

../../_images/ogcapi-draft-ms4w-collection.png