3.6. OGC API機能

OGC API Features（OAPIF）は、新世代のOGCプロトコルの最初の実装です。これは OGC API - Features - Part 1：コアドキュメントで説明されています。

一般的なインストールでは、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 Features の実装では、プロジェクトファイルを指定するために MAP パラメータを活用することができますが、OPENAPI 仕様では余分なクエリパラメータを使用することはできません。このため、MAP を URL で公開せず、他の方法（例えば、ウェブサーバの書き換えルールで QGIS_PROJECT_FILE を環境に設定する）でプロジェクトファイルを指定することを強く推奨します。

注釈

API エンドポイントは、サポートされているすべてのパラメータとサービスの出力形式に関する包括的なドキュメントを提供します。以下の段落では、最も重要なもののみを説明します。

3.6.1. リソース表現

QGIS ServerにおけるOGC API Featuresの実装は、現在、以下のリソース表現（出力）形式をサポートしています：

HTML
JSON

実際に提供される形式はコンテント・ネゴシエーションに依存しますが、エンドポイントにフォーマット指定子を付加することで、特定の形式を明示的に要求することができます。

サポートされているフォーマット指定子の拡張子：

.json
.html

追加のフォーマット指定子エイリアスは、特定のエンドポイントによって定義されることができます：

.openapi: API エンドポイントがサポートする .json のエイリアス
.geojson: Features 及び Feature エンドポイントがサポートする .json のエイリアス

3.6.2. エンドポイント

APIは、クライアントが取得できるエンドポイントのリストを提供します。システムは、すべてのレスポンスが、提供されたすべてのリソースをナビゲートするためのリンクのセットを提供するように設計されています。

QGISの実装によって提供されるエンドポイント・ポイントは以下のものです：

名前	パス	説明
Landing Page	`/`	サービスに関する一般的な情報と、利用可能なすべてのエンドポイントへのリンクを提供します。
Conformance	`/conformance`	サービスの規格適合性に関する情報
API	`/api`	サービスによって提供されるエンドポイントの完全な説明と、返された文書の構造
Collections	`/collections`	サービスが提供するすべてのコレクション（すなわち「ベクタレイヤ」）のリスト
Collection	`/collections/{collectionId}`	コレクションに関する情報（名前、メタデータ、範囲など）
Features	`/collections/{collectionId}/items`	コレクションが提供する地物のリスト
Feature	`/collections/{collectionId}/items/{featureId}`	単独地物に関する情報

WFS-T (transactional Web Feature Service)と同様に、地物の追加、更新、削除(CRUD)が可能です。それぞれのリクエストは "/api" に記述されています。

Landing Page

主なエンドポイントは ランディングページ です。このページから、利用可能なすべてのサービス・エンドポイントに移動することができます。ランディング・ページ は、以下へのリンクを提供しなければなりません

API定義（パス /api リンクリレーション service-desc 及び service-doc）、
適合性宣言（パス /conformance、リンクリレーション conformance）、及び
コレクション（パス /collections, リンクリレーション data）。

../../../_images/server_wfs3_landing_page.png — 図 3.23 サーバーのOAPIFランディングページ

API定義

API定義 は、サービスが提供するAPIのOPENAPI準拠の記述です。HTML表現においては、すべてのエンドポイントとそのレスポンスフォーマットが正確にリスト化、文書化されたブラウズ可能なページです。このエンドポイントのパスは /api です。

API定義は、サポートされる全てのパラメータと返されるフォーマットを含む、サービスの包括的で権威ある文書を提供します。

注釈

このエンドポイントはWFSの GetCapabilities に類似しています

コレクションのリスト

コレクションエンドポイントは、サービスで利用可能な全てのコレクションのリストを提供します。そのサービスはひとつのQGISプロジェクトに「サービスを提供する」ため、コレクションは現在のプロジェクトのベクタレイヤになります（プロジェクトのプロパティでWFSとして公開されている場合）。このエンドポイントのパスは /collections/ です。

../../../_images/server_wfs3_collections.png — 図 3.24 サーバーのOAPIFコレクションリストページ

コレクションの詳細

コレクションエンドポイントは利用可能な各コレクションの詳細情報を提供しませんが、その情報は ``/collections/{collectionId}` エンドポイントで利用可能です。典型的な情報には、範囲、説明、CRS、その他のメタデータが含まれます。

また、そのHTML表現は、利用可能な地物を持った閲覧可能な地図も提供されます。

../../../_images/server_wfs3_collection.png — 図 3.25 サーバーのOAPIFコレクションの詳細ページ

地物のリスト

このエンドポイントは、コレクション ID がわかっているコレクション内の全ての地物のリストを提供します。このエンドポイントのパスは /collections/{collectionId}/items です。

また、そのHTML表現は、利用可能な地物を持った閲覧可能な地図も提供されます。

注釈

このエンドポイントは、WFS 1 と WFS 2 の GetFeature に類似しています。

../../../_images/server_wfs3_features.png — 図 3.26 サーバーのOAPIF地物のリストページ

地物の詳細

このエンドポイントは、地物の属性やジオメトリなど、1 つの地物に関する全ての情報を提供します。このエンドポイントのパスは /collections/{collectionId}/items/{itemId} です。

また、そのHTML表現は、地物ジオメトリを含むブラウズ可能な地図も提供されます。

../../../_images/server_wfs3_feature.png — 図 3.27 サーバーのOAPIF地物の詳細ページ

3.6.3. ページ付け

地物の長いリストのページ付けはOGC APIで 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 サーバー設定で設定することができます（qgis-server-envar を参照してください）。

3.6.4. 地物フィルタリング

コレクションで利用可能な地物は、1 つ以上のフィルタを指定してフィルタ/検索できます。

日付と時間フィルタ

クエリ文字列の引数に datetime を指定することで、日付や日付時刻属性を持つコレクションをフィルタすることができます。デフォルトでは、最初のdate/datetimeフィールドがフィルタに使用されます。この動作は、レイヤプロパティダイアログの QGISサーバー ► Dimension セクションで "Date" または "Time" 次元を設定することで設定できます。

日付と時刻のフィルタ構文は API定義に完全に記述されており、単一の値だけでなく範囲 (開始値と終了値が含まれます) も対応しています。

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仕様では、3番目と6番目の項目がZ成分となる6項目のbbox指定子も認められていますが、QGISサーバーではまだサポートされていません。

URLの例:

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

バウンディングボックスの CRS が WGS 84 でない場合、オプションのパラメータ bbox-crs を使って別の 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 ): content typeから短い名前を返します。例 "text/html" は "HTML" を返します
nl2br( text ): 入力テキストから改行をすべて "<br>" タグに置き換えたものを返します
starts_with( string, prefix ): 文字列が指定された文字列プレフィックスで始まっていれば真を、そうでなければ偽を返します

テンプレートのオーバーライド

テンプレートと静的アセットはQGISサーバーのデフォルトのAPIリソースディレクトリのサブディレクトリ(Linuxシステムの場合 /usr/share/qgis/resources/server/api/)に保存され、ベースディレクトリは環境変数 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. エンドポイント

Landing Page

API定義

コレクションのリスト

コレクションの詳細

地物のリスト

地物の詳細

3.6.3. ページ付け

3.6.4. 地物フィルタリング

日付と時間フィルタ

バウンディングボックスフィルタ

属性フィルタ

3.6.5. 地物の並び替え

3.6.6. 属性の選択

3.6.7. HTMLページをカスタマイズする

カスタムテンプレート関数

テンプレートのオーバーライド