설정

AP to REST의 인터페이스 등록 절차는 아래와 같다.

1. 전문레이아웃 등록

전문레이아웃은 공통부, 개별부의 레이아웃을 등록 관리하는 기능이다. 공통부는 시스템별 공통전문이므로, 엔진설정 시 등록하게 된다. 개별부는 각 인터페이스 담당자가 전문관리 > 전문레이아웃 화면을 이용하여 등록한다.

전문레이아웃은 필드명, 타입, 길이 등의 정보를 포함하는 레이아웃 정보이다. 전문레이아웃 등록 시 반복부 항목이 별도 레이아웃을 가지고 있는 경우에는 하위 레이아웃을 만들어서 처리할 수 있다. 하위 전문레이아웃이 필요한 예는 아래와 같다.

3 01

위의 예처럼 주소정보를 여러 개 관리하는 경우 먼저 우편번호, 주소, 상세주소를 가지는 AddrInfo를 레이아웃으로 등록한다. 그 다음 id, pw와 주소정보의 레이아웃인 AddrInfo를 포함하는 UserInfo 레이아웃을 작성한다.

전문은 버전을 가지고 있으며, 업무 변경에 따른 인터페이스에 사용되는 전문레이아웃 ID 단위로 변경된 내역을 관리하기 위하여 사용된다. 인터페이스의 전문레이아웃이 변경되었을 때, 기존 레이아웃 정보를 수정하고 버전을 올려 등록하면, 전문레이아웃화면을 통해 현재 버전 및 과거 버전에 대한 변경 내역을 확인할 수 있다.

1.1. 등록 절차

  1. 전문관리 > 전문레이아웃 화면에서 그리드 우측 상단 버튼을 클릭하여 신규 전문레이아웃 등록화면을 실행한다.

  2. 우측상단의 행 추가 버튼을 클릭하여 전문의 각 필드항목 필드명 및 타입, 길이 등을 설정하여 등록한다.

1.1.1. 기본 정보

  • Version: 환경설정 > 레이아웃버전관리 화면에 등록된 버전을 선택한다.

  • 대상스페이스명: XML의 네임스페이스명을 입력한다. 미입력 시 레이아웃ID가 네임스페이스명이 된다.

  • Root 엘리먼트명: JSON이나 XML 전문의 Root 엘리먼트명을 입력한다. 미입력 시 레이아웃ID가 Root 엘리먼트명이 된다.

  • 복사전문레이아웃: 기등록된 전문레이아웃을 복사하여 새로운 레이아웃을 생성한다.

1.1.2. 필드 정보

컬럼 설명

엘리먼트명

JSON이나 XML 전문에서 사용할 필드의 엘리먼트명을 의미한다. 입력하지 않으면 필드명이 엘리먼트명이 된다.

필드명

필드의 영문명을 의미한다.

필드설명

필드의 설명을 의미한다.

타입

등록 가능한 데이터 타입은 Boolean, Byte 등이 있다. 해당 데이터 타입은 java의 데이터타입과 동일하며, 그 중 DTO선택의 경우 전문 레이아웃으로 등록된 레이아웃을 의미한다.

길이

필드의 길이를 의미한다.

Offset

필드의 Offset 값을 의미한다.

Decimal 길이

필드의 소수점 이하의 길이를 의미한다.

Format

해당 필드의 날짜, 시간과 관련된 포맷을 의미한다.

Array참조필드

반복될 전문 레이아웃의 크기 값을 가진 필드명이나 또는 반복 횟수를 직접 입력하는 항목을 의미한다.

암복호화

필드의 암복호화 사용여부를 의미한다. 암복호화 처리정보는 엔진설정 시 등록되고, 전문레이아웃에서는 사용여부를 선택한다.

코드변환

필드의 코드변환 방식을 의미한다. ASCII, EBCDIC 등 인코딩, 디코딩에 사용할 코드변환 방식을 등록한다.

기본값

필드가 null일 경우(입력되지 않은 경우)에 사용할 기본값을 의미한다.

정렬

해당 필드의 정렬 방식으로 left, right 값 중 하나를 가진다. 타입이 String일 경우엔 left, int 등의 숫자일 경우엔 right가 기본값이 된다.

한글필드여부

해당 필드가 전체 2Bytes 한글 필드 형식으로 되어 있는지 여부를 의미한다.

2. 인터페이스 등록

인터페이스관리 > 온라인인터페이스 화면을 이용하여 등록한다. 인터페이스ID, 인터페이스명은 인터페이스를 식별할 수 있는 값으로 설정한다.

각 구성항목에 대한 설명은 다음과 같다.

2.1. 구성항목

2.1.1. 기본정보

  • 기관코드: 기관코드

  • 대외업무코드: 기관에서 사용할 업무코드

  • 시스템코드: 시스템코드

  • 대내업무코드: 시스템에서 사용할 업무코드

  • 서비스코드: 호출 시 동일 URL을 사용하고, 공통부의 서비스코드를 사용하는 방식에서 공통부의 서비스코드의 값을 등록한다. 기본설정관리 > 시스템별업무 화면에서 서비스호출구분코드가 URL방식이면 대신 컨텍스트URL을 설정할 수 있는데, 이는 URL 단위로 호출하는 방식일 때 호출 URL을 정의한다.

  • 동기여부: 동기/비동기 방식에 대한 설정

  • 응답여부: 응답유무 설정

  • 요청구분: 대외 기관에서 요청하는 거래면 대외요청, 대내 시스템에서 요청하는 거래면 대내요청

  • 요청 플로우: 요청처리 시 사용할 플로우

  • 응답 플로우: 응답처리 시 사용할 플로우

2.1.2. 전문정보

  • 요청전문레이아웃: 요청전문 레이아웃

  • 응답전문레이아웃: 응답전문 레이아웃

  • 요청공통부전문변환: 요청전문의 공통헤더부를 변환하기 위한 변환정보

  • 응답공통부전문변환: 응답전문의 공통헤더부를 변환하기 위한 변환정보

  • 요청개별부전문변환: 요청전문레이아웃을 등록한 경우 전문을 변환하기 위한 변환정보

  • 응답개별부전문변환: 응답전문레이아웃을 등록한 경우 전문을 변환하기 위한 변환정보

요청/응답 전문레이아웃 등록

전문레이아웃은 요청전문레이아웃과 응답전문레이아웃을 등록한다. 요청전문레이아웃은 그림에서 1번에 해당하고, 응답전문레이아웃은 그림에서 2번에 해당한다.

2.1.3. 추가정보

  • 거래제어구분: 수신서비스의 장애 등의 사유로 인터페이스의 거래를 제어하고 싶은 경우에 사용된다. 거래제어가 되면 수신서비스로 전달되지 않고, 설정값에 따라 무응답처리나 에러응답처리를 할 수 있다. 에러응답프로그램은 엔진설정 시 정의된다.

  • 유량제어ID: 인터페이스에 적용할 유량제어 정책. 처리건수 방식을 지원한다.

  • 타임아웃시간(초): 응답이 오지 않는 경우 타임아웃처리를 위한 시간설정

  • 타임아웃응답여부: 타임아웃시 응답을 줄것인지 여부

  • 전송에러응답여부: 전송에러나 타임아웃 발생시 에러응답 전문을 생성하여 요청기관으로 전송할것인지 여부

  • 플로우처리로깅여부: 라우터 입출력에 대해서 로깅할것인지 여부

  • 루트엘리먼트명: 전문마샬시 바디의 루트엘리먼트명이 data가 아닌 해당 루트엘리먼트명으로 전환

3. 전문변환 등록

AP to REST 거래는 헤더부가 존재하지 않으므로 개별부만 필요시에 전문변환을 진행한다.

전문변환은 요청과 응답에 대해서 각각 이루어진다. 따라서, 전문변환 등록 시 요청과 응답에 대해서 각각 전문변환 정보를 등록해야 한다.

요청/응답 구분 및 입력/출력 전문 설명

전문변환은 입력전문을 출력전문으로 변환하는 정보를 등록하는 것이므로, 전문관리 > 전문변환 화면에서 입력과 출력전문을 선택하고 매핑정보를 등록한다. 전문변환은 입력과 출력전문을 항목을 매핑하는 기능 외에도 출력전문에 상수나 시스템일자 등을 설정할 수 있다.

rest fep msg change2
rest fep msg change

REST 거래는 REST 연계쪽에 헤더부가 존재하지 않는다.

3.1. 등록 절차

  1. 전문관리 > 전문변환 화면에서 전문변환종류를 각각의 전문변환 타입으로 선택한다.

  2. 공통부 전문변환 혹은 개별부 전문변환의 경우, 요청응답구분코드를 요청이나 응답을 선택한다.

  3. 전문변환 대상 입력레이아웃과 출력레이아웃을 등록한 후, 1:1매핑 버튼을 눌러 매핑한다.

  4. 정보등록이 완료되면 저장버튼을 눌러 완료한다.

전문변환에 등록된 매핑정보 외에 추가적인 매핑이 필요한 경우, 사용자프로그램을 호출해 매핑할 수 있다. 전문변환에 등록된 매핑 이후 호출된다.

3.2. 전문변환 종류

3.2.1. 공통부 전문변환

REST 거래는 공통부 전문변환하지 않는다.

3.2.2. 개별부 전문변환

개별부 전문변환은 입력으로 수신한 전문의 개별부에 해당하는 부분을 서비스 입력의 개별부에 맞게 변환(매핑)하는 것을 말한다. 요청, 응답의 전문변환을 각각 등록해야 한다.

3.2.3. 반복부 전문변환

반복부 전문변환은 재사용 가능한 하위 전문레이아웃을 대상으로 전문변환을 등록하는것을 말한다. 등록된 반복부 전문변환 정보는 재사용할 수 있다.

3.3. 매핑정보

컬럼 설명

속성명

입력 레이아웃의 필드명 중 하나를 선택한다. 출력 레이아웃의 필드에 선택한 입력 레이아웃의 필드 데이터가 저장된다.

상수

특정 상수값을 입력한다. 출력 레이아웃의 필드에 입력한 상수 값이 저장된다.

스페셜워드

스페셜 워드의 의미에 따라서 값을 설정한다. 예를 들어 GUID를 선택하면 출력 레이아웃의 필드에 생성된 GUID값이 저장된다. 현재 기본 스페셜워드는 GUID만 있다. 자세한 내용은 사용자 스페셜 워드 처리 방법을 참조한다.

시스템데이트

현재 일자나 시간의 포맷을 목록에서 선택한다.

스크립트

입력 값에 대한 보정이 필요할 경우 해당 script를 입력한다. 자세한 내용은 스크립트를 참조한다.

서브매핑

서브 레이아웃인 경우 반복부 전문변환에서 등록한 서브매핑을 선택한다.

변환없음

해당 출력 레이아웃 필드에 데이터가 저장되지 않는다.

3.3.1. 사용자 스페셜 워드 처리 방법

사용자가 정의한 스페셜 워드 처리 방식은 사용자 프로그램을 이용하여 처리한다.

사용자는 사용자 스페셜 워드를 처리할 프로그램을 개발하고 스페셜 워드를 정하여 specialword.properties에 등록한다. 사용자 스페셜 워드는 워드별로 유니크한 이름으로 등록해야 한다. 사용자 스페셜 워드 등록 절차은 아래와 같다.

  1. 사용자 스페셜 워드를 처리할 프로그램을 스프링 빈 프로그램으로 개발한다.

  2. 기본설정관리 > 프로그램정보 화면에서 개발한 프로그램을 등록한다.

  3. specialword.properties파일에 스페셜 워드와 사용자 프로그램을 매핑하여 등록한다.

아래는 사용자 스페셜 워드를 등록한 예제이다.

${BXIHOME}/config/specialword.properties
# Special word for message transformation
# form: upper case special word=user bean program id
SEQUENCE_NO=customSequenceNumber

3.3.2. 스크립트

설정값 설명

substring

문자열을 분리한다. ex) txCode.substring(1,4)

toUpperCase

문자열을 대문자로 변환한다. ex) txCode.toUpperCase()

toLowerCase

문자열을 소문자로 변환한다. ex) txCode.toLowerCase()

lpad

문자열의 왼쪽을 주어진 숫자만큼 패딩한다. 패딩할 문자열이 지정되지 않은 경우 0으로 패딩한다. ex) txCode.lpad(10,A), txCode.lpad(10)

rpad

문자열의 오른쪽을 주어진 숫자만큼 패딩한다. 패딩할 문자열이 지정되지 않은 경우 0으로 패딩한다. ex) txCode.rpad(10), txCode.rpad(10,A)

value

입력 레이아웃의 데이터를 특정 값으로 변환한다. 오른쪽 예시는 txCode의 값이 source1인 경우엔 target1, source2인 경우에는 target2로 변환한다. ex) txCode.value(source1=target1, source2=target2)

4. REST 정보 등록

AP to REST는 도메인별 공통적으로 사용되는 속성들의 정의가 필요하다. 프로토콜구분, 호스트, 포트번호와 같은 공통 정보가 등록되며, RESTful 지원을 위한 상세 정보는 API정보를 통해 등록한다.

해당 설정은 기관(REST연계) 설정이며, 시스템 설정은 기존 AP to AP와 동일하다.

4.1. 도메인정보

API정보관리 > 도메인정보 화면에서 등록한다.

4.1.1. 구성항목

기본정보
  • 커넥션구분: 해당 도메인의 서버/클라이언트 구분을 등록한다.

  • 프로토콜구분: 도메인이 사용할 프로토콜을 HTTP/HTTPS 중에서 선택하여 등록한다.

  • 통신방식: 해당 도메인의 통신방식을 REST와 SOAP 중 선택하여 등록한다.

커넥션구분
  • 서버 도메인: 외부에서 BXI 엔진으로 들어오는 인바운드 REST 거래 시 사용한다. 정상적으로 등록했다면 엔진 기동 시 서버의 해당 포트가 LISTEN상태로 오픈된다.

  • 클라이언트 도메인: BXI 엔진이 외부로 요청하는 아웃바운드 REST 거래 시 사용한다.

URL정보
  • URL: IP와 PORT를 포함한 도메인의 URL정보를 등록한다.

  • 노드ID: URL이 오픈될 노드를 등록한다. 해당 도메인이 서버인 경우에만 활성화된다.

  • 인스턴스ID: URL이 오픈될 인스턴스를 등록한다. 해당 도메인이 서버인 경우에만 활성화된다.

CORS정보
  • Access Control Allow Origins: 해당 도메인이 서버인 경우, CORS 요청 처리를 위해 등록한다. 등록된 도메인으로부터의 요청만 서버의 리소스에 접근할 수 있게 한다.

  • Access Control Allow Headers: Access Control Allow Origins을 등록한 경우, 요청에서 사용할 수 있는 HTTP Header를 지정한다.

  • Access Control Allow Methods: Access Control Allow Origins을 등록한 경우, 서버의 리소스에 접근할 수 있는 HTTP Method 방식을 지정한다.

추가정보
  • 최대송수신전문길이: 한번에 송수신가능한 최대 전문길이를 제한한다.

  • 프록시 ID: 프록시 사용 시 등록한다.

  • 폴링 IP: 해당 도메인에 대한 폴링 IP를 등록한다.

  • 정상상태 코드 범위: 대상 도메인에 대한 REST 거래시 반환되는 상태코드 값의 정상범위를 설정한다.

4.2. API 정보

API 정보는 URI Path별로 등록되며, 상태 관리의 대상이 된다. 하위에 다수의 Method 정보가 구성될 수 있다. API정보관리 > API정보 화면에서 등록한다.

rest api

4.2.1. 등록 절차

좌측 트리에 기정의된 도메인 정보가 표시되며, 우측에는 API 목록과 상세 정보가 표시된다. 해당 도메인에서 마우스 우클릭 후, API 등록을 선택하여 API 정보를 등록한다.

4.2.2. 구성항목

기본정보
  • API상태코드: API 서비스의 현재 상태

설정값 설명

CREATED

해당 API가 생성 상태임을 의미

PUBLISHED

해당 API가 가 사용 가능한 상태임을 의미

BLOCKED

해당 API가 중지 상태임을 의미

DEPRECATED

해당 API가 더 이상 제공되지 않음을 의미

추가정보
  • 암호화방식: API의 암복호화 방식을 설정한다. 암복호화를 참조한다.

  • 송수신 암복호화 여부: 암호화방식이 '전체전문 암복호화’일 경우 표현된다.

설정값 설명

양방향

송신할 때 암호화, 수신할 때 복호화한다.

송신

송신할 때만 암호화한다.

수신

수신할 때만 복호화한다.

  • HTTP헤더처리프로그램: HTTP 헤더를 처리할 프로그램. 라우터 프로그램을 참조한다.

4.3. Method

Method 정보는 RESTful 방식의 인터페이스를 처리하기 위한 설정 정보이다.

rest method

4.3.1. 등록 절차

API별 6가지의 Method 정보(GET, POST, PUT, DELETE, PATCH, HEAD) 등록이 가능하다.

  1. 해당 API를 클릭한다.

  2. 등록하고자 하는 Method 타입의 체크박스를 선택하여 메소드정보를 설정한다.

  3. 기등록된 인터페이스 ID를 선택한다.

  4. 선택한 인터페이스에 등록된 요청/응답 전문레이아웃이 자동으로 등록 된다. 필요 시 다른 전문으로 변경할 수 있다.

4.3.2. 구성항목

  • 인터페이스ID: 해당 Method로 처리할 인터페이스의 ID를 선택한다. 인터페이스 ID는 온라인인터페이스 화면을 통하여 등록한 인터페이스이어야 한다.

  • 요청/응답 미디어타입: 요청과 응답 시에 사용할 미디어타입을 등록한다.

rest msg inbound fep
rest msg outbound fep
  • 요청파라미터

    • REST 인바운드 : REST 거래시 BXI가 파라미터들을 어떻게 받아들일 것인지를 정의한다.

    • REST 아웃바운드 : REST 거래시 BXI가 파라미터들을 어떻게 전송할 것인지를 정의한다.

  • 응답파라미터

    • REST 인바운드 : REST 거래시 BXI가 파라미터들을 어떻게 전송할 것인지를 정의한다.

    • REST 아웃바운드 : REST 거래시 BXI가 파라미터들을 어떻게 받아들일 것인지를 정의한다.

파라미터 타입
설정값 설명

BODY

요청/응답의 페이로드로 사용될 파라미터

QUERY

GET 메소드 요청 URL에 사용될 파라미터

HEAD

커스텀 헤더에 사용될 파라미터

PATH

URL 패스에 사용될 파라미터

4.4. 예시

REST 인바운드 거래를 예시로 들어서 설명한다.

rest example

URL 패턴이 0.0.0.0:57013/inbound001/{address}/abc/v21이므로, 요청파라미터 중 'address’는 PATH 타입으로 정의되어야 한다. BXI는 이 URL을 외부에 오픈하고 요청을 기다린다. 외부에서 해당 URL로 HTTP 요청이 들어오면, BXI는 REST 인바운드 거래를 진행한다.

예를 들어 외부에서 아래와 같이 HTTP 요청을 한다고 가정했을 때, BXI는 정의된 요청파라미터에 따라 'name=hong' 및 'address=seoul’로 값을 채워넣고 내부 플로우를 진행한다.

curl -X POST -d '{"name":"hong"}' -H "Content-Type:application/json" http://0.0.0.0:57013/inbound001/seoul/abc/v21

REST 인바운드에서 응답파라미터는 응답을 어떻게 돌려줄 것인지를 의미한다. 위 예시에서는 'name’과 'address’가 모두 BODY로 정의되어 있기 때문에 응답은 '{"name":"xxx..", "address":"xxx.."}' 형태로 반환된다. 만약 응답파라미터 중 'name’이 HEAD, 'address’는 BODY로 지정되어 있다면 응답 시 바디에는 'address’만 포함되고, 'name’은 헤더에 포함된다.

4.5. REST 비동기 거래

REST 거래는 기본적으로 동기 거래이지만, BXI는 비동기 거래도 지원한다. 비동기 거래는 200 응답을 받는 것을 특징으로 한다.

  • REST 인바운드 비동기: REST 인바운드 비동기 거래는 하나의 동기 응답 인터페이스로 진행한다.

  1. 인터페이스관리 > 온라인인터페이스 화면에서 동기여부를 동기, 응답여부를 응답으로 설정한다. (기존 동기거래와 동일)

  2. API정보관리 > API정보 화면에서 클라이언트 모드에 동기여부를 비동기로 설정하여 응답API를 등록한다. 응답으로 보내고자 하는 응답미디어타입 & 응답파라미터를 등록한다. (요청은 등록하지않는다.)

  3. API정보관리 > API정보 화면에서 서버 모드에 동기여부를 비동기로 설정하여 응답API를 등록한다. 서버 모드를 비동기 선택시, 응답AIP과 응답 Method를 위에 등록했던 클라이언트 API로 등록한다. 요청파라미터를 등록한다. (응답은 등록하지않는다.)

아래 그림은 0.0.0.0:57013/inbound001/abc로 POST 거래를 입력받아 내부 시스템에 전달한 후, 내부 시스템으로부터 받은 응답을 요청한 곳이 아닌 localhost:6020/api/v1/clientAuth/car-service/connected의 DELETE 방식으로 응답하는 거래의 예시이다.

rest inbound async req
rest inbound async res
  • REST 아웃바운드 비동기: REST 아웃바운드 비동기 거래는 비동기 무응답 인터페이스 2개로 진행한다.

  1. 인터페이스관리 > 온라인인터페이스 화면에서 동기여부를 비동기, 응답여부를 무응답, 요청구분을 대내요청으로 요청 인터페이스를 등록한다. (무응답이므로 타이머를 해제할 수 없으므로 요청 플로우에서 타이머 등록 제외)

  2. 인터페이스관리 > 온라인인터페이스 화면에서 동기여부를 비동기, 응답여부를 무응답, 요청구분을 대외요청으로 응답 인터페이스를 등록한다. (무응답이므로 타이머를 해제할 수 없으므로 요청 플로우에서 타이머 등록 제외)

  3. API정보관리 > API정보 화면에서 클라이언트 모드에 동기여부를 비동기로 API를 등록한다.

  4. API정보관리 > API정보 화면에서 서버 모드에 동기여부를 비동기로 API를 등록한다. (응답URL, 응답파라미터는 등록하지않는다. 응답Method는 변경해도 실제로 적용되지 않음)

REST 아웃바운드 비동기는 요청과 응답이 별개의 인터페이스로 처리되므로, 로그모니터링 > 거래내역조회 화면에서 한 번의 거래당 두 개의 거래내역이 표시된다.

REST 아웃바운드 비동기 응답

REST 아웃바운드 비동기 거래는 타겟으로 요청을 보낸 후, 타겟이 4번에 과정에서 등록한 서버로 다시 요청을 주어야 응답 처리가 가능하다.

SWLab Bankware Global
  • 전체
  • BXM
  • BXCM
  • BXCP
  • BXI
제품 선택 시 더 정확한 매뉴얼 가이드를 제공해드립니다.

Copyright© Bankwareglobal All Rights Reserved.