3.6. OGC API 피처

OGC API Features (OAPIF) is the first implementation of the new generation of OGC protocols. It is described by the OGC API - Features - Part 1: Core document.

다음 내용은 잘 알려진 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}

단일 피처 관련 정보

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/oapif/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/oapif/collection_one/items.json?datetime=2019-01-01

날짜&시간 차원이 2019-01-01T01:01:01 과 일치하는 피처만 반환

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

날짜 차원이 2019-01-01T01:01:01 ─ 2019-01-01T12:00:00 범위에 들어오는 피처만 반환

http://localhost/qgisserver/oapif/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/oapif/collection_one/items.json?bbox=-180,-90,180,90

경계 상자의 좌표계가 WGS 84 가 아닌 경우, 부가적인 bbox-crs 파라미터를 사용해서 다른 좌표계를 지정할 수 있습니다. 이때 좌표계 식별자 서식은 OGC URI 에 있는 서식이어야만 합니다.

URL 예시:

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

속성 필터

속성 필터와 경계 상자 필터를 결합할 수 있습니다. 속성 필터의 일반적인 서식은 <attribute name>=<attribute value> 입니다. AND 연산자를 사용해서 여러 필터를 결합할 수 있습니다.

URL 예시:

name 속성이 “my value” 와 동일한 모든 피처를 필터링

http://localhost/qgisserver/oapif/collection_one/items.json?attribute_one=my%20value

* (“star”) 연산자를 사용하는 부분 일치도 지원합니다:

URL 예시:

name 속성이 “value” 로 끝나는 모든 피처를 필터링

http://localhost/qgisserver/oapif/collection_one/items.json?attribute_one=*value

3.6.5. 객체 정렬

sortby 쿼리 파라미터를 사용하면 필드값으로 설정된 산출물을 정렬할 수 있습니다.

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

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

3.6.6. 속성 선택

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

URL 예시:

name 속성만 반환

http://localhost/qgisserver/oapif/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/oapif” 인 “static( “/style/black.css” )” 는 “http://localhost/qgisserver/oapif/static/style/black.css” 를 반환할 것입니다.

  • links_filter( links, key, value ): 링크 목록에서 필터링한 링크를 반환합니다.

  • content_type_name( content_type ): 내용 유형으로부터 약칭을 반환합니다. 예를 들어 “text/html” 은 “HTML” 을 반환할 것입니다.

  • nl2br( text ): Returns the input text with all newlines replaced by “<br>” tags

템플릿 무시

템플릿과 정적 자산(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 환경 변수가 새 위치를 가리키도록 변경하십시오.