BizMessage Agent

디케이테크인의 Kakao i BizMessage 서비스는 최종 사용자에게 알림톡, 친구톡, SMS, LMS, MMS, RCS, 네이버톡톡 등을 전송할 수 있는 시스템입니다. Kakao i BizMessage 서비스는 BizMessage Agent 설치 방식 혹은 BizMessage API 호출 방식으로 구현할 수 있습니다. 이 문서에서는 BizMessage Agent 설치를 통한 시스템 설치 및 설정 사항을 설명합니다.

안내
BizMessage 서비스를 사용하기 위해서는 별도의 서비스 계약이 필요합니다. 계약 방법 및 서비스 이용 절차에 대한 자세한 설명은 BizMessage(KOR) 문서를 참고하시기 바랍니다.

시스템 권장 사양

BizMsgAgent 설치 및 서버 운영을 위해서는 다음의 시스템 사양이 필요합니다.

BizMessage Agent 설치

BizMessage Agent의 설치 순서는 다음과 같습니다.

Step 1. 방화벽 오픈하기

BizMsgAgent는 TCP/IP 소켓 통신을 통해 안정적인 발송 요청과 결과 데이터를 수신합니다. 통신 시 보안은 RSA 및 AES128 암호화를 준수하며, dk techin 메시지 중계 서버와의 통신을 위해 Agent 설치 전 영업 담당자에게 TCP/IP 방화벽 오픈을 요청해야 합니다. 이때 서비스 종류와 보안 등급에 따라 전용선 혹은 인터넷망을 사용할 수 있습니다. 다음 정보를 참고하여, 방화벽에서 포트번호와 IP 주소를 오픈하시기 바랍니다.

BizMessage 서버 정보

BizMessage 서버는 운영과 스테이징으로 구분됩니다.

• 운영 서버는 실제 고객에게 메시지를 발송하는 목적으로 적합하며, 발송 메시지 건수에 제한이 없고, 과금이 됩니다.
• 스테이징 서버는 소량의 메시지를 테스트하는 목적으로 적합하며, 발송 메시지 건수에 제한이 있고, 과금이 되지 않습니다. 하지만 스테이징 서버에서 메시지를 발송하더라도 실제 메시지가 발송되므로, 메시지 오발송에 주의가 필요합니다. 스테이징 서버에서 전송할 수 있는 메시지 제한 개수는 계약 조건에 따라 다를 수 있습니다.

주의
스테이징 서버는 카카오 운영 서버와 연동되어 있어 실제 메시지가 발송되므로, 메시지 오발송에 주의하시기 바랍니다.

Step 2. 모듈 압축 해제하기

BizMsgAgent는 Java 애플리케이션으로, 설치 파일 형태로 제공됩니다. 설치 파일을 원하는 경로에 복사 후 압축을 해제하면 설치가 완료됩니다. 설치 후에는 다음의 디렉터리가 생성됩니다.

Step 3. 환경 설정하기(agent.ini)

${app_home}/conf/agent.ini 경로로 이동 후, 다음을 참고하여 agent.ini 파일의 섹션별 환경 설정을 수행합니다.

공통 설정 섹션

계정 설정을 아래와 같이 설정합니다.

코드예제agent.ini

[AGENT]
client_id=TEST0001
agent_id=TEST0001001
agent_type=AT         # (AT: 알림톡, FT: 친구톡 , RCS: RCS, XMS: SMS/LMS/MMS 발송 전용, NAVER: 네이버톡톡)
at_type=PUSH            # 알림톡 결과 수신 방식(PUSH, POLLING)

[GW_INFO]
rx_ip= {발송 서버 IP}
rx_port=7001
tx_ip= {수신 서버 IP}
tx_port=7000

DBMS 섹션

데이터베이스 종류에 따라 agent.ini 파일의 DBMS 섹션을 다음과 같이 설정합니다.

Oracle

코드예제Oracle

[DBMS]
type=oracle
user={agent_username}
password={agent_password}
schema={AGENT_SCHEMA}     # 스키마명 (오라클에서는 schema명을 대문자로 기입)
minimumIdle=10                    # DB 연결 최소 개수
maximumPoolSize=20          # DB 연결 최대 개수
url=jdbc:oracle:thin:@127.0.0.1:1521/ORCL

#failover 연결
#url=jdbc:oracle:thin:@(DESCRIPTION=(FAIL_OVER=ON)(LOAD_BALANCE=off)(ADDRESS=(PROTOCOL=TCP)(HOST=192.168.0.1) (PORT=3000))(ADDRESS=(PROTOCOL=TCP)(HOST=192.168.0.2) (PORT=1521))(CONNECT_DATA=(SERVICE_NAME=ORCL)))

MSSQL

코드예제MSSQL

[DBMS]
type=mssql
user={sa}
password={sapassword}
schema={dbo}                         # 스키마명 ( DB 기본 권한 dbo )
minimumIdle=10                  # DB 연결 최소 개수
maximumPoolSize=20        # DB 연결 최대 개수
url=jdbc:sqlserver://127.0.0.1:1433;databaseName=AGENT

MySQL

코드예제MySQL

[DBMS]
type=mysql
user={testuser}
password={testpassword}
schema={agent}                    # 스키마명 ( 데이터베이스명 )
minimumIdle=10                  # DB 연결 최소 개수
maximumPoolSize=20        # DB 연결 최대 개수
url=jdbc:mysql://localhost:3306/agent?useSSL=false&useUnicode=true&characterEncoding=UTF-8&allowMultiQueries=true

DB2

코드예제DB2

[DBMS]
type=db2
user=db2inst
password=db2instpass
schema=AGENT                          # 스키마명 ( 데이터베이스 명 )
minimumIdle=10                     # DB 연결 최소 개수
maximumPoolSize=20           # DB 연결 최대 개수
url=jdbc:db2://localhost:50000/AGENT

TIBERO

코드예제TIBERO

[DBMS]
type=tibero
user=tuser
password=tpassword
schema=AGENT                          # 스키마명
minimumIdle=10                     # DB 연결 최소 개수
maximumPoolSize=20           # DB 연결 최대 개수
url=jdbc:tibero:thin:@127.0.0.1:8629:tibero

PostgreSQL

코드예제PostgreSQL

[DBMS]
type=postgresql
user=postgres
password=ppassword
schema=public                           # 스키마명
minimumIdle=10                        # DB 연결 최소 개수
maximumPoolSize=20               # DB 연결 최대 개수
url=jdbc:postgresql://127.0.0.1:5432/postgres

Sybase

코드예제Sybase

[DBMS]
type=sybase
user=agent
password=agentpassword
schema=dbo                                     # 스키마명
minimumIdle=10                           # DB 연결 최소 개수
maximumPoolSize=20                 # DB 연결 최대 개수
url=jdbc:postgresql://127.0.0.1:5432/postgres

TABLE 섹션

메시지 발송을 위한 테이블의 기본 환경 설정 변경 시 다음의 형식을 참고하여 agent.ini 파일을 수정합니다. TABLE 섹션에서 =의 우측 값은 기본값이며, 수정할 수 있습니다.

코드예제TABEL 섹션

[TABLE]
# Sybase, PostgreSQL은 테이블명을 모두 소문자로 지정해야 하며, 그 외 DBMS는 대문자로 작성합니다.
# 발송 요청과 결과 테이블을 하나로 사용할 경우, 요청 테이블명과 결과 테이블명을 동일하게 입력합니다.

# 시퀀스명(MySQL은 auto_increment, Sybase와 MSSQL은 identity를 사용하기 위해 이름 입력 필요)
alimtalk_sequence=seq_k

# 알림톡 발송 요청 테이블
alimtalk_message=k_message

# 알림톡 발송 결과 테이블
alimtalk_messagelog=k_message_log

# 위 시퀀스와 동일
ftalk_sequence=seq_f

# 친구톡 발송 요청 테이블
ftalk_message=k_f_message

# 친구톡 발송 결과 테이블
ftalk_message_log=k_f_message_log

# RCS 발송 요청 테이블
rcs_message=k_rcs_message

# RCS 발송 결과 테이블
rcs_message_log=k_rcs_message_log

# XMS 테이블의 PK 시퀀스
xms_sequence=SEQ_XMS_MESSAGE

# XMS 발송 테이블
xms_message=XMS_MESSAGE

# XMS 로그 테이블
xms_message_log=XMS_MESSAGE_LOG

# XMS 이미지 테이블
xms_contents=XMS_MESSAGE_CONTENTS

# 네이버 테이블의 PK 시퀀스
naver_sequence=SEQ_NAVER_MESSAGE

# 네이버 발송 테이블
naver_message=NAVER_MESSAGE8

# 네이버 로그 테이블
naver_message_log=NAVER_MESSAGE_LOG8

# DB별로 테이블 생성을 위한 별도 스크립트가 필요함
createTable=true

# 로그 테이블을 월별로 생성할지 여부
logDivision=true

# 발송 요청과 결과 테이블이 동일할 때, 로그 테이블을 하나로 사용할 경우 해당 일수만큼 지난 데이터는 삭제 처리, 일단위
logDataDelete=10

# 발송 서비스에서 1회 조회 시 조회 건수 설정(defaut : 1000건)
at_fetch_count=1000
at_img_fetch_count=100
ft_fetch_count=1000
ft_img_fetch_count=100
rcs_fetch_count=1000
rcs_img_fetch_count=100
xms_fetch_count=1000
xms_img_fetch_count=100
naver_fetch_count=1000

테이블 설명

에이전트는 데이터베이스를 바탕으로 동작하는 프로그램이므로 테이블 및 데이터 관리가 중요합니다. 에이전트에서 사용하는 테이블에 대한 설명은 다음과 같습니다.

HA 섹션(선택)

[HA] 섹션은 Agent의 서버 이중화 구성을 위한 Active – Standby 설정 시 사용합니다.

코드예제HA 섹션

[HA]
#HA 사용 여부 (default=false)
ha_use=false

# sybase, postgresql은 테이블명을 모두 소문자로 지정하며, 그 외 DBMS는 대문자로 작성
ha_table_name=k_agent

# M : master, S : slave
ha_agent_type=M

# Active – Stanby
에이전트 이중화 체크 시간(초)
ha_timeout_sec=60

FILE_DEL 섹션

[File_DEL] 섹션은 데이터 전송을 위한 임시 파일 삭제 시 사용합니다.

코드예제FILE_DEL 섹션

[FILE_DEL]
#에이전트에서 생성되는 파일에 대해서 기준일 이후는 삭제처리, 일 기준
log=4

JOB_EXPIRED 섹션

[JOB_EXPIRED] 섹션은 메시지 발송 시 유효 시간을 설정할 때 사용합니다.

코드예제JOB_EXPIRED 섹션

[JOB_EXPIRED]
#1440 : 1day

#단건 발송 유효시간, 분 기준 (예약시간 기준으로 해당 시간 이내 건만 발송)
small_fetch_expired_min=1440

#대량 발송 유효시간, 분 기준 (예약시간 기준으로 해당 시간 이내 건만 발송)
large_fetch_expired_min=1440

White List 섹션(선택)

[WHITE_LIST] 섹션은 mobile_no에 입력된 전화번호에 한해 데이터를 발송 시 사용합니다.

코드예제White List 섹션

[WHITE_LIST]
#사용 유무
use=false
# 등록된 번호에 한해 메시지를 전송
mobile_no=01999999999,09999999999

Black List 섹션(선택)

[BLACK_LIST] 섹션은 블랙리스트를 DB 테이블로 관리하기 위한 기능으로 DB 테이블에 등록된 전화번호를 발송하지 않을때 사용합니다.

코드예제Black List 섹션

[BLACK_LIST]
#사용 유무
use=false
#블랙리스트 DB테이블명
blacklist_table=K_BLACKLIST

Server IP 섹션

[SERVER_IP] 섹션은 에이전트가 설치된 서버 장비의 IP 확인을 위해 사용합니다. 계약 시 설정한 IP를 기입해야 합니다.

코드예제Server IP 섹션

[SERVER_IP]
#에이전트가 설치된 서버의 IP
ip=127.0.0.1

Custom Column 섹션(선택)

Custom Column 섹션은 고객이 테이블에 칼럼을 추가하여 사용하는데 필요한 섹션으로, 다음의 파라미터로 구성됩니다.

코드예제Custom Column 섹션

[CUSTOM_CULOMN]
#고객사에서 임의로 추가가 필요한 칼럼이 있을 때 추가하여 사용

#테이블 생성시 칼럼 추가
#create=CUST_1 TYPE VARCHAR(1) DEFAULT 'X' NOT NULL , CUST_2 VARCHAR(1) DEFAULT 'N' NOT NULL

#발송 요청 테이블에서 결과 테이블로 이관 시 select 칼럼 추가
#select=CUST_1, CUST_2

Code Mapping 섹션(선택)

결과코드를 고객사의 코드로 매핑하기 위한 기능을 제공합니다. 매핑하려는 각각의 코드를 |로 구분하여 #{결과코드}|#{매핑하려는 고객사 결과코드} 형식으로 작성합니다.

코드예제Code Mapping 섹션

# 결과 코드 매핑 기능 설정 (사용: true, 미사용: false)
[CODE_MAPPING]
# 메시지 타입별 커스텀 결과 코드 사용 여부
alimtalk_code_mapping_use=false
sms_code_mapping_use=false
rcs_code_mapping_use=false
naver_code_mapping_use=false

Step 4. 서버 OS 설정하기

서버 OS별 설정 방법은 다음과 같습니다.

Windows 계열

Windows 계열의 서버 환경 설정을 위해서 다음의 경로로 이동하여 환경 설정 작업을 수행합니다.

1. ${app_home}/bin 경로로 이동한 후, kakaoAgent.xml 파일에서 환경 설정을 수행합니다. * {app_home}에는 에이전트가 설치된 경로를 입력합니다.

   코드예제kakaoAgent.xml 구성

   Plain Text

   <?xml version="1.0" encoding="UTF-8"?>
   <service>
     <!-- 에이전트가 설치된 절대경로 -->
     <env name="AGENT_HOME" value="C:\PushAgent\C1A1-at"/>
   
     <!-- jdk 설치 절대 경로 -->
     <env name="JAVA_HOME" value="C:\java\jdk1.8.0_45"/>
   
     <env name="ENCODING" value="UTF-8"/>
     <env name="OS_NAME" value="WINDOW"/>
     <env name="XMS" value="-Xms256m"/>
     <env name="XMX" value="-Xmx256m"/>
   
     <env name="GC_CONF1" value=""-XX:+UseParallelGC -XX:PermSize=128M -XX:MaxPermSize=128M -XX:NewSize=256M    -XX:MaxNewSize=256M "/>
     <env name="GC_CONF2" value="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath"/>
   
     <!-- 에이전트명 고객사 맞게 변경 가능 -->
     <id>KakaoPush</id>
   
     <!-- 윈도우 서비스에 등록할 이름 고객사 맞게 변경 가능 -->
     <name>KakaoPush</name>
     <description>Kakao Alimtalk/Friendtalk Push Windows Service</description>
   <executable>%JAVA_HOME%\bin\java</executable>
   <arguments> -server %XMS% %XMX% -Dfile.encoding=%ENCODING% -Dos.name=%OS_NAME% -DAGENT_HOME=%AGENT_HOME% %GC_CONF1% %GC_CONF2%=%AGENT_HOME% -jar %AGENT_HOME%\kakaoAgent.jar start</arguments>
   <logmode>none</logmode>
   <startmode>Automatic</startmode>
   </service>
   

2. ${app_home}/bin/kakaoAgent.exe를 실행합니다.

3. 서비스 등록을 위해 관리자 권한으로 ${app_home}/bin/service.bat을 실행합니다.

   안내
   만약 kakaoAgent.xml이 수정된 경우 등록된 서비스를 삭제한 후 재등록하시기 바랍니다.

   그림관리자 권한으로 실행

   표서비스 등록

   구분	설명
   0	종료
   1	윈도우 서비스 등록
   2	윈도우 서비스 제거

4. Windows의 Services로 이동하여 KakaoPush가 등록되었는지 확인합니다.

그림KakaoPush 등록 확인

Unix 계열

Unix 계열의 환경 설정을 위해서는 다음의 경로로 이동하여 환경 설정 작업을 수행합니다.

1. ${app_home}/bin/env.sh로 이동하여 다음과 같이 환경 설정을 수행합니다.

   코드예제env.sh 구성

   Plain Text

   #!/bin/sh
   
   #실행 시 프로세스 명
   SERVER_NAME="KAKAO_AGENT"
   
   #에이전트 설치 절대 경로
   AGENT_HOME="/Users/agent_at"
   
   #jdk 설치 절대 경로
   JAVA_HOME="/Usr/bin/"
   
   ENCODING="UTF-8"
   XMS="-Xms256m"
   XMX="-Xmx256m"
   GC_CONF1=""-XX:+UseParallelGC -XX:PermSize=128M -XX:MaxPermSize=128M -XX:NewSize=256M -XX:MaxNewSize=256M"
   GC_CONF2="-XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath"
   
   #에이전트를 실행할 시스템 사용자 명
   SETUSER="root"
   
   RUNNER=`whoami`
   ….
   

2. 서비스의 실행이나 종료 시 다음의 명령어를 실행합니다.

   • Agent 실행 및 종료를 위해서는 chmod 755 권한이 필요합니다.

   그림Agent 실행 및 종료

   표서비스 등록

   구분	설명
   start.sh	프로세스 실행
   stop.sh	프로세스 종료

3. app_home 디렉터리에서 서비스 로그를 확인합니다.

   그림서비스 로그 확인

   표서비스 로그

   로그명	설명
   logs/${yyyy}	yyyy/mm 폴더에 각 날짜별로 log 파일 이관
   logs/start.log	실행 로그
   logs/err.log	에러 로그
   logs/job.log	Job 동작 로그