3.6. OGC API功能

OGC API功能(OAPIF)是新一代OGC协议的第一个实现。它是由 OGC API - Features - Part 1: Core 文件。

在典型安装上可以通过以下方式访问该API http://localhost/qgisserver/wfs3

以下是众所周知的WFS协议和OAPIF之间最重要的区别的非正式快速摘要：

OAPIF基于 REST API
OAPIF必须遵循 OPENAPI 规格
OAPIF支持多种输出格式，但不规定任何输出格式(目前QGIS OAPIF中仅提供GeoJSON和HTML)，并且它使用 content negotiation 确定要向客户端提供哪种格式
JSON和HTML是OAPIF中的一等公民
OAPIF是自我记录的(通过 /api 终端)
OAPIF完全可导航(通过链接)和可浏览

重要

而QGIS中的OGC API功能实现可以利用 MAP 参数来指定项目文件，则OPENAPI规范不允许额外的查询参数。出于这个原因，强烈建议 MAP 未在URL中显示，并且项目文件在环境中通过其他方式指定(即设置 QGIS_PROJECT_FILE 在环境中通过网络服务器重写规则)。

备注

这个 API Endpoint提供了您的服务的所有受支持参数和输出格式的全面文档。下面的段落将只描述最重要的几个。

3.6.1. 资源表示

QGIS服务器中OGC API功能的实现目前支持以下资源表示(输出)格式：

HTML
JSON

实际提供的格式将取决于内容协商，但可以通过向端点附加格式说明符来显式请求特定格式。

支持的格式说明符扩展名为：

.json
.html

其他格式说明符别名可能由特定端点定义：

.openapi ：别名 .json 由 API 终结点
.geojson ：别名 .json 由 Features 和 Feature 端点

3.6.2. 端点

该API提供了客户端可以检索的端点的列表。系统的设计方式是，每个响应都提供一组链接，以便在所有提供的资源中导航。

QGIS实施提供的终结点包括：

名字	路径	描述
登录页	`/`	有关服务的一般信息，并提供指向所有可用端点的链接
合规性	`/conformance`	关于服务符合标准的信息
API	`/api`	服务提供的端点和返回的文档结构的完整描述
收藏	`/collections`	由该服务提供的所有集合(即‘矢量图层’)的列表
集合	`/collections/{collectionId}`	有关集合的信息(名称、元数据、范围等)
功能	`/collections/{collectionId}/items`	集合提供的功能列表
功能	`/collections/{collectionId}/items/{featureId}`	有关单个要素的信息

与WFS-T(事务性Web功能服务)类似，可以添加、更新和删除功能(CRUD)。各个请求在“/api”中进行了说明。

登录页

主端点是 Landing Page 。从该页面可以导航到所有可用的服务端点。这个 Landing Page 必须提供指向

API定义(路径 /api 链接关系 service-desc 和 service-doc ),
一致性声明(路径 /conformance ，链接关系 conformance )，以及
集合(路径 /collections ，链接关系 data )。

../../../_images/server_wfs3_landing_page.png — 图 3.23 服务器OAPIF登录页面

接口定义

这个 API Definition 是对服务提供的API的符合OPENAPI的描述。在其HTML表示形式中，它是一个可浏览的页面，其中准确地列出并记录了所有端点及其响应格式。此端点的路径为 /api 。

API定义提供了服务的全面和权威文档，包括所有支持的参数和返回的格式。

备注

此端点类似于WFS的 GetCapabilities

收藏品列表

集合终结点提供服务中所有可用集合的列表。由于该服务“服务”单个QGIS项目，因此集合是当前项目中的矢量层(如果它们在项目属性中发布为WFS)。此端点的路径为 /collections/ 。

../../../_images/server_wfs3_collections.png — 图 3.24 服务器OAPIF集合列表页面

收集详细信息

虽然集合终结点不提供有关每个可用集合的详细信息，但该信息可在 /collections/{collectionId} 终端。典型信息包括范围、描述、CRSS和其他元数据。

该HTML表示还提供了具有可用功能的可浏览地图。

../../../_images/server_wfs3_collection.png — 图 3.25 服务器OAPIF集合详细信息页

功能列表

此终结点提供知道集合ID的集合中所有要素的列表。此终结点的路径为 /collections/{collectionId}/items 。

该HTML表示还提供了具有可用功能的可浏览地图。

备注

此端点类似于 GetFeature 在WFS 1和WFS 2中。

../../../_images/server_wfs3_features.png — 图 3.26 服务器OAPIF功能列表页面

功能详细信息

此端点提供有关单个要素的所有可用信息，包括要素属性及其几何图形。此端点的路径为 /collections/{collectionId}/items/{itemId} 。

该HTML表示还提供了带有要素几何图形的可浏览地图。

../../../_images/server_wfs3_feature.png — 图 3.27 服务器OAPIF功能详细信息页面

3.6.3. 分页

在OGCAPI中通过以下方式实现对一长串功能的分页 next 和 prev 链接，QGIS服务器通过将 limit 和 offset 作为查询字符串参数。

URL示例：

http://localhost/qgisserver/wfs3/collection_one/items.json?offset=10&limit=10

备注

的最大可接受值 limit 可以使用 QGIS_SERVER_API_WFS3_MAX_LIMIT 服务器配置设置(请参阅：环境变量 )。

3.6.4. 特征过滤

可以通过指定一个或多个筛选器来筛选/搜索集合中可用的功能。

日期和时间过滤器

可以通过指定具有日期和/或日期时间属性的 datetime 查询字符串中的参数。默认情况下，第一个日期/日期时间字段用于筛选。此行为可以通过在 QGIS Server ► Dimension 部分的层属性对话框中。

中详细介绍了日期和时间筛选语法。接口定义除了支持单个值之外，还支持范围(包括开始值和结束值)。

URL示例：

仅返回日期维度匹配的要素 2019-01-01

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01

仅返回日期时间维度匹配的要素 2019-01-01T01:01:01

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01T01:01:01

仅返回日期时间维度在范围内的要素 2019-01-01T01:01:01 - 2019-01-01T12:00:00

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01T01:01:01/2019-01-01T12:00:00

边界框过滤器

边框空间过滤器可以使用 bbox 参数：

逗号分隔元素的顺序为：

左下角，WGS 84经度
左下角，WGS 84纬度
右上角，WGS 84经度
右上角，WGS 84纬度

备注

OGC规范还允许6项BBox说明符，其中第三项和第六项是Z组件，QGIS服务器还不支持这一点。

URL示例：

http://localhost/qgisserver/wfs3/collection_one/items.json?bbox=-180,-90,180,90

如果 CRS 不是边界框的 WGS 84 ，则可以使用可选参数指定不同的CRS bbox-crs 。CRS格式标识符必须位于 OGC URI 格式：

URL示例：

http://localhost/qgisserver/wfs3/collection_one/items.json?bbox=913191,5606014,913234,5606029&bbox-crs=http://www.opengis.net/def/crs/EPSG/9.6.2/3857

3.6.5. 特征排序

方法按字段值对结果集进行排序。 sortby 查询参数。

默认情况下，结果按升序排序。若要按降序对结果进行排序，请使用布尔标志 (sortdesc )可以设置为：

http://localhost/qgisserver/wfs3/collection_one/items.json?sortby=name&sortdesc=1

3.6.6. 属性选择

对象返回的要素属性功能列表通过将逗号分隔的属性名称列表添加到可选的 properties 查询字符串参数。

URL示例：

仅返回 name 属性

http://localhost/qgisserver/wfs3/collection_one/items.json?properties=name

3.6.7. 自定义HTML页

该HTML表示使用一组HTML模板来生成响应。该模板由一个名为 inja 。可以通过覆盖模板来自定义模板(请参阅：模板覆盖 )。模板可以访问可用于的相同数据 JSON 模板可以使用表示法和几个附加功能：

自定义模板函数

path_append( path ) ：将目录路径追加到当前url
path_chomp( n ) ：从当前url路径中删除指定数量的目录组件“n”。
json_dump( ) ：打印传递给模板的JSON数据
static( path ) ：返回指定静态路径的完整URL。例如：“Static(”/Style/Black.css“)”带有根路径“http://localhost/qgisserver/wfs3”将返回“http://localhost/qgisserver/wfs3/static/style/black.css”.
links_filter( links, key, value ) ：从链接列表中返回过滤的链接
content_type_name( content_type ) ：从内容类型返回短名称，例如“Text/html”将返回“html”
nl2br( text ) ：返回所有换行符都被“<br>”标记替换的输入文本
starts_with( string, prefix ) ：如果字符串以提供的字符串前缀开头，则返回TRUE，否则返回FALSE

模板覆盖

模板和静态资产存储在QGIS服务器默认API资源目录的子目录中 (/usr/share/qgis/resources/server/api/ 在Linux系统上)，可以通过更改环境变量来自定义基本目录 QGIS_SERVER_API_RESOURCES_DIRECTORY 。

典型的Linux安装将具有以下目录树：

/usr/share/qgis/resources/server/api/
└── ogc
    ├── schema.json
    ├── static
    │   ├── jsonFormatter.min.css
    │   ├── jsonFormatter.min.js
    │   └── style.css
    └── templates
        └── wfs3
            ├── describeCollection.html
            ├── describeCollections.html
            ├── footer.html
            ├── getApiDescription.html
            ├── getFeature.html
            ├── getFeatures.html
            ├── getLandingPage.html
            ├── getRequirementClasses.html
            ├── header.html
            ├── leaflet_map.html
            └── links.html

要覆盖模板，可以将整个树复制到其他位置和点 QGIS_SERVER_API_RESOURCES_DIRECTORY 到新的地点。

3.6. OGC API功能

3.6.1. 资源表示

3.6.2. 端点

登录页

接口定义

收藏品列表

收集详细信息

功能列表

功能详细信息

3.6.3. 分页

3.6.4. 特征过滤

日期和时间过滤器

边界框过滤器

属性过滤器

3.6.5. 特征排序

3.6.6. 属性选择

3.6.7. 自定义HTML页

自定义模板函数

模板覆盖