. 개정이 서 개정번호개정페이 및내용개정일 2

Open API Library 개발자가이드 1

. 개정이 서 개정번호개정페이 및내용개정일 2

차 1. Open API Library 구성... 5 2. Open API Library 상세구조... 5 2.1. Open API Application Module 구조설명... 6 2.1.1. Simple Module... 6 2.1.2. Shortcut Module... 6 2.1.3. Base Module... 7 2.2. Open API Gateway Library 구조설명... 7 2.2.1. Simple Module... 7 2.2.2. Shortcut Module... 7 2.2.3. Base Module... 8 3. Open API Library Sample 코드... 8 3.1. JAVA Application 개 을위한 Open API Application Module Sample 설명... 8 3.1.1. 초기... 8 3.1.2. 단말등... 10 3.1.3. 수집데이터조회... 11 3.1.4. 어... 12 3.1.5. Exceptions... 14 3.2. 안드 이드 Application 개 을위한 Open API Application Module Sample 설명... 15 3.2.1. 안드 이드 성에따른처리... 16 3.2.2. GW... 18 3.2.3. GW 위치측위... 18 3.2.4. GW 주기 고-... 18 3.3. JAVA Application 개 을위한 Open API Gateway Module Sample 설명... 18 3.3.1. 초기... 19 3.3.2. GW/Device 등... 20 3.3.3. 수집데이터 고... 22 3.3.4. 어- 고... 23 3.3.5. GatewayAuthor... 24 3

3.3.6. OmpResponseModel... 24 3.3.7. Exceptions... 25 3.4. 안드 이드 Application 개 을위한 Open API Gateway Module Sample 설명... 26 3.4.1. 안드 이드 성에따른처리... 27 3.4.2. GW 등... 29 3.4.3. GW Profile... 29 3.4.4. GW 주기 고... 29 4

1. Open API Library 구성 Open API Library는 Open API Gateway Module과 Application Module 구성되어있다. Open API Gateway Module은 SKT OMP와 M2M Gateway의연동을위해사용되며 Open API Application Module는 SKT OMP와 M2M Application의연동을위해사용된다. Gateway Module와 Application Module는 JAR(Java Archive 형 파일구조 ) 공되며본문서는 Open API Library에대한 이드만 공한다. 2. Open API Library 상세구조 Open API Library는기본 으 com.skt.omp 키 를루 사용하므 해당 키 와겹치는명칭을사용하 않아숗한다. HTTP 통신부분에 Apache HttpComponents 4.3.2 Library를사용을하며 키 명 org.apache.http을 omp.org.apache.http으 변경해서사용하고있다.. Apache HttpComponents Library 사용에참조하는 Apache commons-logging 1.1.3 버전, Apache commons-codec 1.6 버전이추 사용된다. Apache HttpComponents Library를추 사용할경우 omp.org.apache.http 키 를사용하기를권장한다. 세한내용은 https://hc.apache.org/ 에서 인할수있으며 HttpClient 4.3.2 와 HttpCore 4.3.2 를 인하면 된다. 5

2.1. Open API Application Module 구조설명 Open API Application Module은크게 3 구분된다. Module를사용하기위한 Simple Interface Module, 개별기능구현을위한 Shortcut Module, 공통기능과 OMP와의네 워킹을위한 Base 듈 나뉜다 2.1.1. Simple Module Library 사용 를위해 공되는 Module Operation에해당하는기능들을쉽게사용하기위해구성되어져있으며, Library 셎스에서 ApplicationCommon 인터페이스와 ApplicationExtension 인터페이스를구현한 Application Module 클래스에해당한다. Shorcut Module의기능들을하나 으고, 요청을분배하는 할을한다. 2.1.2. Shortcut Module 기능별실 구현을 고있는 듈. Simple Module 부터전달 은명령을 Base Module을사용해 값을 장하고, OMP에요청을 낸후, 은응 값을기 하고다시 Simple Module 전달하는 할을한다. Simple Module에서 Inteface 정의한기능을사용하면되기에, Shortcut Module을 다룰필요는숰다. 6

2.1.3. Base Module Library 내에서공통으 사용하는기능들이나 OMP 와의 Network 등에사용하는기능등을 은 듈. 2.2. Open API Gateway Library 구조설명 Open API Gateway Library는크게 3 구분된다. Library를사용하기위한 Simple Interface Module, 개별기능구현을위한 Shortcut Module, 공통기능과 OMP와의네 워킹을위한 Base 듈 나뉜다 2.2.1. Simple Module Library 사용 를위해 공되는 Module Operation에해당하는기능들을쉽게사용하기위해구성되어져있으며, Library 셎스에서 GatewayCommon 인터페이스를구현한 Gateway Module 클래스에해당한다. Shorcut Module의기능들을하나 으고, 요청을분배하는 할을한다. 2.2.2. Shortcut Module 기능별실 구현을 고있는 듈. Simple Module 부터전달 은명령을 Base Module을사용해 값을 장하고, OMP에요청을 낸후, 은응 값을기 하고다시 Simple Module 전달하는 할을한다. 7

Simple Module 에서 Inteface 정의한기능을사용하면되기에, Shortcut Module 을 다룰필요는숰 다. 2.2.3. Base Module Library 내에서공통으 사용하는기능들이나 OMP 와의 Network 등에사용하는기능등을 은 듈. 3. Open API Library Sample 코드 해당 Library는일반 바어플리케이션개 은물론, 안드 이드및서블릿에서도사용 능하다. 기본 인사용법은일반 바어플리케이션개 과동일하기에, 전체 인설명은일반 바어플리케이션개 을기준으 한다. 안드 이드개 에서도크게달라 않기에, 그에대한설명은대표 인기능몇 만예를들어설명한다. 전체 인내용은일반 바어플리케이션개 의설명을참고하기바란다. 샘플코드에 용된 domain, servicename 등의값들은테스 코드에사용된값으 기능동 에대한책 은 않는다. 해당값들은 SKT OMP Portal을통해등 절차 진 이되어숗만한다. 샘플에대한설명은 Open API Application Module, Open API Gateway Module 순으 설명한다. 3.1. JAVA Application 개발을위한 Open API Application Module Sample 설명 샘플의구조는다음과같다. 3.1.1. 초기화 8

샘플프 의초기값은 SampleHelper.java 의생성 에 장되어있다. 샘플클래스들은이 SampleHelper 를사용해필요한값을취한다. 때문에값을변경해숗할경우 SampleHelper 만편집하면 든샘플클래스에 용된다. 따라서이하의메뉴들에선초기값에대한설명은생략한다. 9

3.1.2. 단말등 GW를등 할때는 M2M OMP 포탈의 [ 단말관리 ] 메뉴에서등 신청을하고승인을 은상 숗만 능하다. 단말등 은 ApplicationRosterRegSample.java를참고한다. reg() 는단말등 예 다. Application Module의 aoreg 메서드를사용한다. 10

해 의경우반환되는 Message-Body 숰으므 성공 부를 인하 면 Response-Code 를 인해숗한 다. 반환값으 숪는 ResponseModel 을통해 Response-Code 값을숪을수있다. 3.1.3. 수집데이터조회 수집데이터 고는 ApplicationReportSample.java 를참고한다. Application Module 의 aodata 메서드를사용한다. GW 와 Device 두같은메서드를사용하 만, GW 인 11

경우에는 deviceid에해당하는값이 null이어숗만한다. 수집데이터 고는 4종류 주기 고 / 이벤 고 / 장애 고 / 장애해 고 이다. 의구분은 ReportType enum 값으 결정된다. 3.1.4. 제어 어 는 ApplicationControlSample.java를참고한다. Application Module의 gocontrol 메서드를사용한다. GW와 Device 두같은메서드를사용하 만, GW 인경우에는 deviceid에해당하는값이 null이어숗만한다. 어명령을내린후에는 동으 어결과를조회하는데이는 ControlCallback 인터페이스의구현을통해그응 을 는다. 12

어명령의응 은 oncommandresponse 메서드를통해 을수있다. 어명령이정상 으 수 되었으면숫마후에 어결과를조회할것인 를 0 이상의밀리초단위 반환한다. 만수 어명령이실 거나, 어결과를 인할필요 숰다면 0 다 은수를반환한다. 0 다 으면 어조회를수 하 않고처리 종료된다. oncommandresponse 메서드에서 0 이상의수를반환 다면그만큼의밀리초후 어결과조회 실 되고, 그응 은 onresultresponse 메서드를통해 을수있다. 어 아 진 되고있어성공 / 실 알수숰다면다시금숫마후에 어결과를조회할것인 를 0 이상의밀리초단위 반환한다. 만수 어결과를 인할필요 숰다면 0 다 은수를반환한다. 0 다 으면더이상 어조회는반 수 하 않고처리 종료된다. GW Remote Terminal Access 어는 GMMP 단말만 원한다. 13

3.1.5. Exceptions 예외처리는 ExceptionCatcher.java 를참고한다. Application Module의 기능들은상황에따라 러 예외를던질수있는데해당예외들은기본 으 OmpException을상셏 고있다. 따라서 OmpException일경우 catch하면 OmpResponseModel을품고있을수있는데, 기서해당 그정 를 인할수도있다. 다만, 생상황에따라 OmpResponseModel이나 그정 숰을수도있다. OmpException을상셏 는예외들에대한정 는다음과같다. ExecutionExceedsException 동시실 수 한을넘어실 되 고하는경우. PathVariableNotFoundException 'URI Path 의변수 (sclbase, sclid, deviceid 등 )' 에해당하는필수값이 null 이거나부 절한경우. HeaderNotFoundException 'Header 값 (authid, authkey 등 )' 이 null 이거나부 절한경우. InputPhaseException 값검증단계에서예외 생한경우. PathVariableNotFoundException 과 HeaderNotFoundException 의상위예외이기도하다. ReadTimeoutException OMP 서버 요청을 낸후부터응 을수신하는동안 Read Timeout 이 생한경우. AfterConnectionPhaseException OMP 서버 요청을 낸후부터응 을수신하는동안예외 생한경우. ReadTimeoutException 의상위예외이기도하다. 14

OmpException 기능처리중 생한것을의미하는기본예외. 또한, ExecutionExceedsException, PathVariableNotFoundException, HeaderNotFoundException, InputPhaseException, AfterConnection- PhaseException 의상위예외이기도하다. 3.2. 안드 이드 Application 개발을위한 Open API Application Module Sample 설명. 안드 이드환경에서의샘플은 Android 4.2.2 버전을기준으 구현되었으며, 샘플의구조는다음과같다. MainActivity 실 되어샘플 을 주는 IndexActivity 넘어간다. 에서샘플을선 하면 의 SampleActivity 실 된다. 15

기능사용방법은일반 바어플레이션과동일하다. 다만, 안드 이드에서는 UI Thread에서네 워크 숯을허용하 않기때문에별도의 Thread 또는 AsyncTask를이용해처리해숗한다. 또한, UI Thread 이외의 Thread에서 View를조 하는것도허용하 않기때문에, 결과값처리는 Handler를이용해숗한다. 3.2.1. 안드 이드특성에따른처리 listgw 메서드에서 Open API Library의기능을이용하고있다. Library 기능은 OMP 서버와 HTTP 통신을하기때문에 listgw 메서드를바 호출하면예외 생한다. 때문에 NetwrokBackRunner라는 Runnable 인터페이스를구현하 별도의스레드를이용해처리하고있다. 그리고그결과값은 Handler에서처리하도 내고있다. UI Thread 이외의 Thread 에서 View 를조 하 하면안드 이드는예외를던진다. 때문에해당 결과값출 을위해 Handler 에처리를위탁해숗하므, ResultRunner 라는 Runnable 인터페이스 16

를구현하 처리토 하였다. Android Sample UI Main 면 GW 동 면 GW 위치측위동 면 GW 주기 고 - 동 면 17

3.2.2. GW 목 GW 등 은 ApplicationRosterSampleActivity.java 를참고한다. 3.2.3. GW 위치측위 GW Profile 은 ApplicationLocationSampleActivity.java 를참고한다. 3.2.4. GW 주기보고 - 목 GW 주기 고는 ApplicationReportSampleActivity.java 를참고한다. 3.3. JAVA Application 개발을위한 Open API Gateway Module Sample 설명 샘플의구조는다음과같다. 18

3.3.1. 초기화샘플프 의초기값은 SampleHelper.java의생성 에 장되어있다. 샘플클래스들은이 SampleHelper를사용해필요한값을취한다. 때문에값을변경해숗할경우 SampleHelper만편집하면 든샘플클래스에 용된다. 따라서이하의메뉴들에선초기값에대한설명은생략한다. 19

3.3.2. GW/Device 등 GW를등 할때는 M2M OMP 포탈의 [ 단말관리 ] 메뉴에서등 신청을하고승인을 은상 숗만 능하다. GW/Device 등 은 GatewayRosterRegSample.java를참고한다. reggw() 는 GW 등 예 다. Gateway Module의 goreg 메서드를사용한다. 이때 sclid와 AuthKey에해당하는값은 null이어숗만한다. 20

반환값으 숪는 ResponseModel 을통해앞으 사용해숗할 sclid 값과 AuthKey 값을숪을수있다. regdevice() 는 Device 등 예 다. 마찬 Gateway Module 의 goreg 메서드를사용한다. 이때필요 한 sclid 와 AuthKey 값은위 extractgw 메서드를 면알수있듯이 GW 를등 하면서숪을수있다. 21

3.3.3. 수집데이터보고 수집데이터 고는 GatewayReportSample.java 를참고한다. Gateway Module의 godata 메서드를사용한다. GW와 Device 두같은메서드를사용하 만, GW인경우에는 deviceid에해당하는값이 null이어숗만한다. 수집데이터 고는 4종류 주기 고 / 이벤 고 / 장애 고 / 장애해 고 이다. 의구분은 ReportType enum 값으 결정된다. 고할데이터 의경우 1회 고에 능한최대크기 2048byte다. 때문에그 다클경우 동으 분할하 반 해서 고를한다. 때문에반환형도 List 형이다. 22

3.3.4. 제어 - 보고 어 - 고 는 GatewayControlReportSample.java 를참고한다. Gateway Module의 gocontrol 메서드를사용한다. GW와 Device 두같은메서드를사용하 만, GW인경우에는 deviceid에해당하는값이 null이어숗만한다. 또한 Header에 TID값이반드시필요한데, 이값은 어-수신 시에 Header를통해숪을수있다. 주의할 은수신 은 TID Base64 인코딩되어있으므, 반드시디코딩한값을 해숗한다. 23

3.3.5. GatewayAuthor GatewayAuthor 는 OMP 에 셏할때 Header 에해당하는정 를 하는클래스다. Author 클래스를상셏 는데, 기본 인기능은이 Author 클래스에 두 고있기에, Gateway 쪽기능 에필요한값의 출 을위한메서드만을 원한다. AuthId, AuthKey, mfid 에해당하는값을 능하며그에따른상수를갖고있다. 3.3.6. OmpResponseModel Gateway Module 의 기능들의기본반환형이다. OMP 와의 셏후 Response-Code 및 Header, Message-Body 정 를갖고있다. 24

이에대한활용법은 GatewayRosterRegSample.java 와 GatewayRosterUnregSample.java 를참고한다. 3.3.7. Exceptions 예외처리는 ExceptionCatcher.java 를참고한다. Gateway Module의 기능들은상황에따라 러 예외를던질수있는데해당예외들은기본 으 OmpException을상셏 고있다. 따라서 OmpException일경우 catch하면 OmpResponseModel을품고있을수있는데, 기서해당 그정 를 인할수도있다. 다만, 생상황에따라 OmpResponseModel이나 그정 숰을수도있다. 25

OmpException 을상셏 는예외들에대한정 는다음과같다. ExecutionExceedsException 동시실 수 한을넘어실 되 고하는경우. PathVariableNotFoundException 'URI Path 의변수 (sclbase, sclid, deviceid 등 )' 에해당하는필수값이 null 이거나부 절한경우. HeaderNotFoundException 'Header 값 (authid, authkey 등 )' 이 null 이거나부 절한경우. InputPhaseException 값검증단계에서예외 생한경우. PathVariableNotFoundException 과 HeaderNotFoundException 의상위예외이기도하다. ReadTimeoutException OMP 서버 요청을 낸후부터응 을수신하는동안 Read Timeout 이 생한경우. AfterConnectionPhaseException OMP 서버 요청을 낸후부터응 을수신하는동안예외 생한경우. ReadTimeoutException 의상위예외이기도하다. OmpException 기능처리중 생한것을의미하는기본예외. 또한, ExecutionExceedsException, PathVariableNotFoundException, HeaderNotFoundException, InputPhaseException, AfterConnection- PhaseException 의상위예외이기도하다. 3.4. 안드 이드 Application 개발을위한 Open API Gateway Module Sample 설명. 샘플의구조는다음과같다. MainActivity 실 되어샘플 을 주는 IndexActivity 넘어간다. 26

에서샘플을선 하면 의 SampleActivity 실 된다. 기능사용방법은일반 바어플레이션과동일하다. 다만, 안드 이드에서는 UI Thread에서네 워크 숯을허용하 않기때문에별도의 Thread 또는 AsyncTask를이용해처리해숗한다. 또한, UI Thread 이외의 Thread에서 View를조 하는것도허용하 않기때문에, 결과값처리는 Handler를이용해숗한다. 3.4.1. 안드 이드특성에따른처리 includegw 메서드에서 Open API Library의기능을이용하고있다. Library 기능은 OMP 서버와 HTTP 통신을하기때문에 includegw 메서드를바 호출하면예외 생한다. 때문에 NetwrokBackRunner라는 Runnable 인터페이스를구현하 별도의스레드를이용해처리하고있다. 그리고그결과값은 Handler에서처리하도 내고있다. 27

UI Thread 이외의 Thread 에서 View 를조 하 하면안드 이드는예외를던진다. 때문에해당 결과값출 을위해 Handler 에처리를위탁해숗하므, ResultRunner 라는 Runnable 인터페이스 를구현하 처리토 하였다. Android Sample UI 28

Main 면 GW Reg 동 면 GW Profile 동 면 GW 주기 고동 면 3.4.2. GW 등 GW 등 은 GatewayRosterRegSampleActivity.java 를참고한다. 3.4.3. GW Profile GW Profile 은 GateweayProfileSampleActivity.java 를참고한다. 3.4.4. GW 주기보고 GW 주기 고는 GatewayReportSampleActivity.java 를참고한다. 29

30