3. 서비스

QGIS 서버는 OGC(Open Geospatial Consortium) 가 개발한 표준 프로토콜에 따라 데이터를 서비스할 수 있습니다:

  • WMS 1.1.1 및 1.3.0

  • WFS 1.0.0 및 1.1.0

  • OGC API - Features (WFS3)

  • WCS 1.1.1

  • WMTS 1.0.0

QGIS 렌더링 엔진은 본래의 표준 프로토콜은 물론, 그 습성을 사용자 지정할 수 있는 가능성을 크게 확장시켜주는 몇몇 상용 제품의 파라미터 및 요청을 지원합니다.

3.1. WMS(웹 맵 서비스)

QGIS 서버에 구현된 WMS 1.1.1 및 1.3.0 표준은 QGIS 프로젝트로부터 생성된 맵 또는 범례 이미지를 요청할 수 있는 HTTP 인터페이스를 제공합니다. 전형적인 WMS 요청은 사용할 QGIS 프로젝트, 렌더링할 레이어는 물론 생성할 이미지 포맷도 정의합니다. SLD(Styled Layer Descriptor) 사용도 기본으로 지원합니다.

사양:

QGIS 서버가 제공하는 표준 요청:

요청

설명

GetCapabilities

서버에 대한 정보를 담은 XML 메타데이터를 반환합니다.

GetMap

맵을 반환합니다.

GetFeatureInfo

픽셀 위치에 대한 데이터(도형 및 값)를 검색합니다.

GetLegendGraphics

범례 심볼을 반환합니다.

QGIS 서버가 제공하는 상용 제품 요청:

요청

설명

GetPrint

QGIS 조판을 반환합니다.

GetProjectSettings

QGIS 서버에 대한 특정 정보를 반환합니다.

3.1.1. GetMap

OGC WMS 1.1.1 및 1.3.0 사양에 따른 GetMap 요청용 표준 파라미터:

파라미터

필수 여부

설명

SERVICE

○

서비스(WMS)의 명칭

VERSION

○

서비스의 버전

REQUEST

○

요청(GetMap)의 명칭

LAYERS

Ｘ

표시할 레이어

STYLES

Ｘ

레이어의 스타일

SRS / CRS

○

좌표계

BBOX

○

맵 범위

WIDTH

○

이미지의 픽셀 단위 너비

HEIGHT

○

이미지의 픽셀 단위 높이

FORMAT

Ｘ

이미지 포맷

TRANSPARENT

Ｘ

투명한 배경

SLD

Ｘ

스타일 작업에 쓰이는 SLD의 URL

SLD_BODY

Ｘ

스타일 작업에 사용될 인라인(In-line) SLD(XML)

표준 파라미터 이외에도, QGIS 서버는 다음과 같은 추가 파라미터를 지원합니다:

파라미터

필수 여부

설명

MAP

○

QGIS 프로젝트 파일을 지정합니다.

BGCOLOR

Ｘ

배경 색상을 지정합니다.

DPI

Ｘ

출력물의 해상도를 지정합니다.

IMAGE_QUALITY

Ｘ

JPEG 압축

OPACITIES

Ｘ

레이어 또는 레이어 그룹의 투명도

FILTER

Ｘ

피처의 하위집합

SELECTION

Ｘ

피처를 강조합니다.

FILE_NAME

Ｘ

다운로드한 파일의 파일명

FORMAT=application/dxf 파라미터 사용시에만 쓰입니다.

FORMAT_OPTIONS

Ｘ

지정한 파일 포맷의 옵션들

FORMAT=application/dxf 파라미터 사용시에만 쓰입니다.

TILED

Ｘ

타일 모드 로 작동합니다.

URL 예시:

http://localhost/qgis_server?
SERVICE=WMS
&VERSION=1.3.0
&REQUEST=GetMap
&MAP=/home/qgis/projects/world.qgs
&LAYERS=mylayer1,mylayer2,mylayer3
&STYLES=style1,default,style3
&OPACITIES=125,200,125
&CRS=EPSG:4326
&WIDTH=400
&HEIGHT=400
&FORMAT=image/png
&TRANSPARENT=TRUE
&DPI=300
&TILED=TRUE

SERVICE

이 파라미터는 WMS 이어야 합니다.

다음은 예시입니다:

http://localhost/qgisserver?
SERVICE=WMS
&...

VERSION

이 파라미터는 사용할 서비스의 버전을 지정할 수 있습니다. VERSION 파라미터가 사용할 수 있는 값은 다음과 같습니다:

  • 1.1.1

  • 1.3.0

버전 번호에 따라, 다음 파라미터의 사용 방법이 조금씩 달라집니다. 이에 대해서는 차후 설명하겠습니다:

  • CRS / SRS

  • BBOX

REQUEST

GetMap 요청의 경우, 이 파라미터는 GetMap 이어야 합니다.

LAYERS

이 파라미터는 맵 상에 표시할 레이어를 지정할 수 있습니다. 레이어명을 쉼표로 구분해야 합니다.

이에 더해, QGIS 서버는 레이어를 다음을 통해 선택할 수 있는 옵션을 제공합니다:

  • 약칭(short name)

  • 레이어 ID

레이어 메뉴의 Properties ► Metadata 를 통해 레이어의 약칭을 설정할 수도 있습니다. 약칭을 정의한 경우, 레이어명 대신 약칭을 기본으로 사용할 것입니다:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&LAYERS=mynickname1,mynickname2
&...

이에 더해, Project ► Properties… 대화창의 OWS Server ► WMS capabilities 메뉴에서 레이어 ID로 레이어를 선택할 수 있는 프로젝트 수준 옵션도 있습니다. 이 옵션을 활성화하려면, |checkbox| Use layer ids as names 를 체크하십시오.

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&LAYERS=mylayerid1,mylayerid2
&...

STYLES

렌더링 단계에서 어떤 레이어 스타일을 사용할지 지정하는 데 이 파라미터를 사용할 수 있습니다. 스타일을 쉼표로 구분해야 합니다. 기본 스타일의 명칭은 default 입니다.

SRS / CRS

SRS 파라미터는 WMS 1.1.1 에서 맵 출력물의 좌표계를 나타낼 수 있으며, EPSG:XXXX 같은 서식이어야 합니다. 현재 버전이 1.1.1 이라면 CRS 도 지원한다는 사실을 기억하십시오.

WMS 1.3.0 의 경우, CRS 파라미터가 선호되지만 SRS 도 지원합니다.

요청에서 CRS 와 SRS 파라미터 둘 다 사용한 경우, VERSION 파라미터에서 지정한 현재 버전을 우선합니다.

다음 예시에서는, VERSION 파라미터 값이 무엇이든 SRS 파라미터를 사용합니다. CRS 가 없기 때문입니다:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&VERSION=1.3.0
&SRS=EPSG:2854
&...

다음 예시에서는, VERSION 파라미터 값 때문에 CRS 대신 SRS 파라미터를 사용합니다:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&VERSION=1.1.1
&CRS=EPSG:4326
&SRS=EPSG:2854
&...

다음 예시에서는, VERSION 파라미터 값 때문에 SRS 대신 CRS 파라미터를 사용합니다:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&VERSION=1.3.0
&CRS=EPSG:4326
&SRS=EPSG:2854
&...

BBOX

이 파라미터는 맵 범위를 현재 좌표계의 단위로 지정할 수 있습니다. 좌표를 쉼표로 구분해야 합니다.

BBOX 파라미터는 min_a,min_b,max_a,max_b 와 같은 서식이지만 a 와 b 축의 정의는 현재 VERSION 파라미터에 따라 달라집니다:

  • WMS 1.1.1 에서는 축의 순서가 언제나 동/북입니다.

  • WMS 1.3.0 에서는 축의 순서가 좌표계 기관(CRS authority)을 따릅니다.

예를 들면 EPSG:4326 과 WMS 1.1.1 인 경우, a 가 경도(동)이고 b 는 위도(북)이기 때문에 요청이 다음과 같이 보입니다:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&VERSION=1.1.1
&SRS=epsg:4326
&BBOX=-180,-90,180,90
&...

그러나 WMS 1.3.0 인 경우, EPSG 데이터베이스에 정의된 축의 순서가 북/동이기 때문에 a 가 위도이고 b 는 경도가 됩니다:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&VERSION=1.3.0
&CRS=epsg:4326
&BBOX=-90,-180,90,180
&...

WIDTH

이 파라미터는 출력 이미지의 너비를 픽셀 단위로 지정할 수 있습니다.

HEIGHT

이 파라미터는 출력 이미지의 높이를 픽셀 단위로 지정할 수 있습니다.

FORMAT

이 파라미터는 맵 이미지의 포맷을 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다:

  • jpg

  • jpeg

  • image/jpeg

  • image/png

  • image/png; mode=1bit

  • image/png; mode=8bit

  • image/png; mode=16bit

  • application/dxf: WFS 서비스에서 읽기 접근 권한이 있는 레이어만 DXF 포맷으로 내보냅니다.

    URL 예시:

    http://localhost/qgisserver?
SERVICE=WMS&VERSION=1.3.0
&REQUEST=GetMap
&FORMAT=application/dxf
&LAYERS=Haltungen,Normschacht,Spezialbauwerke
&STYLES=
&CRS=EPSG%3A21781&BBOX=696136.28844801,245797.12108743,696318.91114315,245939.25832905
&WIDTH=1042
&HEIGHT=811
&FORMAT_OPTIONS=MODE:SYMBOLLAYERSYMBOLOGY;SCALE:250&FILE_NAME=plan.dxf

TRANSPARENT

이 불(boolean) 파라미터는 배경 투명도를 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다(대소문자 구분 안 함):

  • TRUE

  • FALSE

하지만, FORMAT 파라미터가 나타내는 맵 이미지의 포맷이 PNG가 아닌 경우 이 파라미터를 무시합니다.

MAP

이 파라미터는 사용할 QGIS 프로젝트 파일을 정의할 수 있습니다.

GetMap 파라미터 표 에서 언급한 것처럼, MAP 파라미터는 필수입니다. 요청이 제대로 작동하려면 QGIS 프로젝트가 필요하기 때문입니다. 하지만 QGIS_PROJECT_FILE 환경 변수를 사용해서 기본 QGIS 프로젝트를 정의할 수도 있습니다. 이런 특정한 경우에만, MAP 이 필수 파라미터가 아니게 됩니다. 더 자세한 내용은 고급 환경 설정 을 참조하세요.

BGCOLOR

이 파라미터는 맵 이미지의 배경 색상을 지정할 수 있습니다. 하지만 PNG 이미지인 경우, TRANSPARENT 파라미터와 결합해서 사용할 수 없습니다. (투명을 더 우선하기 때문입니다.) 일반적인 색상명을 사용할 수도 있고, 십육진법으로 표기할 수도 있습니다.

일반적인 표기법을 사용한 URL 예시:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&VERSION=1.3.0
&BGCOLOR=green
&...

십육진법 표기법을 사용한 URL 예시:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&VERSION=1.3.0
&BGCOLOR=0x00FF00
&...

DPI

이 파라미터는 요청한 출력물의 해상도를 지정할 수 있습니다.

IMAGE_QUALITY

이 파라미터는 JPEG 이미지 전용입니다. JPEG 압축 기본값은 -1 입니다.

Project ► Properties… 대화창의 OWS Server ► WMS capabilities 메뉴에서 이 기본값을 QGIS 프로젝트 별로 변경할 수 있습니다. GetMap 요청에서 이 파라미터를 무시하고 싶은 경우 IMAGE_QUALITY 파라미터를 사용하면 됩니다.

OPACITIES

불투명도 값들을 쉼표로 구분한 목록. 레이어 또는 레이어 그룹 수준에서 불투명도를 설정할 수 있습니다. 0(완전히 투명)에서 255(완전히 불투명)까지의 범위에서 값을 정의할 수 있습니다.

FILTER

FILTER 파라미터를 통해 레이어의 하위 집합을 선택할 수 있습니다. 문법은 QGIS 하위 집합 문자열과 기본적으로 동일합니다. 하지만, QGIS 서버를 통해 데이터베이스에 SQL 삽입(injection)이 일어나는 일을 막기 위한 몇몇 제약 조건이 있습니다. 파라미터에서 위험한 문자열이 발견될 경우, QGIS 서버는 다음 오류를 반환할 것입니다:

<ServiceExceptionReport>
  <ServiceException code="Security">The filter string XXXXXXXXX has been rejected because of security reasons.
  Note: Text strings have to be enclosed in single or double quotes. A space between each word / special character is mandatory.
  Allowed Keywords and special characters are IS,NOT,NULL,AND,OR,IN,=,<,=<,>,>=,!=,',',(,),DMETAPHONE,SOUNDEX.
  Not allowed are semicolons in the filter expression.</ServiceException>
</ServiceExceptionReport>

URL 예시:

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&LAYERS=mylayer1,mylayer2,mylayer3
&FILTER=mylayer1:"col1";mylayer1,mylayer2:"col2" = 'blabla'
&...

이 예시에서 mylayer1 및 mylayer2 양쪽에 동일한 필터(col2 필드는 blabla 문자열과 동등합니다)가 적용되는 반면, col1 필드에 대한 필터는 mylayer1 레이어에만 적용됩니다.

참고

FILTER 파라미터가 존재하는 경우 GetFeatureInfo 를 통해 속성을 검색할 수 있고 X/Y 파라미터를 생략할 수도 있습니다. 그러면 QGIS 서버가 일치하는 피처에 관한 정보를 반환하고 결합된 경계 상자를 XML 출력물 형태로 생성할 것입니다.

SELECTION

SELECTION 파라미터는 하나 이상의 레이어에서 피처를 강조시킬 수 있습니다. 피처 ID를 쉼표로 구분한 목록을 전송하면 벡터 피처를 선택할 수 있습니다.

http://localhost/qgisserver?
SERVICE=WMS
&REQUEST=GetMap
&LAYERS=mylayer1,mylayer2
&SELECTION=mylayer1:3,6,9;mylayer2:1,5,6
&...

다음 그림은, 예를 들어 http://myserver.com/...&SELECTION=countries:171,65 처럼, SELECTION 파라미터를 사용한 GetMap 요청이 반환한 응답의 예시입니다.

소스 데이터셋에서 파라미터의 피처 ID에 해당하는 프랑스 와 루마니아 가 노란색으로 강조돼 있습니다.

../../_images/server_selection_parameter.png

그림 3.1 SELECTION 파라미터를 사용한 GetMap 요청에 대한 서버의 응답

FORMAT-OPTIONS

선택한 포맷을 위한 옵션들을 지정하는 데 이 파라미터를 사용할 수 있습니다. FORMAT=application/dxf 전용입니다. 쌍반점으로 구분한 키:값 쌍의 목록입니다:

  • SCALE: 심볼 규칙, 필터, 스타일용으로 사용됩니다. (데이터를 실제로 크기 조정하지는 않습니다. 데이터는 원본 척도로 유지됩니다.)

  • MODE: QGIS 데스크탑 DXF 내보내기 대화창에서 지정하는 내보내기 옵션에 대응합니다. NOSYMBOLOGY, FEATURESYMBOLOGY 및 SYMBOLLAYERSYMBOLOGY 값을 사용할 수 있습니다.

  • LAYERSATTRIBUTES: DXF 레이어명을 위한 값을 담고 있는 필드를 지정합니다 ─ 지정하지 않을 경우, 원본 QGIS 레이어명을 사용합니다.

  • USE_TITLE_AS_LAYERNAME: 이 파라미터를 사용하면, 레이어의 제목을 레이어명으로 사용할 것입니다.

  • CODEC: 인코딩에 사용할 코덱을 지정합니다. 기본값은 ISO-8859-1 입니다. QGIS 데스크탑 DXF 내보내기 대화창에서 사용할 수 있는 유효한 값을 찾아보십시오.

  • NO_MTEXT: 라벨에 MTEXT 대신 TEXT를 사용합니다.

  • FORCE_2D: 산출물을 2D로 강제합니다. 폴리라인 너비를 지정하려면 이 옵션이 필수입니다.

TILED

성능 향상을 위해 QGIS 서버를 타일 모드로 사용할 수 있습니다. 이 모드에서, 클라이언트는 몇 개의 조그만 고정 크기 타일을 요청해서 조립하여 전체 맵을 만듭니다. 이 과정에서 두 타일 사이의 경계선 위 또는 가까이 있는 심볼이 잘린 것으로 보일 수도 있습니다. 심볼이 두 타일 가운데 하나에만 존재하기 때문입니다.

TILED 파라미터를 TRUE 로 설정하면 QGIS 서버가 타일 모드로 작동해서, QGIS 프로젝트에서 환경 설정한 타일 버퍼 를 적용합니다. (사용자 프로젝트 환경 설정하기 를 참조하세요.)

TILED 가 TRUE 이고 QGIS 프로젝트에서 타일 버퍼를 0이 아닌 값으로 환경 설정했다면, 타일 경계선에서 심볼이 잘리는 일을 피하기 위해 타일 범위 바깥에 있는 피처를 렌더링합니다.

TILED 파라미터의 기본값은 FALSE 입니다.

3.1.2. GetFeatureInfo

OGC WMS 1.1.1 및 1.3.0 사양에 따른 GetFeatureInfo 요청용 표준 파라미터:

파라미터

필수 여부

설명

SERVICE

○

서비스(WMS)의 명칭

VERSION

Ｘ

서비스의 버전

REQUEST

○

요청(GetFeatureInfo)의 명칭

QUERY_LAYERS

○

쿼리할 레이어

LAYERS

○

표시할 레이어 (QUERY_LAYERS 와 동일)

STYLES

Ｘ

레이어의 스타일

SRS / CRS

○

좌표계

BBOX

Ｘ

맵 범위

WIDTH

○

이미지의 픽셀 단위 너비

HEIGHT

○

이미지의 픽셀 단위 높이

TRANSPARENT

Ｘ

투명한 배경

INFO_FORMAT

Ｘ

출력물 포맷

FEATURE_COUNT

Ｘ

반환할 피처의 최대 개수

I

Ｘ

쿼리할 포인트의 픽셀 열

X

Ｘ

I 파라미터와 동일 (WMS 1.1.1 용)

J

Ｘ

쿼리할 포인트의 픽셀 행

Y

Ｘ

J 파라미터와 동일 (WMS 1.1.1 용)

WMS_PRECISION

Ｘ

도형 반환시 사용할 정밀도(소수점 이하 자릿수). (객체 요청에 도형을 추가하는 방법 을 참조하세요.) 기본값은 -1 로, 프로젝트에서 정의한 정밀도를 사용한다는 뜻입니다.

표준 파라미터 이외에도, QGIS 서버는 다음과 같은 추가 파라미터를 지원합니다:

파라미터

필수 여부

설명

MAP

○

QGIS 프로젝트 파일을 지정합니다.

FILTER

Ｘ

피처의 하위집합

FI_POINT_TOLERANCE

Ｘ

포인트 레이어의 픽셀 단위 허용 오차

FI_LINE_TOLERANCE

Ｘ

라인 레이어의 픽셀 단위 허용 오차

FI_POLYGON_TOLERANCE

Ｘ

폴리곤 레이어의 픽셀 단위 허용 오차

FILTER_GEOM

Ｘ

도형 필터링

WITH_MAPTIP

Ｘ

출력물에 맵 도움말(map tip) 추가

WITH_GEOMETRY

Ｘ

출력물에 도형 추가

URL 예시:

http://localhost/qgisserver?
SERVICE=WMS
&VERSION=1.3.0
&REQUEST=GetMap
&MAP=/home/qgis/projects/world.qgs
&LAYERS=mylayer1,mylayer2,mylayer3
&CRS=EPSG:4326
&WIDTH=400
&HEIGHT=400
&INFO_FORMAT=text/xml
&TRANSPARENT=TRUE
&QUERY_LAYERS=mylayer1
&FEATURE_COUNT=3
&I=250
&J=250

REQUEST

GetFeatureInfo 요청의 경우, 이 파라미터는 FeatureInfo 이어야 합니다.

INFO_FORMAT

이 파라미터는 산출물의 포맷을 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다:

  • text/xml

  • text/html

  • text/plain

  • application/vnd.ogc.gml

  • application/json

QUERY_LAYERS

이 파라미터는 맵 상에 표시할 레이어를 지정합니다. 레이어명을 쉼표로 구분해야 합니다.

이에 더해, QGIS 서버는 레이어를 다음을 통해 선택할 수 있는 옵션을 제공합니다:

  • 약칭(short name)

  • 레이어 ID

더 자세한 내용은 GetMap 에서 설명하는 LAYERS 파라미터를 참조하세요.

FEATURE_COUNT

이 파라미터는 레이어별로 반환해야 할 피처의 최대 개수를 지정합니다. 예를 들어 QUERY_LAYERS 파라미터를 layer1,layer2 로 설정하고 FEATURE_COUNT 를 3 으로 설정하면 ‘layer1’ 로부터 피처를 최대 3개 반환할 것입니다. ‘layer2’ 도 마찬가지로 피처를 최대 3개 반환할 것입니다.

각 레이어별로 피처 1개만 반환하는 것이 기본값입니다.

I

WMS 1.3.0에서 정의된 이 파라미터는 쿼리 포인트의 픽셀 열을 지정할 수 있습니다.

X

I 파라미터와 동일하지만, WMS 1.1.1에서 정의되었습니다.

J

WMS 1.3.0에서 정의된 이 파라미터는 쿼리 포인트의 픽셀 행을 지정할 수 있습니다.

Y

J 파라미터와 동일하지만, WMS 1.1.1에서 정의되었습니다.

FI_POINT_TOLERANCE

이 파라미터는 포인트 레이어의 허용 오차를 픽셀 단위로 지정합니다.

FI_LINE_TOLERANCE

이 파라미터는 라인 레이어의 허용 오차를 픽셀 단위로 지정합니다.

FI_POLYGON_TOLERANCE

이 파라미터는 폴리곤 레이어의 허용 오차를 픽셀 단위로 지정합니다.

FILTER_GEOM

이 파라미터는 피처가 교차해야 하는 WKT 도형을 지정합니다.

WITH_MAPTIP

이 파라미터는 출력물에 맵 도움말(map tip)을 추가할지 여부를 지정합니다.

다음 값을 사용할 수 있습니다(대소문자 구분 안 함):

  • TRUE

  • FALSE

WITH_GEOMETRY

이 파라미터는 산출물에 도형을 추가할지 여부를 지정합니다. 이 기능을 사용하려면 먼저 QGIS 프로젝트에서 Add geometry to feature response 옵션을 활성화해야만 합니다. ref:사용자 프로젝트 환경 설정 <Creatingwmsfromproject> 을 참조하세요.

다음 값을 사용할 수 있습니다(대소문자 구분 안 함):

  • TRUE

  • FALSE

3.1.3. GetPrint

QGIS 서버는 인쇄 조판 출력물을 PDF 또는 픽셀 포맷으로 생성할 수 있습니다. 게시된 프로젝트에 있는 인쇄 조판기 창을 템플릿으로 사용합니다. 클라이언트는 GetPrint 요청 안에 템플릿이 담고 있는 조판 맵 및 라벨의 파라미터를 지정할 수 있습니다.

GetPrint 요청의 파라미터:

파라미터

필수 여부

설명

MAP

○

QGIS 프로젝트 파일을 지정합니다.

SERVICE

○

서비스(WMS)의 명칭

VERSION

Ｘ

서비스의 버전

REQUEST

○

요청(GetPrint)의 명칭

LAYERS

Ｘ

표시할 레이어

TEMPLATE

○

사용할 레이어 템플릿

SRS / CRS

○

좌표계

FORMAT

Ｘ

출력물 포맷

ATLAS_PK

Ｘ

지도책 피처

STYLES

Ｘ

레이어의 스타일

TRANSPARENT

Ｘ

투명한 배경

OPACITIES

Ｘ

레이어 또는 레이어 그룹의 투명도

SELECTION

Ｘ

피처를 강조합니다.

mapX:EXTENT

Ｘ

맵 ‘X’ 의 범위

mapX:LAYERS

Ｘ

맵 ‘X’ 의 레이어

mapX:STYLES

Ｘ

맵 ‘X’ 의 레이어의 스타일

mapX:SCALE

Ｘ

맵 ‘X’ 의 레이어의 축척

mapX:ROTATION

Ｘ

맵 ‘X’ 의 기울기

mapX:GRID_INTERVAL_X

Ｘ

맵 ‘X’ 의 X축 그리드 간격

mapX:GRID_INTERVAL_Y

Ｘ

맵 ‘X’ 의 Y축 그리드 간격

URL 예시:

http://localhost/qgisserver?
SERVICE=WMS
&VERSION=1.3.0
&REQUEST=GetPrint
&MAP=/home/qgis/projects/world.qgs
&CRS=EPSG:4326
&FORMAT=png
&TEMPLATE=Layout%201
&map0:EXTENT=-180,-90,180,90
&map0:LAYERS=mylayer1,mylayer2,mylayer3
&map0:OPACITIES=125,200,125
&map0:ROTATION=45

조판 템플릿이 맵을 하나 이상 담고 있을 수도 있다는 사실을 기억하십시오. 이런 맥락에서, 사용자가 특정 맵을 환경 설정하려는 경우 mapX: 파라미터를 사용해야 합니다. 이때 X 는 GetProjectSettings 요청 시 받아올 수 있는 양수(陽數)입니다.

다음은 예시입니다:

<WMS_Capabilities>
...
<ComposerTemplates xsi:type="wms:_ExtendedCapabilities">
<ComposerTemplate width="297" height="210" name="Druckzusammenstellung 1">
<ComposerMap width="171" height="133" name="map0"/>
<ComposerMap width="49" height="46" name="map1"/></ComposerTemplate>
</ComposerTemplates>
...
</WMS_Capabilities>

REQUEST

GetPrint 요청의 경우, 이 파라미터는 GetPrint 이어야 합니다.

TEMPLATE

이 파라미터는 인쇄용으로 사용할 조판 템플릿의 명칭을 지정할 수 있습니다.

FORMAT

이 파라미터는 맵 이미지의 포맷을 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다:

  • png (기본값)

  • image/png

  • jpg

  • jpeg

  • image/jpeg

  • svg

  • image/svg

  • image/svg+xml

  • pdf

  • application/pdf

FORMAT 파라미터가 이 값들 가운데 하나가 아닐 경우, 예외를 반환합니다.

ATLAS_PK

이 파라미터는 인쇄하려는 피처를 지정해서 지도책 렌더링을 활성화할 수 있습니다. (프로젝트 환경 설정에서 설정한 피처 최대 개수에 따라) 모든 피처를 담은 지도책을 받아오려면, * 특수문자를 사용하면 됩니다.

FORMAT 파라미터가 pdf 인 경우, 모든 피처 페이지를 결합한 PDF 문서 파일 1개를 반환합니다. 다른 모든 포맷의 경우, 단일 페이지를 반환합니다.

mapX:EXTENT

이 파라미터는 조판 맵 항목의 범위를 xmin,ymin,xmax,ymax 서식으로 지정합니다.

mapX:ROTATION

이 파라미터는 맵의 기울기를 도 단위로 지정합니다.

mapX:GRID_INTERVAL_X

이 파라미터는 X축 방향의 그리드선 밀도를 지정합니다.

mapX:GRID_INTERVAL_Y

이 파라미터는 Y축 방향의 그리드선 밀도를 지정합니다.

mapX:SCALE

이 파라미터는 조판 맵 항목의 맵 축척을 지정합니다. 클라이언트 및 서버가 축척 분모를 계산할 때 서로 다른 알고리즘을 사용하는 경우라도, 레이어와 라벨의 축척 기반 가시성을 보장하는 데 유용합니다.

mapX:LAYERS

이 파라미터는 조판 맵 항목에 표시될 레이어를 지정할 수 있습니다. 더 자세한 내용은 GetMap Layers 를 참조하세요.

mapX:STYLES

이 파라미터는 특정 조판 맵 항목에 표시되는 레이어의 스타일을 지정할 수 있습니다. 더 자세한 내용은 GetMap Styles 를 참조하세요.

3.1.4. GetLegendGraphics

다음은 범례 항목의 크기를 변경하는 데 사용할 수 있는 여러 추가 파라미터들입니다:

  • BOXSPACE: 범례 프레임과 내용물 사이의 여백을 밀리미터 단위로 정의합니다.

  • FORMAT: image/jpeg, image/png 또는 application/json. JSON의 경우, 심볼을 Base64로 인코딩하는데 조판 또는 글꼴과 관련된 다른 대부분의 옵션은 고려하지 않습니다. 왜냐하면 범례는 클라이언트 측에서 빌드되어야만 하기 때문입니다.

  • LAYERSPACE: 레이어들 사이의 수직 여백을 밀리미터 단위로 정의합니다.

  • LAYERTITLESPACE: 레이어 제목과 그 옆에 있는 항목들 사이의 수직 여백을 밀리미터 단위로 정의합니다.

  • SYMBOLSPACE: 심볼과 그 옆에 있는 항목 사이의 수직 여백을 밀리미터 단위로 정의합니다.

  • ICONLABELSPACE: 심볼과 라벨 텍스트 사이의 수평 여백을 밀리미터 단위로 정의합니다.

  • SYMBOLWIDTH: 심볼 미리보기의 너비를 밀리미터 단위로 정의합니다.

  • SYMBOLHEIGHT: 심볼 미리보기의 높이를 밀리미터 단위로 정의합니다.

다음은 레이어 제목 및 항목 라벨의 글꼴 속성을 변경하는 파라미터들입니다:

  • LAYERFONTFAMILY, ITEMFONTFAMILY: 각각 레이어 제목 및 항목의 텍스트 용 글꼴 패밀리를 정의합니다.

  • LAYERFONTBOLD, ITEMFONTBOLD: 값이 TRUE 이면 굵은체를 사용합니다.

  • LAYERFONTSIZE, ITEMFONTSIZE: 글꼴 크기를 포인트 단위로 정의합니다.

  • LAYERFONTITALIC, ITEMFONTITALIC: 값이 TRUE 이면 이탤릭체를 사용합니다.

  • LAYERFONTCOLOR, ITEMFONTCOLOR: 색상을 헥사 코드로 (예: 빨간색의 경우 #FF0000) 정의합니다.

  • LAYERTITLE: FALSE 로 설정하면 레이어 제목 없이 범례 그래픽만 반환합니다.

  • RULELABEL:

    • FALSE 로 설정하면 항목 라벨 없이 범례 그래픽만 반환합니다.

    • AUTO 로 설정하면 Single symbol 렌더링된 레이어의 항목 라벨을 숨깁니다.

내용 기반(content based) 범례를 위한 파라미터는 클라이언트가 요청한 영역 안에 들어오는 피처에 대한 심볼만 표시하는 범례를 요청할 수 있도록 해줍니다:

  • BBOX: 범례를 생성해야 하는 지리적 영역을 정의합니다.

  • CRS, SRS: BBOX 의 좌표를 계산하는 데 사용될 좌표계를 정의합니다.

  • SRCWIDTH / SRCHEIGHT: 이 파라미터들을 설정하는 경우, QGIS 서버가 심볼의 크기를 맵 뷰 이미지 크기에 따라 조정할 수 있도록 GetMap 요청에서 정의한 WIDTH 및 HEIGHT 파라미터와 일치해야 합니다.

내용 기반 범례 피처는 UMN 맵서버 구현 사양 을 기반으로 합니다:

  • SHOWFEATURECOUNT: TRUE 로 설정한 경우 범례에 각 피처의 개수를 다음 그림과 같이 추가합니다:

    ../../_images/getfeaturecount_legend.png

  • RULE: 이 파라미터를 지정한 규칙명으로 설정하면, 이름을 지정한 규칙 심볼만 가져옵니다.

  • WIDTH/HEIGHT: RULE 파라미터를 설정한 경우 생성하는 범례 이미지 크기입니다.

3.1.5. GetProjectSettings

이 요청 유형은 GetCapabilities 요청과 비슷하게 동작하지만, 좀 더 QGIS 서버에 특화돼 있고 클라이언트가 GetCapabilities 출력물에서는 볼 수 없는 다음 추가 정보를 읽을 수 있습니다:

  • 레이어의 초기 가시성

  • 벡터 속성 및 속성 편집 유형 관련 정보

  • 레이어 순서 및 렌더링 순서 관련 정보

  • WFS에 게시된 레이어 목록

  • 레이어 트리에 있는 그룹이 상호 배타적 인 경우 표시합니다.

3.2. WFS(웹 피처 서비스)

QGIS 서버에 구현된 WFS 1.0.0 및 1.1.0 표준은 QGIS 프로젝트로부터 지리 피처를 쿼리할 수 있는 HTTP 인터페이스를 제공합니다. 전형적인 WFS 요청은 사용할 QGIS 프로젝트와 쿼리할 레이어를 정의합니다.

서비스 버전에 따른 사양 문서:

QGIS 서버가 제공하는 표준 요청:

요청

설명

GetCapabilities

서버에 대한 정보를 담은 XML 메타데이터를 반환합니다.

GetFeature

피처 집합을 반환

DescribeFeatureType

피처 유형 및 속성의 설명을 반환

Transaction

피처를 삽입, 업데이트, 삭제 가능

3.2.1. GetFeature

OGC WFS 1.0.0 및 1.1.0 사양에 따른 GetFeature 요청용 표준 파라미터:

파라미터

필수 여부

설명

SERVICE

○

서비스명

VERSION

Ｘ

서비스의 버전

REQUEST

○

요청명

TYPENAME

Ｘ

레이어명

OUTPUTFORMAT

Ｘ

출력물 포맷

RESULTTYPE

Ｘ

산출물 유형

PROPERTYNAME

Ｘ

반환할 속성의 명칭

MAXFEATURES

Ｘ

반환할 피처의 최대 개수

SRSNAME

Ｘ

좌표계

FEATUREID

Ｘ

피처를 ID로 필터링

FILTER

Ｘ

OGC 필터 인코딩

BBOX

Ｘ

맵 범위

SORTBY

Ｘ

산출물 정렬

표준 파라미터 이외에도, QGIS 서버는 다음과 같은 추가 파라미터를 지원합니다:

파라미터

필수 여부

설명

MAP

○

QGIS 프로젝트 파일을 지정합니다.

STARTINDEX

Ｘ

페이지 번호 붙이기

GEOMETRYNAME

Ｘ

반환할 도형의 유형

EXP_FILTER

Ｘ

표현식 필터링

SERVICE

GetFeature 요청의 경우, 이 파라미터는 WFS 이어야 합니다.

다음은 예시입니다:

http://localhost/qgisserver?
SERVICE=WFS
&...

VERSION

이 파라미터는 사용할 서비스의 버전을 지정할 수 있습니다. VERSION 파라미터가 사용할 수 있는 값은 다음과 같습니다:

  • 1.0.0

  • 1.1.0

요청에서 버전을 지정하지 않을 경우, 1.1.0 을 기본값으로 사용합니다.

URL 예시:

http://localhost/qgisserver?
SERVICE=WFS
&VERSION=1.1.0
&...

REQUEST

GetFeature 요청의 경우, 이 파라미터는 GetFeature 이어야 합니다.

URL 예시:

http://localhost/qgisserver?
SERVICE=WFS
&VERSION=1.1.0
&REQUEST=GetFeature
&...

RESULTTYPE

이 파라미터는 산출물의 종류를 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다:

  • results: 기본 습성

  • hits: 피처 개수만 반환

URL 예시:

http://localhost/qgisserver?
SERVICE=WFS
&VERSION=1.1.0
&REQUEST=GetFeature
&RESULTTYPE=hits
&...

GEOMETRYNAME

이 파라미터는 피처에 대해 반환할 도형의 종류를 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다:

  • extent

  • centroid

  • none

URL 예시:

http://localhost/qgisserver?
SERVICE=WFS
&VERSION=1.1.0
&REQUEST=GetFeature
&GEOMETRYNAME=centroid
&...

STARTINDEX

이 파라미터는 WFS 2.0에서는 표준이지만, WFS 1.0.0에서는 확장 기능입니다. 실제로는 산출물 집합에서 일부 피처를 건너뛰는데 사용할 수 있기 때문에, MAXFEATURES 파라미터와 함께 사용하면 산출물의 페이지를 넘기는 기능으로 쓸 수 있습니다.

URL 예시:

http://localhost/qgisserver?
SERVICE=WFS
&VERSION=1.1.0
&REQUEST=GetFeature
&STARTINDEX=2
&...

3.3. WMTS(웹 맵 타일 서비스)

QGIS 서버에 구현된 WMTS 1.0.0 표준은 QGIS 프로젝트로부터 생성된 타일 맵 이미지들을 요청할 수 있는 HTTP 인터페이스를 제공합니다. 전형적인 WMTS 요청은 사용할 QGIS 프로젝트, 렌더링할 레이어와 같은 몇몇 WMS 파라미터들은 물론 타일 파라미터들도 정의합니다.

WMTS 서비스의 사양 문서:

QGIS 서버가 제공하는 표준 요청:

요청

설명

GetCapabilities

서버에 대한 정보를 담은 XML 메타데이터를 반환합니다.

GetTile

타일을 반환

GetFeatureInfo

픽셀 위치에 대한 데이터(도형 및 값)를 검색합니다.

3.3.1. GetCapabilities

OGC WMTS 1.0.0 사양에 따른 GetCapabilities 요청용 표준 파라미터:

파라미터

필수 여부

설명

SERVICE

○

서비스(WMTS)의 명칭

REQUEST

○

요청(GetCapabilities)의 명칭

표준 파라미터 이외에도, QGIS 서버는 다음과 같은 추가 파라미터를 지원합니다:

파라미터

필수 여부

설명

MAP

○

QGIS 프로젝트 파일을 지정합니다.

URL 예시:

http://localhost/qgisserver?
SERVICE=WMTS
&REQUEST=GetCapabilities
&MAP=/home/qgis/projects/world.qgs

SERVICE

GetCapabilities 요청의 경우, 이 파라미터는 WMTS 이어야 합니다.

REQUEST

GetCapabilities 요청의 경우, 이 파라미터는 GetCapabilities 이어야 합니다.

MAP

이 파라미터는 사용할 QGIS 프로젝트 파일을 정의할 수 있습니다.

3.3.2. GetTile

OGC WMTS 1.0.0 사양에 따른 GetTile 요청용 표준 파라미터:

파라미터

필수 여부

설명

SERVICE

○

서비스(WMTS)의 명칭

REQUEST

○

요청(GetTile)의 명칭

LAYER

○

레이어 식별자

FORMAT

○

타일의 산출물 포맷

TILEMATRIXSET

○

피라미드명

TILEMATRIX

○

메시 작업

TILEROW

○

메시 내부의 행 좌표

TILECOL

○

메시 내부의 열 좌표

표준 파라미터 이외에도, QGIS 서버는 다음과 같은 추가 파라미터를 지원합니다:

파라미터

필수 여부

설명

MAP

○

QGIS 프로젝트 파일을 지정합니다.

URL 예시:

http://localhost/qgisserver?
SERVICE=WMTS
&REQUEST=GetTile
&MAP=/home/qgis/projects/world.qgs
&LAYER=mylayer
&FORMAT=image/png
&TILEMATRIXSET=EPSG:4326
&TILEROW=0
&TILECOL=0

SERVICE

GetTile 요청의 경우, 이 파라미터는 WMTS 이어야 합니다.

REQUEST

GetTile 요청의 경우, 이 파라미터는 GetTile 이어야 합니다.

LAYER

이 파라미터는 타일 상에 표시할 레이어를 지정할 수 있습니다.

이에 더해, QGIS 서버는 레이어를 다음을 통해 선택할 수 있는 옵션을 제공합니다:

  • 약칭(short name)

  • 레이어 ID

레이어 메뉴의 Properties ► Metadata 를 통해 레이어의 약칭을 설정할 수도 있습니다. 약칭을 정의한 경우, 레이어명 대신 약칭을 기본으로 사용할 것입니다:

http://localhost/qgisserver?
SERVICE=WMTS
&REQUEST=GetTile
&LAYER=mynickname
&...

이에 더해, Project ► Properties… 대화창의 OWS Server ► WMS capabilities 메뉴에서 레이어 ID로 레이어를 선택할 수 있는 프로젝트 수준 옵션도 있습니다. 이 옵션을 활성화하려면, Use layer ids as names 옵션을 체크하십시오.

http://localhost/qgisserver?
SERVICE=WMTS
&REQUEST=GetTile
&LAYER=mylayerid1
&...

FORMAT

이 파라미터는 타일 이미지의 포맷을 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다:

  • jpg

  • jpeg

  • image/jpeg

  • image/png

FORMAT 파라미터가 이 값들 가운데 하나가 아닐 경우, 기본 포맷인 PNG를 대신 사용합니다.

TILEMATRIXSET

이 파라미터는 기저 피라미드를 계산할 때 사용할 좌표계를 정의합니다. 서식: EPSG:XXXX.

TILEMATRIX

이 파라미터는 산출물 타일용으로 사용할 매트릭스를 정의할 수 있습니다.

TILEROW

이 파라미터는 매트릭스 내부에 들어갈 타일의 행을 선택할 수 있습니다.

TILECOL

이 파라미터는 매트릭스 내부에 들어갈 타일의 열을 선택할 수 있습니다.

MAP

이 파라미터는 사용할 QGIS 프로젝트 파일을 정의할 수 있습니다.

GetMap 파라미터 표 에서 언급한 것처럼, MAP 파라미터는 필수입니다. 요청이 제대로 작동하려면 QGIS 프로젝트가 필요하기 때문입니다. 하지만 QGIS_PROJECT_FILE 환경 변수를 사용해서 기본 QGIS 프로젝트를 정의할 수도 있습니다. 이런 특정한 경우에만, MAP 이 필수 파라미터가 아니게 됩니다. 더 자세한 내용은 고급 환경 설정 을 참조하세요.

3.3.3. GetFeatureInfo

OGC WMTS 1.0.0 사양에 따른 GetFeatureInfo 요청용 표준 파라미터:

파라미터

필수 여부

설명

SERVICE

○

서비스(WMTS)의 명칭

REQUEST

○

요청(GetFeatureInfo)의 명칭

LAYER

○

레이어 식별자

INFOFORMAT

Ｘ

출력물 포맷

I

Ｘ

픽셀의 X 좌표

J

Ｘ

픽셀의 Y 좌표

TILEMATRIXSET

○

GetTile 참조

TILEMATRIX

○

GetTile 참조

TILEROW

○

GetTile 참조

TILECOL

○

GetTile 참조

표준 파라미터 이외에도, QGIS 서버는 다음과 같은 추가 파라미터를 지원합니다:

파라미터

필수 여부

설명

MAP

○

QGIS 프로젝트 파일을 지정합니다.

URL 예시:

http://localhost/qgisserver?
SERVICE=WMTS
&REQUEST=GetFeatureInfo
&MAP=/home/qgis/projects/world.qgs
&LAYER=mylayer
&INFOFORMAT=image/html
&I=10
&J=5

SERVICE

GetFeatureInfo 요청의 경우, 이 파라미터는 WMTS 이어야 합니다.

REQUEST

GetFeatureInfo 요청의 경우, 이 파라미터는 FeatureInfo 이어야 합니다.

MAP

이 파라미터는 사용할 QGIS 프로젝트 파일을 정의할 수 있습니다.

GetMap 파라미터 표 에서 언급한 것처럼, MAP 파라미터는 필수입니다. 요청이 제대로 작동하려면 QGIS 프로젝트가 필요하기 때문입니다. 하지만 QGIS_PROJECT_FILE 환경 변수를 사용해서 기본 QGIS 프로젝트를 정의할 수도 있습니다. 이런 특정한 경우에만, MAP 이 필수 파라미터가 아니게 됩니다. 더 자세한 내용은 고급 환경 설정 을 참조하세요.

LAYER

이 파라미터는 타일 상에 표시할 레이어를 지정할 수 있습니다.

이에 더해, QGIS 서버는 레이어를 다음을 통해 선택할 수 있는 옵션을 제공합니다:

  • 약칭(short name)

  • 레이어 ID

레이어 메뉴의 Properties ► Metadata 를 통해 레이어의 약칭을 설정할 수도 있습니다. 약칭을 정의한 경우, 레이어명 대신 약칭을 기본으로 사용할 것입니다:

http://localhost/qgisserver?
SERVICE=WMTS
&REQUEST=GetFeatureInfo
&LAYER=mynickname
&...

이에 더해, Project ► Properties… 대화창의 OWS Server ► WMS capabilities 메뉴에서 레이어 ID로 레이어를 선택할 수 있는 프로젝트 수준 옵션도 있습니다. 이 옵션을 활성화하려면, Use layer ids as names 옵션을 체크하십시오.

http://localhost/qgisserver?
SERVICE=WMTS
&REQUEST=GetFeatureInfo
&LAYER=mylayerid1
&...

INFOFORMAT

이 파라미터는 산출물의 포맷을 지정할 수 있습니다. 사용할 수 있는 값은 다음과 같습니다:

  • text/xml

  • text/html

  • text/plain

  • application/vnd.ogc.gml

기본값은 text/plain 입니다.

I

이 파라미터는 기저 정보를 검색하고자 하는 픽셀의 X 좌표를 정의할 수 있습니다.

J

이 파라미터는 기저 정보를 검색하고자 하는 픽셀의 Y 좌표를 정의할 수 있습니다.

3.4. WFS3 (OGC API ─ 피처)

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

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

  • WFS3은 REST API를 기반으로 합니다.

  • WFS3 API는 OPENAPI 사양을 따라야만 합니다.

  • WFS3은 여러 산출물 포맷을 지원하지만 어느 포맷도 강제하지 않으며 (QGIS WFS3은 현재 GeoJSON과 HTML만 지원합니다) 클라이언트에 서비스할 포맷을 결정하는 데 내용 협상(content negotiation) 을 사용합니다.

  • JSON과 HTML은 WFS3의 일급 객체(first class citizen)입니다.

  • WFS3은 (/api 종단점을 통해) 자체 문서화(self-documenting)합니다.

  • WFS3을 (링크를 통해) 완전하게 둘러보고 또 탐색할 수 있습니다.

중요

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

참고

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

3.4.1. 리소스 표현

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

  • HTML

  • JSON

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

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

  • .json

  • .html

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

  • .openapi: API 종단점이 지원하는 .json 의 별명

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

3.4.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.2 서버 WFS3 랜딩 페이지

API 정의

API 정의 는 서비스가 제공하는 API의, OPENAPI와 호환되는 설명입니다. 이 HTML 표현은 모든 종단점 및 각 종단점의 응답 포맷을 정확하게 목록화하고 문서화한, 탐색 가능한 페이지입니다. 이 종단점의 경로는 /api 입니다.

API 정의는 서비스에 대한, 지원하는 파라미터와 반환되는 포맷을 모두 포함하는 포괄적이고 권위 있는 문서를 제공합니다.

참고

이 종단점은 WFS의 GetCapabilities 와 유사합니다.

Collections 목록

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

../../_images/server_wfs3_collections.png

그림 3.3 서버 WFS3 선택 집합 목록 페이지

Collection 상세 정보

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

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

../../_images/server_wfs3_collection.png

그림 3.4 서버 WFS3 선택 집합 상세 정보 페이지

Features 목록

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

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

참고

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

../../_images/server_wfs3_features.png

그림 3.5 서버 WFS3 피처 목록 페이지

Feature 상세 정보

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

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

../../_images/server_wfs3_feature.png

그림 3.6 서버 WFS3 피처 상세 정보 페이지

3.4.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.4.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

속성 필터

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

URL 예시:

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

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

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

URL 예시:

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

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

3.4.5. 객체 정렬

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

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

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

3.4.6. 속성 선택

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

URL 예시:

name 속성만 반환

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

3.4.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” 을 반환할 것입니다.

템플릿 무시

템플릿과 정적 자산(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.5. 모든 요청 유형이 지원하는 추가 파라미터들

모든 프로토콜이 다음과 같은 추가 파라미터를 지원합니다.

  • FILE_NAME: 이 파라미터를 설정하면, 서버가 클라이언트에게 지정한 파일명을 가진 첨부 파일로 응답을 전송할 것입니다.

참고

WFS3에서는 사용할 수 없습니다.

  • MAP: 맵서버와 비슷하게, QGIS 프로젝트 파일을 가리키는 경로를 지정하는 데 MAP 파라미터를 사용할 수 있습니다. 절대 경로를 지정할 수도 있고, 서버 실행 파일(qgis_mapserv.fcgi)의 위치를 기준으로 하는 상대 경로를 지정할 수도 있습니다. 이 파라미터를 설정하지 않으면, QGIS는 서버 실행 파일이 위치한 디렉터리에서 .qgs 파일을 검색합니다.

    다음은 그 예시입니다:

    http://localhost/cgi-bin/qgis_mapserv.fcgi?\
  REQUEST=GetMap&MAP=/home/qgis/projects/world.qgs&...

참고

QGIS_PROJECT_FILE 파라미터를 환경 변수로 정의해서 서버 실행 파일에 QGIS 프로젝트 파일을 찾을 수 있는 위치를 알려줄 수 있습니다. 이 변수가 QGIS가 프로젝트 파일을 검색할 위치가 될 것입니다. 정의하지 않을 경우, 요청에 있는 MAP 파라미터를 이용한 다음 마지막으로 서버 실행 파일이 있는 디렉터리를 살펴볼 것입니다.

3.6. REDLINING(특정 경계 지역 지정)

GetMap 및 GetPrint 요청을 통해 이 기능을 사용할 수 있습니다.

요청 안에 있는, 서버가 반환한 표준 이미지(맵) 위에 중첩되는 도형 및 라벨을 전송하는 데 이 REDLINING 기능을 사용할 수 있습니다. 이 기능은 사용자가 표준 맵에는 없는 일부 지역 또는 위치 등을 강조하거나 또는 그런 곳에 주석(라벨)을 달 수 있도록 해줍니다.

다음과 같은 서식으로 GetMap 을 요청합니다:

http://qgisplatform.demo/cgi-bin/qgis_mapserv.fcgi?map=/world.qgs&SERVICE=WMS&VERSION=1.3.0&
REQUEST=GetMap
...
&HIGHLIGHT_GEOM=POLYGON((590000 5647000, 590000 6110620, 2500000 6110620, 2500000 5647000, 590000 5647000))
&HIGHLIGHT_SYMBOL=<StyledLayerDescriptor><UserStyle><Name>Highlight</Name><FeatureTypeStyle><Rule><Name>Symbol</Name><LineSymbolizer><Stroke><SvgParameter name="stroke">%23ea1173</SvgParameter><SvgParameter name="stroke-opacity">1</SvgParameter><SvgParameter name="stroke-width">1.6</SvgParameter></Stroke></LineSymbolizer></Rule></FeatureTypeStyle></UserStyle></StyledLayerDescriptor>
&HIGHLIGHT_LABELSTRING=Write label here
&HIGHLIGHT_LABELSIZE=16
&HIGHLIGHT_LABELCOLOR=%23000000
&HIGHLIGHT_LABELBUFFERCOLOR=%23FFFFFF
&HIGHLIGHT_LABELBUFFERSIZE=1.5

동일한 내용의 GetPrint 요청은 다음과 같습니다(어떤 맵을 특정 경계 지역 지정하는지 알리기 위해 mapX: 파라미터를 추가했다는 점을 기억하세요):

http://qgisplatform.demo/cgi-bin/qgis_mapserv.fcgi?map=/world.qgs&SERVICE=WMS&VERSION=1.3.0&
REQUEST=GetPrint
...
&map0:HIGHLIGHT_GEOM=POLYGON((590000 5647000, 590000 6110620, 2500000 6110620, 2500000 5647000, 590000 5647000))
&map0:HIGHLIGHT_SYMBOL=<StyledLayerDescriptor><UserStyle><Name>Highlight</Name><FeatureTypeStyle><Rule><Name>Symbol</Name><LineSymbolizer><Stroke><SvgParameter name="stroke">%23ea1173</SvgParameter><SvgParameter name="stroke-opacity">1</SvgParameter><SvgParameter name="stroke-width">1.6</SvgParameter></Stroke></LineSymbolizer></Rule></FeatureTypeStyle></UserStyle></StyledLayerDescriptor>
&map0:HIGHLIGHT_LABELSTRING=Write label here
&map0:HIGHLIGHT_LABELSIZE=16
&map0:HIGHLIGHT_LABELCOLOR=%23000000
&map0:HIGHLIGHT_LABELBUFFERCOLOR=%23FFFFFF
&map0:HIGHLIGHT_LABELBUFFERSIZE=1.5

다음 그림은 앞의 요청을 통해 일반 맵 위에 폴리곤 및 라벨을 렌더링한 출력물을 보여줍니다:

../../_images/server_redlining.png

그림 3.7 REDLINING 파라미터를 보유한 GetMap 요청에 대한 서버의 응답

이 요청 안에 다음 여러 파라미터들이 있다는 것을 알 수 있습니다:

  • HIGHLIGHT_GEOM: 포인트, 멀티라인스트링, 폴리곤 등을 추가할 수 있습니다. 다중 부분 도형도 지원합니다. 이 파라미터는 HIGHLIGHT_GEOM=MULTILINESTRING((0 0, 0 1, 1 1)) 과 같이 사용할 수 있습니다. 사용 좌표는 GetMap / GetPrint 요청의 좌표계의 좌표여야 합니다.

  • HIGHLIGHT_SYMBOL: 이 파라미터는 도형의 외곽선을 어떻게 렌더링할지 제어하며, 사용자가 획의 너비, 색상 및 불투명도를 변경할 수 있습니다.

  • HIGHLIGHT_LABELSTRING: 이 파라미터를 통해 사용자의 라벨 텍스트를 넘겨줄 수 있습니다.

  • HIGHLIGHT_LABELSIZE: 이 파라미터는 라벨의 크기를 제어합니다.

  • HIGHLIGHT_LABELFONT: 이 파라미터는 라벨의 글꼴(예: Arial)을 제어합니다.

  • HIGHLIGHT_LABELCOLOR: 이 파라미터는 라벨의 색상을 제어합니다.

  • HIGHLIGHT_LABELBUFFERCOLOR: 이 파라미터는 라벨 버퍼의 색상을 제어합니다.

  • HIGHLIGHT_LABELBUFFERSIZE: 이 파라미터는 라벨 버퍼의 크기를 제어합니다.

3.7. 외부 WMS 레이어

QGIS 서버는 WMS GetMap 및 GetPrint 요청에 외부 WMS 서버의 레이어를 포함시킬 수 있습니다. 웹 클라이언트가 웹 맵에 외부 배경 레이어를 사용하는 경우 특히 유용한 기능입니다. 속도 향상을 위해, 웹 클라이언트가 이런 레이어를 (QGIS 서버를 통해 순차적으로 요청하는 것이 아니라) 직접 요청해야 합니다. 하지만 인쇄 작업의 경우, 인쇄한 맵에 이런 레이어가 나타나게 하려면 QGIS 서버를 통해 순차적으로 요청해야 합니다.

LAYERS 파라미터에 외부 레이어를 EXTERNAL_WMS:<layername> 로 추가할 수 있습니다. 외부 WMS 레이어용 파라미터(예를 들어 url, format, dpiMode, crs, layers, styles 등)는 차후 서비스 파라미터 <layername>:<parameter> 로 지정할 수 있습니다. GetMap 요청에서는 다음과 같이 보일 수도 있습니다:

http://localhost/qgisserver?
SERVICE=WMS&REQUEST=GetMap
...
&LAYERS=EXTERNAL_WMS:basemap,layer1,layer2
&STYLES=,,
&basemap:url=http://externalserver.com/wms.fcgi
&basemap:format=image/jpeg
&basemap:dpiMode=7
&basemap:crs=EPSG:2056
&basemap:layers=orthofoto
&basemap:styles=default

GetPrint 요청에서도 이와 비슷하게 외부 레이어를 사용할 수 있습니다:

http://localhost/qgisserver?
SERVICE=WMS
...
&REQUEST=GetPrint&TEMPLATE=A4
&map0:layers=EXTERNAL_WMS:basemap,layer1,layer2
&map0:EXTENT=<minx,miny,maxx,maxy>
&basemap:url=http://externalserver.com/wms.fcgi
&basemap:format=image/jpeg
&basemap:dpiMode=7
&basemap:crs=EPSG:2056
&basemap:layers=orthofoto
&basemap:styles=default

3.8. QGIS 서버 카탈로그

QGIS 서버 카탈로그는 QGIS 서버가 서비스하는 QGIS 프로젝트들의 목록을 보여주는 단순 카탈로그입니다. 해당 QGIS 프로젝트들을 통해 노출되는 데이터셋을 손쉽게 탐색할 수 있는 기본 매핑 케이퍼빌리티를 가지고 있는, 완전 검색이 가능하고 사용자 친화적인 웹사이트를 제공합니다.

QGIS 서버 카탈로그는 QGIS_SERVER_LANDING_PAGE_PROJECTS_DIRECTORIES 및 QGIS_SERVER_LANDING_PAGE_PROJECTS_PG_CONNECTIONS 변수를 사용합니다. (환경 변수 를 참조하세요.)

../../_images/server_project_list.png

그림 3.8 서버 카탈로그 프로젝트 목록 페이지

프로젝트에 관련된 메타데이터와 프로젝트가 제공하는 서비스를 참고할 수 있습니다. 이런 서비스를 가리키는 링크도 제공됩니다.

../../_images/server_project_metadata_services.png

그림 3.9 서버 카탈로그, 프로젝트에 관련된 메타데이터와 프로젝트가 제공하는 서비스(를 가리키는 링크)

프로젝트를 탐색하면 해당 프로젝트가 서비스하는 데이터셋 목록을 볼 수 있습니다.

../../_images/server_browse_dataset.png

그림 3.10 서버 카탈로그에 있는 프로젝트가 서비스하는 데이터셋 탐색하기

레이어를 오른쪽 클릭하면 해당 레이어 관련 속성 테이블을 표시합니다.

../../_images/server_attribute_table.png

그림 3.11 레이어 관련 속성 테이블

다음 그림에서 볼 수 있는 것처럼, 맵에 있는 요소들의 정보도 참고할 수 있습니다:

../../_images/server_info_results.png

그림 3.12 맵 요소의 정보 참고하기