관리

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

1. 전문레이아웃 등록

전문레이아웃은 공통부, 개별부의 레이아웃을 등록 관리하는 기능이다.

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

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

하위 전문레이아웃이 필요한 예는 아래와 같다.

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

전문은 버전을 가지고 있는데, 업무변경으로 인한 인터페이스에 사용되는 전문레이아웃 ID단위로 변경된 내역을 관리하기 위하여 사용된다.

인터페이스의 전문레이아웃이 변경되었을때 기존 레이아웃정보를 수정하고 버전을 올려 등록하면, 전문레이아웃화면을 통해 현재버전 및 과거버전에 대한 변경내역을 확인할 수 있다.

등록절차

1. 전문관리 > 전문레이아웃화면에서 그리드 우측 상단 버튼을 클릭하여 신규 전문레이아웃 등록화면을 실행한다.
2. 우측상단의 행 추가 버튼을 클릭하여 전문의 각 필드항목 필드명 및 타입, 길이등을 설정하여 등록한다.

☑ 기본 정보

• Version : 환경설정 > 레이아웃버전관리에 등록된 버전을 선택한다.
• 대상스페이스명 : XML의 네임스페이스명을 입력한다. 미입력 시 레이아웃ID가 네임스페이스명이 된다.
• Root엘리먼트명 : JSON이나 XML 전문의 Root 엘리먼트명을 입력한다. 미입력 시 레이아웃ID가 Root엘리먼트명이 된다.
• 복사전문레이아웃 : 기등록된 전문레이아웃을 복사하여 새로운 레이아웃을 생성한다.

☑ 필드 정보

컬럼	설명
엘리먼트명	JSON이나 XML 전문에서 사용할 필드의 엘리먼트명을 의미한다. 입력하지 않으면 필드명이 엘리먼트명이 된다.
필드명	필드의 영문명을 의미한다.
필드설명	필드의 설명을 의미한다.
타입	등록 가능한 데이터 타입은 Boolean, Byte 등이 있다. 해당 데이터 타입은 java의 데이터타입과 동일하며, 그 중 DTO선택의 경우 전문 레이아웃으로 등록된 레이아웃을 의미한다.
길이	필드의 길이를 의미한다.
Offset	필드의 Offset 값을 의미한다.
Decimal 길이	필드의 소수점 이하의 길이를 의미한다.
Format	해당 필드의 날짜, 시간과 관련된 포맷을 의미한다.
Array참조필드	반복될 전문 레이아웃의 크기 값을 가진 필드명이나 또는 반복 횟수를 직접 입력하는 항목을 의미한다.
암복호화	필드의 암복호화 사용여부를 의미한다. 암복호화 처리정보는 엔진설정 시 등록되고, 전문레이아웃에서는 사용여부를 선택한다.
코드변환	필드의 코드변환 방식을 의미한다. ASCII, EBCDIC 등 인코딩, 디코딩에 사용할 코드변환 방식을 등록한다.
기본값	필드가 null일 경우(입력되지 않은 경우)에 사용할 기본값을 의미한다.
정렬	해당 필드의 정렬 방식으로 left, right 값 중 하나를 가진다. 타입이 String일 경우엔 left, int 등의 숫자일 경우엔 right가 기본값이 된다.
한글필드여부	해당 필드가 전체 2Bytes 한글 필드 형식으로 되어 있는지 여부를 의미한다.

2. 인터페이스 등록

인터페이스 관리 > 온라인인터페이스화면을 이용하여 등록한다. 인터페이스ID, 인터페이스명은 인터페이스를 식별할 수 있는 값으로 설정한다. 각 구성항목에 대한 설명은 다음과 같다.

구성항목

☑ 기본정보

• 기관코드 : 기관코드
• 대외업무코드 : 기관에서 사용할 업무코드
• 시스템코드 : 시스템코드
• 대내업무코드 : 시스템에서 사용할 업무코드
• 적용일자 : 해당 인터페이스를 적용할 날짜. 당일부터 실행하고자 하는 경우, 오늘 이전 날짜를 등록한다.
• 서비스코드 : 호출 시 동일 URL을 사용하고, 공통부의 서비스코드를 사용하는 방식에서 공통부의 서비스코드의 값을 등록한다. 기본설정관리 > 시스템별업무에서 서비스호출구분코드가 URL방식이면 대신 컨텍스트URL을 설정할 수 있는데, 이는 URL 단위로 호출하는 방식일 때 호출 URL을 정의한다.
• 동기여부 : 동기/비동기 방식에 대한 설정
• 응답여부 : 응답유무 설정
• 요청구분 : 대외기관에서 요청하는 거래면 대외요청, 대내시스템에서 요청하는 거래면 대내요청
• 요청플로우 : FEP에서 요청처리 시 사용할 플로우
• 응답플로우 : FEP에서 응답처리 시 사용할 플로우

☑ 전문정보

• 요청전문레이아웃 : 송신시스템의 요청전문 레이아웃
• 응답전문레이아웃 : 수신시스템의 응답전문 레이아웃
• 요청공통부전문변환 : 요청전문의 공통헤더부를 변환하기 위한 변환정보
• 응답공통부전문변환 : 응답전문의 공통헤더부를 변환하기 위한 변환정보
• 요청개별부전문변환 : 요청전문레이아웃을 등록한 경우 전문을 변환하기 위한 변환정보
• 응답개별부전문변환 : 응답전문레이아웃을 등록한 경우 전문을 변환하기 위한 변환정보

☑ 추가정보

• 요청사용자프로그램 : 대내시스템의 대상서비스 또는 대외기관에 서비스를 요청하기 전에 특별한 처리가 필요한 경우 설정한다.
• 응답사용자프로그램 : 대내시스템의 대상서비스 또는 대외기관에 응답을 전송하기 전에 특별한 처리가 필요한 경우 설정한다.
• 거래제어구분 : 수신서비스의 장애 등의 사유로 인터페이스의 거래를 제어하고 싶은 경우에 사용된다. 거래제어가 되면 수신서비스로 전달되지 않고, 설정값에 따라 무응답처리나 에러응답처리를 할 수 있다. 에러응답프로그램은 엔진설정 시 정의된다.
• 유량제어ID : 인터페이스에 적용할 유량제어 정책. 처리건수 방식을 지원한다.
• 타임아웃시간(초) : 응답이 오지 않는 경우 타임아웃처리를 위한 시간설정
• 타임아웃응답여부 : 타임아웃시 응답을 줄것인지 여부
• 전송에러응답여부 : 전송에러나 타임아웃 발생시 에러응답 전문을 생성하여 요청기관으로 전송할것인지 여부
• 지연응답전송여부 : 타임아웃 처리 후에 응답을 수신한 경우, 대내시스템에 전송할 것인지 여부
• 플로우처리로깅여부 : 라우터 입출력에 대해서 로깅할것인지 여부
• 루트엘리먼트명 : 전문마샬시 바디의 루트엘리먼트명이 data가 아닌 해당 루트엘리먼트명으로 전환

위의 설명한 항목 중 인터페이스 처리상세 유형 및 요청/응답 전문레이아웃의 위치는 아래에서 자세하게 설명한다.

요청/응답 전문레이아웃의 위치

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

3. 전문변환 등록

REST 거래는 REST연계쪽(기관, 시스템)이 해더부가 존재하지않으므로 개별부만 필요시에 전문변환을 진행한다.

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

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

노트

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

등록과정

1. 전문관리 > 전문변환에서 전문변환종류를 각각의 전문변환 타입으로 선택한다.
2. 공통부 전문변환 혹은 개별부 전문변환의 경우, 요청응답구분코드를 요청이나 응답을 선택한다.
3. 전문변환 대상 입력레이아웃과 출력레이아웃을 등록한 후, 1:1매핑 버튼을 눌러 매핑한다.
4. 정보등록이 완료되면 저장버튼을 눌러 완료한다.

정보

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

전문변환 종류

공통부 전문변환

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

개별부 전문변환

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

반복부 전문변환

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

매핑정보

컬럼	설명
속성명	입력 레이아웃의 필드명 중 하나를 선택한다. 출력 레이아웃의 필드에 선택한 입력 레이아웃의 필드 데이터가 저장된다.
상수	특정 상수값을 입력한다. 출력 레이아웃의 필드에 입력한 상수 값이 저장된다.
스페셜워드	스페셜 워드의 의미에 따라서 값을 설정한다. 예를 들어 GUID를 선택하면 출력 레이아웃의 필드에 생성된 GUID값이 저장된다. 현재 기본 스페셜워드는 GUID만 있다. 자세한 내용은 사용자 스페셜 워드 처리 방법을 참조한다.
시스템데이트	현재 일자나 시간의 포맷을 목록에서 선택한다.
스크립트	입력 값에 대한 보정이 필요할 경우 해당 script를 입력한다. 자세한 내용은 스크립트를 참조한다.
서브매핑	서브 레이아웃인 경우 반복부 전문변환에서 등록한 서브매핑을 선택한다.
변환없음	해당 출력 레이아웃 필드에 데이터가 저장되지 않는다.

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

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

사용자는 사용자 스페셜 워드를 처리할 프로그램을 개발하고 스페셜 워드를 정하여 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

☑ 스크립트

설정값	설명
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정보 등록

BXI의 APtoAP 인터페이스 중 REST방식을 사용하는 경우, 도메인별 공통적으로 사용되는 속성들의 정의가 필요하다. 프로토콜구분, 호스트, 포트번호와 같은 공통 정보가 등록되며, Restful지원을 위한 상세 정보는 API정보를 통해 등록한다.

정보

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

도메인정보

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

구성항목

☑ 기본정보

• 커넥션구분 : 해당 도메인의 서버/클라이언트 구분을 등록한다.
• 프로토콜구분 : 도메인이 사용할 프로토콜을 HTTP/HTTPS 중에서 선택하여 등록한다.
• 통신방식 : 해당 도메인의 통신방식을 REST와 SOAP 중 선택하여 등록한다.
• 적용일자 : 해당 도메인을 적용할 날짜. 당일부터 실행하고자 하는 경우, 오늘 이전 날짜를 등록한다.

커넥션구분

• 서버 도메인 : 외부에서 BXI엔진으로 들어오는 인바운드 REST거래 시 사용한다. 정상적으로 등록했다면 엔진 기동 시 서버의 해당 포트가 LISTEN상태로 오픈된다.
• 클라이언트 도메인 : BXI엔진이 외부로 요청하는 아웃바운드 REST거래 시 사용한다.

☑ 기본정보

• 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 거래시 반환되는 상태코드 값의 정상범위를 설정한다.

API정보

API정보는 Restful인터페이스를 지원하기 위한 상세 정보를 의미하며, API와 Method로 구분된다.

API정보관리 > API정보에서 등록한다.

1. API

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

등록과정

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

구성항목

☑ 기본정보

• API상태코드 : API 서비스의 현재 상태

설정값	설명
CREATED	해당 API가 생성 상태임을 의미
PUBLISHED	해당 API가 가 사용 가능한 상태임을 의미
BLOCKED	해당 API가 중지 상태임을 의미
DEPRECATED	해당 API가 더 이상 제공되지 않음을 의미

• 적용일자 : 해당 API를 적용할 날짜. 당일부터 실행하고자 하는 경우, 오늘 이전 날짜를 등록한다.

☑ 추가정보

• 암호화방식 : API의 암복호화 방식을 설정한다. 암복호화를 참조한다.
• 송수신 암복호화 여부 : 암호화방식이 '전체전문 암복호화'일 경우 표현된다.

설정값	설명
양방향	송신할 때 암호화, 수신할 때 복호화한다.
송신	송신할 때만 암호화한다.
수신	수신할 때만 복호화한다.

• HTTP헤더처리프로그램 : HTTP 헤더를 처리할 프로그램. 커스터마이징을 참조한다.

2. Method

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

등록과정

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

1. 해당 API를 클릭한다.
2. 등록하고자 하는 Method 타입의 체크박스를 체크해 메소드정보를 설정한다.
3. 기등록된 인터페이스 ID를 선택한다.
4. 선택된 인터페이스ID에 등록된 요청/응답파라미터가 자동등록되지만, 필요시에 다른 전문으로 바꿔준다.

구성항목

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

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

  

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

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

파라미터타입

설정값	설명
BODY	요청/응답의 페이로드로 사용될 파라미터
QUERY	GET 메소드 요청 URL에 사용될 파라미터
HEAD	커스텀 헤더에 사용될 파라미터
PATH	URL 패스에 사용될 파라미터

예시

REST INBOUND거래를 예시로 들어서 설명한다.

URL pattern이 http://0.0.0.0:57013/inbound001/{address}/abc/v21이므로, 요청파라미터 address 파라미터 타입이 PATH로 정의되어있어야한다. BXI는 해당 URL을 외부에 오픈시켜놓고 요청을 기다린다. 외부에서 해당 URL로 HTTP요청을 하면 BXI는 REST INBOUND거래를 진행한다.

예를들어 외부에서 curl -X POST -d '{"name":"hong"}' -H "Content-Type:application/json" http://0.0.0.0:57013/inbound001/seoul/abc/v21로 HTTP 요청을 했을때, BXI는 정의된 요청파라미터에 의하여 name=hong, address=seoul으로 값을 채워넣고 BXI 내부 플로우를 진행한다.

REST INBOUND에서 응답파라미터는 RESTFul방식으로 응답을 어떻게 돌려줄것인가를 의미한다. 해당 예시에는 name, address가 둘다 BODY로 정의되어있기때문에 {"name":"xxx..", "address":"xxx.."} 으로 응답을 준다. 만약 응답파라미터의 name이 HEAD, address는 BODY로 파라미터파입이 지정되었다면 응답 시 바디부에 address만 포함되며, name은 해더옵션으로 포함된다.

REST 비동기 거래

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

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

1. 인터페이스관리 > 온라인인터페이스에서 동기여부를 동기, 응답여부를 응답으로 설정한다. (기존 동기거래와 동일)
2. API정보관리 > API정보에서 서버모드에 동기여부를 비동기로 API를 등록한다. 서버모드는 비동기 선택시, 응답URL과 응답 Method를 입력할 수 있다.
3. 요청, 응답파라미터를 설정한다. REST 인바운드 비동기에서 응답파라미터는, 응답Method방식으로 응답URL에 데이터를 전송하려는 사실상의 요청파라미터로 인식하면 된다.

아래 그림은, http://0.0.0.0:57013/inbound001/abc로 POST거래를 입력받아 내부시스템에 전달 후, 내부시스템으로부터 받은 응답을 요청한곳이 아니라 http://localhost:6020/rest/{address}로 DELETE방식으로 요청하는 거래의 예시이다.

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

1. 인터페이스관리 > 온라인인터페이스에서 동기여부를 비동기, 응답여부를 무응답, 요청구분을 대내요청으로 요청인터페이스를 등록한다. (무응답이므로 타이머를 해제할수없으므로 요청플로우에서 타이머등록 제외)
2. 인터페이스관리 > 온라인인터페이스에서 동기여부를 비동기, 응답여부를 무응답, 요청구분을 대외요청으로 응답인터페이스를 등록한다. (무응답이므로 타이머를 해제할수없으므로 요청플로우에서 타이머등록 제외)
3. API정보관리 > API정보에서 클라이언트모드에 동기여부를 비동기로 API를 등록한다.
4. API정보관리 > API정보에서 서버모드에 동기여부를 비동기로 API를 등록한다. (응답URL, 응답파라미터는 등록하지않는다. 응답Method는 변경해도 실제로 적용안됨)

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

REST 아웃바운드 비동기 응답

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