메시지

개요

메시지는 AnyLink에서 송수신하는 데이터의 구조를 정의합니다. 메시지 정의를 통해 다음을 수행할 수 있습니다.

  • 요청/응답 데이터 구조 정의

  • 필드별 타입 및 속성 설정

  • 직렬화/역직렬화 규칙 지정

AnyLink는 다음 3가지 메시지 유형을 지원합니다.

유형 설명 주요 용도

JSON

JSON 포맷

HTTP API, 웹 서비스

XML

XML 포맷

SOAP, 레거시 시스템

Fixed-Length

고정 길이 포맷

금융권, 전문 통신

메시지 생성

리소스 트리에서 원하는 거래 또는 거래 그룹의 컨텍스트 메뉴를 열고 [리소스 생성] > [메시지 생성]을 선택합니다.

워크스페이스의 탭 편집기 영역에 [메시지 생성] 탭이 표시되면 설정 정보를 입력합니다. 메시지 정보는 기본 정보와 메시지 타입별 구성 영역으로 구성됩니다.

message create

메시지 정보 입력이 완료되면 하단의 [생성] 버튼을 클릭합니다.

  • ① 기본 정보 설정

    메시지의 기본 정보를 입력합니다. (*: 필수 설정 항목)

    항목 설명

    메시지 아이디 *

    메시지의 고유 식별자입니다.

    메시지 이름

    메시지의 표시 이름입니다. 미입력 시 아이디 값으로 자동 설정됩니다.

    설명

    메시지에 대한 설명입니다.

  • ② 메시지 타입 및 구성 설정

    메시지의 타입을 지정합니다.

    항목 설명

    메시지 타입 추가

    [+ 메시지 타입 추가] 버튼을 클릭해 메시지 타입을 선택합니다.

    • XML

    • JSON

    • FIXED_LENGTH

    메시지 타입 설정

    메시지 타입별 설정을 구성합니다. 선택한 메시지 타입에 따라 표시되는 설정 항목이 다릅니다.

    메시지 타입별 설정 항목은 메시지 타입별 설정을 참고합니다.

    메시지 구성 *

    메시지 필드 정보를 입력합니다. 필드 정보는 메시지 필드 정의을 참고합니다.

메시지 필드 정의

메시지의 필드 속성을 정의하려면 메시지 필드 테이블 상단의 [+ 추가] 버튼을 클릭합니다. 빈 행이 추가되면 각각의 필드 속성을 입력하고 하단의 [생성] 버튼을 클릭합니다.

필드를 삭제하려면 필드 목록에서 삭제할 필드를 선택하고 [삭제] 버튼을 클릭합니다.

다음은 모든 메시지 타입에서 공통으로 사용되는 필드 속성입니다. 메시지 타입별로 추가로 설정이 필요한 필드 속성은 메시지 타입별 설정을 참고합니다.

항목 설명

Field Id *

필드의 고유 식별자입니다. 영문, 숫자 및 언더스코어(_)를 조합하여 3~32자 이내로 입력해야 합니다.

Field Name *

필드의 표시 이름입니다. 한글, 영문, 숫자 및 언더스코어(_)를 조합하여 2~32자 이내로 입력해야 합니다.

Field Type

필드의 데이터 타입입니다. 설정 가능한 데이터 타입에 대한 설명은 하단의 표를 참고합니다.

Object Message Name

필드 타입을 Object로 지정할 때 참조할 메시지를 설정합니다. 메시지 구성 테이블 상단의 [메시지 찾기] 버튼을 클릭하여 원하는 메시지를 선택하면 자동으로 설정됩니다.

Object Message Path

필드 타입을 Object로 지정할 때 참조할 메시지의 경로를 설정합니다. 메시지 구성 테이블 상단의 [메시지 찾기] 버튼을 클릭하여 원하는 메시지를 선택하면 자동으로 설정됩니다.

Comment

필드에 대한 설명을 입력합니다.

다음은 AnyLink에서 지원하는 필드 타입입니다.

타입 Java 타입 설명

STRING

String

문자열

INT

int / Integer

32비트 정수

LONG

long / Long

64비트 정수

FLOAT

float / Float

단정밀도 부동소수점

DOUBLE

double / Double

배정밀도 부동소수점

BOOLEAN

boolean / Boolean

참/거짓

OBJECT

MessageEntity

중첩 객체

OBJECT 타입을 사용하면 메시지 내에 중첩 구조를 정의할 수 있습니다. 중첩 객체를 정의하는 방법은 부모 필드의 타입을 Object로 설정하고, 부모 필드 아래에 자식 필드를 추가합니다.

다음은 중첩 구조의 예시입니다.

{
  "orderId": "ORD001",
  "customer": {           // OBJECT 타입
    "name": "홍길동",
    "email": "hong@example.com",
    "address": {          // 중첩 OBJECT
      "city": "서울",
      "zipCode": "12345"
    }
  }
}

메시지 조회 및 수정

리소스 트리에서 원하는 메시지를 클릭하면 워크스페이스의 탭 편집기 영역에 해당 메시지 탭이 표시됩니다.

message detail

조회 가능한 항목에 대한 설명은 메시지 생성을 참고합니다. 메시지 정보를 수정하려면 탭 하단의 [편집] 버튼을 클릭해 편집 모드로 전환합니다.

메시지 타입별 설정

AnyLink에서는 JSON, XML, Fixed-Length 3가지 타입의 메시지를 지원합니다. 각 타입별 설정 항목은 해당 절을 참고합니다.

JSON 메시지

JSON(JavaScript Object Notation) 메시지는 경량 데이터 교환 형식을 사용하는 텍스트 기반 메시지입니다. JSON 형식은 사람이 읽고 작성하기 쉽고, 시스템 간 데이터 교환에 적합합니다.

JSON 메시지는 주로 다음과 같은 환경에서 사용됩니다.

  • HTTP API 통신

  • 웹 서비스 연동

  • 마이크로서비스 간 통신

message json form

다음은 JSON 메시지의 설정 정보입니다.

항목 설명

객체 이름

JSON 루트 객체의 키 이름입니다. 미지정 시 메시지 클래스 이름을 사용합니다.

빈 값 대응

null 값의 처리 방식을 지정합니다. NULL만 선택 가능합니다.

알 수 없는 값 무시

역직렬화 시 매핑되지 않은 JSON 필드를 무시할지 여부를 선택합니다.

다음은 JSON 메시지에서 사용할 수 있는 필드 속성입니다. 메시지 타입과 관계없이 공통으로 사용하는 필드 속성은 메시지 필드 정의를 참고합니다.

항목 설명

JSON Key

JSON에서 사용할 키 이름입니다. 미지정 시 필드 이름을 사용합니다.

다음은 JSON Key 설정 예시입니다.

{
  "customer_name": "홍길동"   // JSON Key: customer_name
}

Field Id와 JSON Key를 다르게 설정하면 내부 필드 이름과 JSON 키 이름을 구분하여 사용할 수 있습니다. 예를 들어 내부에서는 camelCase 형식의 이름(orderId)을 사용하고, 외부 API와 통신할 때는 snake_case 형식의 JSON 키(order_id)를 사용할 수 있습니다.

다음은 아래 설정값을 적용하여 구성한 JSON 메시지 예제입니다.

  • 객체 이름: order

  • 빈 값 대응: NULL

  • 알 수 없는 값 무시: true

{
  "order": {
    "orderId": "ORD001",
    "customerName": "홍길동",
    "totalAmount": 50000,
    "item": {
      "productId": "P001",
      "quantity": 2
    }
  }
}

다음은 예제에 사용된 필드 정의입니다.

Field Id Field Type JSON Key 설명

orderId

STRING

orderId

주문 고유 식별자

customerName

STRING

customerName

고객명

totalAmount

LONG

totalAmount

총 금액

itemInfo

OBJECT

item

주문 항목 정보

XML 메시지

XML(Extensible Markup Language) 메시지는 데이터를 구조화하여 표현하고 전송하기 위한 텍스트 기반 메시지입니다. XML 형식은 태그를 사용하여 데이터의 의미와 계층 구조를 명확하게 표현할 수 있습니다.

XML 메시지는 주로 다음과 같은 환경에서 사용됩니다.

  • SOAP 웹 서비스

  • 레거시 시스템 연동

  • 전자문서교환(EDI)

message xml form

다음은 XML 메시지의 설정 정보입니다.

항목 설명

Root Element Name

XML 문서의 루트 요소 이름입니다. 네임스페이스를 포함하여 지정할 수 있습니다.

네임스페이스를 지정하는 방법은 네임스페이스 설정을 참고합니다.

Content Type

XML 요소의 콘텐츠 구조를 설정합니다.

  • ELEMENT: 자식 요소만 포함합니다. (가장 일반적)

  • SIMPLE: 텍스트 콘텐츠만 포함합니다.

  • MIXED: 자식 요소와 텍스트를 함께 포함합니다.

  • EMPTY: 자식 요소나 텍스트 없이 속성만 가질 수 있습니다.

UnmarshalException 무시

XML 역직렬화 중 오류가 발생했을 때 예외를 무시할지 여부를 설정합니다.

[네임스페이스 설정]

XML 네임스페이스는 XML 요소와 속성의 이름 충돌을 방지하기 위해 사용합니다.

AnyLink에서는 루트 요소 이름을 설정할 때 Clark 표기법({namespace-uri}local-name)을 사용하여 네임스페이스를 지정합니다.

다음은 XML 예시입니다.

입력 예:
{http://example.com/order}Order

결과 XML:
<Order xmlns:ord="http://example.com/order">
  ...
</Order>
입력 예 설명

{http://example.com/order}Order

http://example.com/order 네임스페이스의 Order 요소입니다.

Order

Order 요소입니다.

다음은 XML 메시지에서 사용할 수 있는 필드 속성입니다. 메시지 타입과 관계없이 공통으로 사용하는 필드 속성은 메시지 필드 정의를 참고합니다.

항목 설명

Is Element

필드를 XML 요소로 매핑할지 속성으로 매핑할지를 선택합니다. (true | false)

Element Name / Attribute Name

XML에서 사용할 요소 이름 또는 속성의 이름입니다.
Is Element 설정에 따라 요소명 또는 속성명으로 사용됩니다.

Attribute Use Option

XML 속성의 사용 옵션입니다.

  • NONE: 적용하지 않습니다.

  • OPTIONAL: 선택 항목으로 사용합니다.

  • REQUIRED: 필수 속성으로 사용합니다.

  • PROHIBITED: 사용하지 않습니다.

Nillable

null 값을 xsi:nil 형식으로 표현할지 여부를 선택합니다. (true | false)

CDATA

텍스트 값을 CDATA 섹션으로 감쌀지 여부를 선택합니다.
특수문자를 이스케이프하지 않고 포함할 때 사용합니다. (true | false)

다음은 XML 필드의 예시입니다.

<Order id="ORD001">           <!-- id는 속성 -->
  <CustomerName>홍길동</CustomerName>  <!-- 요소 -->
  <Description><![CDATA[특수문자 포함: <>&]]></Description>  <!-- CDATA -->
</Order>

다음은 아래 설정값을 적용하여 구성한 XML 메시지 예제입니다.

  • Root Element Name: {http://example.com/order}Order

  • Content Type: ELEMENT

  • UnmarshalException 무시: false

네임스페이스가 지정되면 XML 메시지에는 예제와 같이 URI가 함께 선언됩니다.

<Order xmlns="http://example.com/order">
  <orderId id="ORD001">ORD001</orderId>  <!-- id는 REQUIRED 속성 -->
  <customerName>홍길동</customerName>
  <description><![CDATA[특수문자 포함: <>&]]></description>
</Order>

다음은 예제에 사용된 필드 정의입니다.

Field Id Field Type Is Element Element/Attribute Name 설명

orderId

STRING

true

orderId

주문 ID 요소

id

STRING

false

id

주문 ID 속성 (REQUIRED)

customerName

STRING

true

customerName

고객명 요소

description

STRING

true

description

설명 요소 (CDATA 사용)

XML 메시지에서 한글을 정상적으로 사용하기 위해서 UTF-8 인코딩을 사용합니다. EUC-KR은 XML 사양에서는 지원하지 않습니다.

Fixed-Length 메시지

Fixed-Length(고정 길이) 메시지는 각 필드가 미리 정해진 바이트 길이를 가지는 메시지 형식입니다. 구분자를 사용하지 않고, 각 필드의 시작 위치와 길이를 기준으로 데이터를 식별합니다.

Fixed-Length 메시지는 주로 다음과 같은 환경에서 사용됩니다.

  • 금융권 전문 통신

  • 레거시 메인프레임 연동

  • 대용량 전문 처리

message fixed form

다음은 Fixed-Length 메시지의 설정 정보입니다.

항목 설명

공백 설정 (Trim)

메시지 값의 앞뒤 공백을 처리하는 방식입니다.

  • NONE: 공백을 제거하지 않습니다.

  • RIGHT: 오른쪽 공백 제거합니다.

  • LEFT: 왼쪽 공백 제거합니다.

  • BOTH: 양쪽 공백 제거합니다.

총 길이 *

메시지의 전체 바이트 길이입니다. 메시지 구성에서 Length를 설정하면 총 길이가 자동으로 계산되어 표시됩니다.

다음은 Fixed-Length 메시지에서 사용할 수 있는 필드 속성입니다. 메시지 타입과 관계없이 공통으로 사용하는 필드 속성은 메시지 필드 정의를 참고합니다.

항목 설명

Length *

필드의 바이트 길이입니다.

Offset

필드의 시작 위치입니다.

필드 길이를 기준으로 자동 계산되며, 읽기 전용으로 표시됩니다.

Align

필드 값의 정렬 방식입니다.

  • NONE: 정렬을 적용하지 않습니다.

  • LEFT: 왼쪽 정렬합니다.

  • RIGHT: 오른쪽 정렬합니다.

Fill

정렬 시 남는 공간을 채우는 패딩 문자입니다. 기본값은 공백입니다.

다음은 Fixed-Length 메시지의 필드 레이아웃 예시입니다.

각 필드는 시작 위치(Offset)와 길이(Length)에 따라 고정된 위치에 배치됩니다.

Position  Length  Field Id        Field Name      Type     Align   Fill
--------  ------  --------------  --------------  -------  ------  -----
0         4       txCode          전문구분코드     STRING   LEFT    ' '
4         10      txNo            전문번호         STRING   LEFT    ' '
14        8       txDate          거래일자         STRING   LEFT    ' '
22        6       txTime          거래시간         STRING   LEFT    ' '
28        15      amount          금액             LONG     RIGHT   '0'

Fixed-Length 메시지는 바이트 길이를 기준으로 필드를 계산합니다. 한글과 같은 멀티바이트 문자는 인코딩 방식에 따라 바이트 수가 달라지므로, 필드 길이를 설정할 때 주의해야 합니다.

인코딩 한글 1자 영문 1자

UTF-8

3 bytes

1 byte

EUC-KR

2 bytes

1 byte

예를 들어, 문자열 홍길동의 바이트 길이는 인코딩에 따라 다음과 같이 달라집니다.

  • UTF-8: 9 bytes (3 x 3)

  • EUC-KR: 6 bytes (2 x 3)

다음은 아래 설정값을 적용하여 구성한 Fixed-Length 메시지 예제입니다.

  • 공백 설정: RIGHT

  • 총 길이: 50 bytes

  • 인코딩: EUC-KR

Position  Length  Field Id        Field Name      Type     Align   Fill   예시 값
--------  ------  --------------  --------------  -------  ------  -----  ---------------
0         4       txCode          전문구분코드     STRING   LEFT    ' '    "0100"
4         10      txNo            전문번호         STRING   LEFT    ' '    "1234567890"
14        8       txDate          거래일자         STRING   LEFT    ' '    "20250205"
22        6       txTime          거래시간         STRING   LEFT    ' '    "143052"
28        15      amount          금액             LONG     RIGHT   '0'    "000000000010000"
43        7       reserved        예약영역         STRING   LEFT    ' '    "       "

각 필드는 정의된 길이만큼 고정 폭을 차지하며, 정렬 방식과 Fill 값에 따라 실제 메시지 값이 구성됩니다.

다음 메시지는 위 필드 값을 순서대로 결합한 결과이며, 전체 길이는 50바이트입니다.

0100123456789020250205143052000000000010000

다음은 예제에 사용된 필드 정의입니다.

Field Id Field Type Length Offset Align 설명

txCode

STRING

4

0

LEFT

전문 구분 코드

txNo

STRING

10

4

LEFT

전문 번호

txDate

STRING

8

14

LEFT

거래 일자 (YYYYMMDD)

txTime

STRING

6

22

LEFT

거래 시간 (HHmmss)

amount

LONG

15

28

RIGHT

금액 (왼쪽을 0으로 채움)

reserved

STRING

7

43

LEFT

예비 필드