3.6. OGC API 피처

OAPIF(OGC API Features)는 신세대 OGC 프로토콜을 처음으로 구현한 것입니다. OGC API ─ 피처 ─ 1부: 핵심 문서에 잘 설명되어 있습니다.

일반적으로 설치했을 경우, http://localhost/qgisserver/wfs3 주소를 통해 API에 접근할 수 있습니다.

다음 내용은 잘 알려진 WFS 프로토콜과 OAPIF의 주요 차이점을 비공식적으로 간단히 요약한 것입니다:

OAPIF는 REST API를 기반으로 합니다.
OAPIF API는 OPENAPI 사양을 따라야만 합니다.
OAPIF는 여러 산출물 포맷을 지원하지만 어느 포맷도 강제하지 않으며 (QGIS OAPIF는 현재 GeoJSON과 HTML만 지원합니다) 클라이언트에 서비스할 포맷을 결정하는 데 내용 협상(content negotiation) 을 사용합니다.
JSON과 HTML은 OAPIF의 일급 객체(first class citizen)입니다.
OAPIF는 (/api 종단점을 통해) 자체 문서화(self-documenting)합니다.
OAPIF를 (링크를 통해) 완전하게 둘러보고 또 탐색할 수 있습니다.

중요

QGIS에 구현된 OGC API 피처는 프로젝트 파일을 지정하는 데 MAP 파라미터를 사용할 수 있지만, OPENAPI 사양으로 인해 다른 추가 파라미터를 사용할 수는 없습니다. 때문에 URL에 MAP 을 노출시키지 말고, 해당 환경에서 다른 방법으로 (예를 들어 웹 서버 고쳐쓰기 규칙을 통해 해당 환경에 QGIS_PROJECT_FILE 을 설정해서) 프로젝트 파일을 지정할 것을 강력히 추천합니다.

참고

API 종단점은 사용자 서비스가 지원하는 모든 파라미터 및 산출물 포맷의 포괄적인 기록을 지원합니다. 다음은 그 가운데 가장 중요한 것들만 설명한 것입니다.

3.6.1. 리소스 표현

QGIS 서버에 구현된 OGC API 피처는 현재 다음과 같은 리소스 표현(산출물) 포맷을 지원합니다:

HTML
JSON

실제로 서비스되는 포맷은 내용 협상에 좌우될 것이지만, 종단점에 포맷 지정자를 추가해서 특정 포맷을 명확하게 요청할 수 있습니다.

다음과 같은 포맷 지정자 확장자를 지원합니다:

.json
.html

특정 종단점이 포맷 지정자의 추가적인 별명을 정의할 수도 있습니다:

.openapi: API 종단점이 지원하는 .json 의 별명
.geojson: Features 및 Feature 종단점이 지원하는 .json 의 별명

3.6.2. 종단점(Endpoint)

API는 클라이언트가 검색할 수 있는 종단점 목록을 제공합니다. 이 시스템은 모든 응답이 모든 제공 리소스를 탐색할 수 있는 링크 집합을 제공하도록 설계되었습니다.

QGIS에 구현된 종단점 포인트는 다음과 같습니다:

이름	경로	설명
Landing Page	`/`	서비스에 대한 일반 정보와 사용할 수 있는 모든 종단점을 가리키는 링크를 제공
Conformance	`/conformance`	표준에 대한 서비스의 적합성 정보
API	`/api`	서비스가 제공하는 종단점에 대한 전체 설명과 반환된 문서의 구조
Collections	`/collections`	서비스가 제공하는 모든 선택 집합(예: ‘vector layers’)의 목록
Collection	`/collections/{collectionId}`	선택 집합 관련 정보 (이름, 메타데이터, 범위 등등)
Features	`/collections/{collectionId}/items`	선택 집합이 제공하는 피처의 목록
Feature	`/collections/{collectionId}/items/{featureId}`	단일 피처 관련 정보

WFS-T(트랜잭션을 통한 웹 피처 서비스)와 비슷하게, OAPIF는 피처를 CRUD(생성, 읽기, 업데이트, 삭제)할 수 있습니다. CRUD 각각의 요청에 대해서는 “/api” 에서 설명하고 있습니다.

Landing Page

주 종단점은 Landing Page 입니다. 해당 페이지에서 사용할 수 있는 모든 서비스 종단점으로 탐색해 갈 수 있습니다. 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 와 유사합니다.

Collections 목록

Collections 종단점은 서비스에서 사용할 수 있는 모든 선택 집합의 목록을 제공합니다. 서비스가 단일 QGIS 프로젝트를 “서비스” 하기 때문에, 선택 집합은 (프로젝트 속성에서 벡터 레이어를 WFS로 게시한 경우) 현재 프로젝트의 벡터 레이어들입니다. 이 종단점의 경로는 /collections/ 입니다.

../../../_images/server_wfs3_collections.png — 그림 3.24 서버 OAPIF 선택 집합 목록 페이지

Collection 상세 정보

Collections 종단점이 사용할 수 있는 각 선택 집합에 대한 자세한 정보를 제공하지 않는 반면, /collections/{collectionId} 종단점에서는 해당 정보를 사용할 수 있습니다. 이 정보는 전형적으로 범위, 설명, 좌표계 및 기타 메타데이터를 포함합니다.

이 HTML 표현은 사용할 수 있는 피처를 보유한 탐색 가능한 맵도 제공합니다.

../../../_images/server_wfs3_collection.png — 그림 3.25 서버 OAPIF 선택 집합 상세 정보 페이지

Features 목록

이 종단점은 ID를 알고 있는 선택 집합에 있는 모든 피처의 목록을 제공합니다. 이 종단점의 경로는 /collections/{collectionId}/items 입니다.

이 HTML 표현은 사용할 수 있는 피처를 보유한 탐색 가능한 맵도 제공합니다.

참고

이 종단점은 WFS1 및 WFS2의 GetFeature 와 유사합니다.

../../../_images/server_wfs3_features.png — 그림 3.26 서버 OAPIF 피처 목록 페이지

Feature 상세 정보

이 종단점은 단일 피처에 대해 피처 속성과 도형을 포함하는, 사용할 수 있는 모든 정보를 제공합니다. 이 종단점의 경로는 /collections/{collectionId}/items/{itemId} 입니다.

이 HTML 표현은 피처 도형을 보유한 탐색 가능한 맵도 제공합니다.

../../../_images/server_wfs3_feature.png — 그림 3.27 서버 OAPIF 피처 상세 정보 페이지

3.6.3. 페이지 번호 매기기

OGC API에서 피처의 긴 목록에 페이지 번호를 메기는 기능(pagination)은 next 및 prev 링크를 통해 구현되어 있습니다. QGIS 서버는 limit 및 offset 을 쿼리 문자열 파라미터로 추가해서 이 링크들을 구성합니다.

URL 예시:

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

참고

QGIS_SERVER_API_WFS3_MAX_LIMIT 서버 환경 설정으로 limit 의 최대 허용 값의 환경을 설정할 수 있습니다. (환경 변수 참조)

3.6.4. 객체 필터링

하나 이상의 필터를 지정해서 선택 집합에서 사용할 수 있는 피처를 필터링/검색할 수 있습니다.

날짜 및 시간 필터

쿼리 문자열에 datetime 인자를 지정하면 날짜 그리고/또는 날짜&시간 속성을 가진 선택 집합을 필터링할 수 있습니다. 필터링 작업에 첫 번째 날짜/날짜&시간 필드를 기본적으로 이용합니다. 레이어 속성 대화창의 QGIS Server ► 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 사양은 경계 상자 파라미터의 값을 6개 항목으로 지정하는 일도 지원합니다. 이때 세 번째와 여섯 번째는 Z 요소인데, QGIS 서버가 아직 지원하지 않고 있습니다.

URL 예시:

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

경계 상자의 좌표계가 WGS 84 가 아닌 경우, 부가적인 bbox-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 쿼리 파라미터를 사용하면 필드값으로 설정된 산출물을 정렬할 수 있습니다.

산출물은 기본적으로 오름차순으로 정렬됩니다. 산출물을 내림차순으로 정렬하려면, 불(boolean) 플래그(sortdesc)를 설정하면 됩니다:

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

3.6.6. 속성 선택

부가적인 properties 쿼리 문자열 인자에 쉼표로 구분한 속성명 목록을 추가하면 Features 목록 호출이 반환하는 피처 속성을 제한할 수 있습니다.

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 전체를 지정한 정적 경로로 반환합니다. 예를 들면: 루트 경로가 “http://localhost/qgisserver/wfs3” 인 “static( “/style/black.css” )” 는 “http://localhost/qgisserver/wfs3/static/style/black.css” 를 반환할 것입니다.
links_filter( links, key, value ): 링크 목록에서 필터링한 링크를 반환합니다.
content_type_name( content_type ): 내용 유형으로부터 약칭을 반환합니다. 예를 들어 “text/html” 은 “HTML” 을 반환할 것입니다.
nl2br( text ): 입력 텍스트의 모든 새줄 문자(newline)를 “<br>” 태그로 치환해서 반환합니다.
starts_with( string, prefix ): 문자열이 지정한 문자열 접두어로 시작하는 경우 참을, 그렇지 않은 경우 거짓을 반환합니다.

템플릿 무시

템플릿과 정적 자산(asset)은 QGIS 서버의 기본 API 리소스 디렉터리(리눅스 시스템의 경우 /usr/share/qgis/resources/server/api/)의 하위 디렉터리에 저장되는데, QGIS_SERVER_API_RESOURCES_DIRECTORY 환경 변수를 변경하면 기본 디렉터리를 사용자 지정할 수 있습니다.

전형적인 리눅스 설치는 다음과 같은 디렉터리 트리를 가지게 될 것입니다:

/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. 종단점(Endpoint)

Landing Page

API 정의

Collections 목록

Collection 상세 정보

Features 목록

Feature 상세 정보

3.6.3. 페이지 번호 매기기

3.6.4. 객체 필터링

날짜 및 시간 필터

경계 상자 필터

속성 필터

3.6.5. 객체 정렬

3.6.6. 속성 선택

3.6.7. HTML 페이지 사용자 정의

사용자 지정 템플릿 함수

템플릿 무시