튜토리얼
영화관입장권통합전산망 오픈API 서비스를 이용해 간단한 애플리케이션을 개발하는 튜토리얼입니다.
SOAP 안내
  • • OPEN API > 제공서비스 메뉴로 이동하여 제공되는 서비스를 확인하고 개발에 사용할 서비스를 클릭하여 인터페이스 정보를 확인합니다. 본 튜토리얼에서는 일별 박스오피스를 기준으로 하여 진행합니다.
  • • 이클립스를 통해 프로젝트명을 임의로 입력(K_OpenAPI)하고 Context Root를 /로 하는
    신규 Web Service Project를 생성합니다. (이하 웹 프로젝트)
  • • SOAP 방식의 서비스는 WSDL을 통해 개발환경에 맞는 클라이언트를 구현하여 이용 가능하며, KOBIS OPEN API 에서 제공하는 각 서비스별 WSDL URL은 다음과 같습니다.
    • - 박스오피스: http://www.kobis.or.kr/kobisopenapi/webservice/soap/boxoffice?wsdl
    • - 공통코드: http://www.kobis.or.kr/kobisopenapi/webservice/soap/code?wsdl
  • • 본 예제에서는 OPEN API > 다운로드 페이지에서 제공하는 클라이언트(kobis-opcl-soap-v1.0.jar)를 이용하여 구성합니다.
    예제를 위한 클라이언트 생성은 Apache에서 제공하는 wsdl to java(http://cxf.apache.org/)를 이용하였습니다.
  • • 다운로드 받은 kobis-opcl-soap-v1.0.jar 파일을 웹 프로젝트의 build path(WEB-INF/lib)로 복사하여 호출에 이용합니다.
    (JAR 파일내에 소스를 참고할 수 있습니다.)
  • • 라이브러리로 추가된 오픈API 클라이언트 객체인 KobisOpenAPIRestService 클래스의 서비스별 메소드는 다음과 같습니다.
    • - BoxOfficeAPIServiceImplService: 박스오피스(일별 박스오피스, 주간/주말 박스오피스)
    • - CodeAPIServiceImplService: 공통코드
  • • 서비스 호출 결과 출력을 위한 soapService.jsp 파일을 생성합니다.
  • • soapService.jsp의 import클래스 및 관련 정보는 다음과 같습니다.
    • - 본 튜토리얼에서는 SOAP웹서비스의 결과값을 핸들링하기 위하여 JSTL등을 이용하였습니다.
      관련 정보는 OPEN API > 튜토리얼 메뉴의 튜토리얼 소개 항목을 참고할 수 있습니다.
  • • soapService.jsp 파일에 발급받은 키를 이용하여 일별 박스오피스 SOAP웹서비스를 위한 클라이언트를 호출합니다.
    호출 파라메터는 다음과 같습니다. 본 예제에서는 테스트용 KEY(430156241533f1d058c603178cc3ca0e)를 이용합니다.
    • - BoxOfficeAPIServiceImplService().getBoxOfficeAPIServiceImplPort().searchDailyBoxOfficeList
      (key,targetDt,itemPerPage,multiMovieYn,repNationCd,wideAreaCd)
    • - key: 테스트용 KEY(430156241533f1d058c603178cc3ca0e)를 입력합니다.
    • - 그 외 각 파라메터의 상세 내용은 OPEN API > 제공서비스의 일별 박스오피스 요청 인터페이스를 참고하여 호출합니다.
  • • 요청 인터페이스
  • 요청 변수 값 설명
    key 문자열(필수) 발급받은키 값을 입력합니다.
    targetDt 문자열(필수) 조회하고자 하는 날짜를 yyyymmdd 형식으로 입력합니다.
    itemPerPage 문자열 결과 ROW의 개수를 지정합니다. (default: "10", 최대 : "10")
    multiMovieYn 문자열 다양성 영화/상업영화를 구분지어 조회할 수 있습니다.
    "Y" : 다양성 영화 "N" 상업영화 (default: 전체)
    repNationCd 문자열 한국/외국 영화별로 조회할 수 있습니다.
    "K" : 한국영화 "F" 외국영화 (default: 전체)
    WideAreaCd 문자열 상영지역별로 조회할 수 있으며, 지역코드는 공통코드 조회 서비스에서
    "0105000000"로서 조회된 지역코드입니다. (default: 전체)
  • • KOBIS OPEN API에서 제공하는 SOAP 웹서비스의 결과 반환 구조는 해당 호출 메소드의 반환 클래스를 따르며, 일별 박스오피스의 경우 제공된 클라이언트 클래스 중 DailyBoxOfficeResult 클래스로 반환됩니다.
    • - 멤버변수: String boxofficeType, List dailyBoxOfficeList(조회결과 리스트), String showRange
    • - 메소드: getBoxoffType(), getDailyBoxOfficeList() 등
  • • 앞서 호출한 일별 박스오피스 SOAP웹서비스의 호출 결과값을 이용하여 HTML로 출력하는 예제는 아래와 같습니다.
    결과 컬럼의 상세 내용은 OPEN API > 제공서비스의 일별 박스오피스 응답구조에서 확인 가능합니다.
  • • 응답 구조
  • 응답 필드 값 설명
    boxofficeType 문자열 박스오피스의 종류를 출력합니다.
    showRange 문자열 박스오피스의 조회일자를 출력합니다.
    rnum 문자열 순번을 출력합니다.
    rank 문자열 해당일자의 박스오피스 순위를 출력합니다.
    rankInten 문자열 전일대비 순위의 증감분을 출력합니다.
    rankOldAndNew 문자열 랭킹에 신규 진입여부를 출력합니다. "OLD": 기존, "NEW": 신규
    movieCd 문자열 영화의 대표코드를 출력합니다.
    movieNm 문자열 영화명(국문)을 출력합니다.
    openDt 문자열 영화의 개봉일을 출력합니다.
    salesAmt 문자열 해당일의 매출액을 출력합니다.
    salesShare 문자열 해당일자 상영작의 매출총액 대비 해당 영화이 매출비율을 출력합니다.
    salesInten 문자열 전일 대비 매출액 증감분을 출력합니다.
    salesChange 문자열 전일 대비 매출액 증감비율을 출력합니다.
    salesAcc 문자열 누적매출액을 출력합니다.
    audiCnt 문자열 해당일의 관객수를 출력합니다.
    audiInten 문자열 전일 대비 관객수 증감분을 출력합니다.
    audiChange 문자열 전일 대비 관객수 증감비율을 출력합니다.
    audiAcc 문자열 누적관객수를 출력합니다.
    scrnCnt 문자열 해당일자에 상영한 스크린수를 출력합니다.
    showCnt 문자열 해당일자에 상영된 횟수를 출력합니다.
  • • 신규 서버(TOMCAT)을 생성하여 해당 웹 프로젝트를 시작하고 soapService.jsp 파일을 호출하여 일별 박스오피스의 호출 결과를 확인합니다. (URL: http://localhost:8080/soapService.jsp?targetDt=20120101&itemPerPage=10)