청기와랩 블로그
Tutorial 2: GitHub에서 청기와랩 SMS API 예제 실행 해보기
2015년 01월 08일 by 청기와랩
자 이제 Tutorial 1에서 등록한 Application ID를 사용해 볼 시간입니다.
청기와랩의 다양한 예제 코드들은 GitHub 에 오픈소스로 공개되어 있습니다.
먼저 https://github.com/BlueHouseLab/sms-openapi 에 접속 합니다.
청기와랩의 GitHub 페이지 입니다. GitHub 에 익숙 하신 개발자 분들은 평소에 하시던 데로 페이지를 쓰윽 둘러 보시면 무엇을 해야 될지 다 아실거에요. 하지만 지금은 튜토리얼 시간이니까 차근 차근 따라 해보기로 해요. :-)
우측 사이드바에 보시면 Git Repository URL 이 있습니다.
예제 코드는 git 명령어를 이용하여 clone 과정을 거쳐 다운 받으실 수도 있고, ZIP 파일로 다운 받으실 수도 있습니다.
로마에서는 로마법을 따라야 겠죠? GitHub 에서는 Git 를 쓰는게 법이랍니다.
https://github... 로 시작되는 URL을 복사한 다음에 터미널에 다음과 같이 붙어 넣으세요
이렇게 하면 sms-openapi 라는 디렉토리에 GitHub 에 등록된 청기와랩의 SMS API 예제를 개발자님의 local machine 에 "clone" 하게 됩니다.
자 이제 sms-openapi 디렉토리에 들어가 볼까요?
보시다 싶이 2014년 11월 현재 다음과 같은 예제가 제공 되고 있습니다.
웹 개발 환경에서는 PHP, Python, Ruby, Java, C# 을 참조 하시면 됩니다.
Unix 환경 내지는 GUI 프로그램들은 C++, C, Java 등이 유용할 걸로 생각 됩니다. 특히 C++ 예제는 GUI ToolKit 쪽에서 가장 많이 쓰이는 크로스플랫폼 라이브러리인 Qt5를 사용 했으므로 Linux, WIndows, Mac 등 다양한 환경에서 참조하실 수 있습니다. C 예제도 말할 것도 없이 뛰어난 이식성을 자랑 합니다.
Java, C#, PHP, Ruby, Node.js, Python 예제 들은 해당 언어의 standard module 들을 사용했으므로 별다른 라이브러리 설치 없이 테스트 가능 합니다.
이번 Tutorial 에서는 가장 많이 사용되는 환경인 Linux 에서 가장 쉽게 테스트 해볼 수 있는 BASH 예제를 소개해 볼까 합니다. Mac OS X 을 사용하시는 개발자 분들도 별다른 모듈 설치 필요 없이 바로 테스트 해보실 수 있습니다.
Bash 예제는 쉘스크립트로 SMS 를 보내볼 수 있는데요. curl 이라고 하는 Command line HTTP Client Tool을 사용 합니다. curl 은 현대 리눅스 배포판및 BSD 계열의 Mac OS X 에도 기본으로 들어 있는 명령어 입니다. Windows 개발자 분들도 Cygwin 또는 MSYS 환경에서 쉽게 테스트 해보실 수 있습니다.
자 한번 해볼까요?
먼저 curl 디렉토리에 들어가서 어떤 예제 파일들이 있는지 확인해 봅시다.
env.sh, result.sh, sendsms.sh 가 있는데요. vi 나 emacs, nano, pico 등의 편집기로 파일을 열어 봅시다.
env.sh 에는 Tutorial 1에서 발급 한 Application ID 와 Key 를 입력 합니다.
자 이제 sendsms.sh 를 열어 볼까요?
3번째 4번째 줄인 SENDER와 RECEIVER 값만 실제 테스트 하실 전화번호로 바꾸시면 됩니다.
# 이후로는 주석이니 무시하셔도 됩니다.
중간에 보시면 ". env.sh" 가 있습니다. Bash 에서는 "쩜" 도 명령어 Alias 중 하나인데요. "source" 명령과 동일합니다. env.sh 의 내용을 Load 하는 것이죠. 다른 언어에서 include 나 import 하는것 처럼요.
자 그럼 실행해 볼까요?
env.sh 에 적혀 있는 APPID와 APIKEY를 변경 하지 않아서 인데요. Tutorial 1의 과정에서 발급 받으신 Application ID와 Key 로 바꾸시면 됩니다.
010XXXXXXXX 번으로 Delivery ID가 201411XXXXXXXXXXXXXXX 인 메시지가 발송 되었다는 뜻입니다.
지금쯤 휴대폰으로 "나는 유리를 먹을 수 있어요. 그래도 아프지 않아요"의 내용이 담긴 SMS가 잘 도착 했을 겁니다.
리턴받을 수 있는 HTTP Status Code 는 http://bluehouselab-sms-openapi.readthedocs.org/ko... 를 참고하세요.
만약 충전된 크레딧 이나 포인트가 부족할 경우 402 Payment Required 을 리턴받게 됩니다. 크레딧 충전이 필요한 상황 이지요. ~(^.^)~
그럼 이제 SMS 가 잘 도착했는지, 프로그래밍으로 확인해 볼까요?
status: 0 은 메시지가 성공적으로 도착했음을 의미 합니다. 받는 사람의 휴대폰이 꺼져 있거나 존재하지 않는 번호 라면 다른 값을 받게 됩니다. 받을 수 있는 모든 status 값들은 http://bluehouselab-sms-openapi.readthedocs.org/ko... 을 참조하세요.
만약 전화번호는 정확 하지만 휴대전화가 꺼져 있다면 -1을 리턴 받습니다. 최대 이틀 까지 -1 상태가 유지될 수 있으며, 휴대폰이 켜지고 문자수신이 완료 되면 0으로 바뀌게 됩니다. 이틀 후까지 전송되지 않는 다면 발송에 사용한 Credit은 Point 로 환급 됩니다.
발송 여부 확인은 청기와랩 홈페이지의 발송 내역 Report 페이지에서 화려한 Graph와 표로 보실 수도 있습니다. 프로그램을 작성하여 확인하기 어려운 상황에서 유용한 정보를 제공해 줍니다.
Tutorial 2를 마치며...
May the code be with you...
다음 튜토리얼에서는 다른 언어 예제에 대한 더 자세한 비하인드 스토리가 이어 집니다!
청기와랩의 다양한 예제 코드들은 GitHub 에 오픈소스로 공개되어 있습니다.
먼저 https://github.com/BlueHouseLab/sms-openapi 에 접속 합니다.
청기와랩의 GitHub 페이지 입니다. GitHub 에 익숙 하신 개발자 분들은 평소에 하시던 데로 페이지를 쓰윽 둘러 보시면 무엇을 해야 될지 다 아실거에요. 하지만 지금은 튜토리얼 시간이니까 차근 차근 따라 해보기로 해요. :-)
우측 사이드바에 보시면 Git Repository URL 이 있습니다.
예제 코드는 git 명령어를 이용하여 clone 과정을 거쳐 다운 받으실 수도 있고, ZIP 파일로 다운 받으실 수도 있습니다.
로마에서는 로마법을 따라야 겠죠? GitHub 에서는 Git 를 쓰는게 법이랍니다.
https://github... 로 시작되는 URL을 복사한 다음에 터미널에 다음과 같이 붙어 넣으세요
bluehouselab:home $ git clone https://github.com/BlueHouseLab/sms-openapi.git Cloning into 'sms-openapi'... remote: Counting objects: 231, done. remote: Total 231 (delta 0), reused 0 (delta 0) Receiving objects: 100% (231/231), 51.72 KiB | 0 bytes/s, done. Resolving deltas: 100% (120/120), done. Checking connectivity... done. bluehouselab:home $
이렇게 하면 sms-openapi 라는 디렉토리에 GitHub 에 등록된 청기와랩의 SMS API 예제를 개발자님의 local machine 에 "clone" 하게 됩니다.
자 이제 sms-openapi 디렉토리에 들어가 볼까요?
bluehouselab:home $ cd sms-openapi/ bluehouselab:sms-openapi $ ls LICENSE c++qt5 curl node.js python-requests README.md c-curl docs php ruby c# callback-api java python bluehouselab:sms-openapi $
보시다 싶이 2014년 11월 현재 다음과 같은 예제가 제공 되고 있습니다.
- C++ (with Qt5)
- C (with libcurl)
- Bash (with curl)
- Node.js
- Python (httplib, requests)
- PHP
- Ruby
- Java
- C# (Mono)
웹 개발 환경에서는 PHP, Python, Ruby, Java, C# 을 참조 하시면 됩니다.
Unix 환경 내지는 GUI 프로그램들은 C++, C, Java 등이 유용할 걸로 생각 됩니다. 특히 C++ 예제는 GUI ToolKit 쪽에서 가장 많이 쓰이는 크로스플랫폼 라이브러리인 Qt5를 사용 했으므로 Linux, WIndows, Mac 등 다양한 환경에서 참조하실 수 있습니다. C 예제도 말할 것도 없이 뛰어난 이식성을 자랑 합니다.
Java, C#, PHP, Ruby, Node.js, Python 예제 들은 해당 언어의 standard module 들을 사용했으므로 별다른 라이브러리 설치 없이 테스트 가능 합니다.
이번 Tutorial 에서는 가장 많이 사용되는 환경인 Linux 에서 가장 쉽게 테스트 해볼 수 있는 BASH 예제를 소개해 볼까 합니다. Mac OS X 을 사용하시는 개발자 분들도 별다른 모듈 설치 필요 없이 바로 테스트 해보실 수 있습니다.
Bash 예제는 쉘스크립트로 SMS 를 보내볼 수 있는데요. curl 이라고 하는 Command line HTTP Client Tool을 사용 합니다. curl 은 현대 리눅스 배포판및 BSD 계열의 Mac OS X 에도 기본으로 들어 있는 명령어 입니다. Windows 개발자 분들도 Cygwin 또는 MSYS 환경에서 쉽게 테스트 해보실 수 있습니다.
자 한번 해볼까요?
먼저 curl 디렉토리에 들어가서 어떤 예제 파일들이 있는지 확인해 봅시다.
bluehouselab:sms-openapi $ cd curl/ bluehouselab:curl $ ls env.sh result.sh sendsms.sh bluehouselab:curl $
env.sh, result.sh, sendsms.sh 가 있는데요. vi 나 emacs, nano, pico 등의 편집기로 파일을 열어 봅시다.
bluehouselab:curl $ vi env.sh
env.sh 에는 Tutorial 1에서 발급 한 Application ID 와 Key 를 입력 합니다.
#!/bin/bash APPID=example APIKEY=c5dd7e7dkjp27377l903c42c032b413b HOST=https://api.bluehouselab.com:443
자 이제 sendsms.sh 를 열어 볼까요?
#!/bin/bash
SENDER=01000000000 # FIXME MUST BE CHANGED AS REAL PHONE NUMBER
RECEIVER=01000000000 # FIXME MUST BE CHANGED AS REAL PHONE NUMBER
. env.sh # load env
curl -i -u $APPID:$APIKEY \
-X POST $HOST/smscenter/v1.0/sendsms \
-H "Content-Type: application/json;charset=utf-8" \
-d '{"sender": "'$SENDER'", "receivers": ["'$RECEIVER'"], "content": "나는 유리를 먹을 수 있어요. 그래도 아프지 않아요"}'
# 이후로는 주석이니 무시하셔도 됩니다.
중간에 보시면 ". env.sh" 가 있습니다. Bash 에서는 "쩜" 도 명령어 Alias 중 하나인데요. "source" 명령과 동일합니다. env.sh 의 내용을 Load 하는 것이죠. 다른 언어에서 include 나 import 하는것 처럼요.
자 그럼 실행해 볼까요?
bluehouselab:curl $ sh sendsms.sh HTTP/1.1 403 FORBIDDEN Date: Mon, 03 Nov 2014 14:02:50 GMT Server: Apache/2.2.22 (Ubuntu) Vary: Accept-Encoding Transfer-Encoding: chunked Content-Type: text/html; charset=utf-8 API Key does not match bluehouselab:curl $403 Forbidden 에러가 발생 했네요. API Key does not match 라고 친절하게 에러 원인도 HTTP 를 통해 전달 됩니다.
env.sh 에 적혀 있는 APPID와 APIKEY를 변경 하지 않아서 인데요. Tutorial 1의 과정에서 발급 받으신 Application ID와 Key 로 바꾸시면 됩니다.
bluehouselab:curl $ sh sendsms.sh
HTTP/1.1 200 OK
Date: Mon, 03 Nov 2014 14:09:41 GMT
Server: Apache/2.2.22 (Ubuntu)
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{"filtered": [], "reserved": null, "sent": [["010XXXXXXXX", "201411XXXXXXXXXXXXXXX"]]}
자 200 OK 가 리턴되었고 JSON 형식의 Data 도 같이 리턴 되었네요.010XXXXXXXX 번으로 Delivery ID가 201411XXXXXXXXXXXXXXX 인 메시지가 발송 되었다는 뜻입니다.
지금쯤 휴대폰으로 "나는 유리를 먹을 수 있어요. 그래도 아프지 않아요"의 내용이 담긴 SMS가 잘 도착 했을 겁니다.
리턴받을 수 있는 HTTP Status Code 는 http://bluehouselab-sms-openapi.readthedocs.org/ko... 를 참고하세요.
만약 충전된 크레딧 이나 포인트가 부족할 경우 402 Payment Required 을 리턴받게 됩니다. 크레딧 충전이 필요한 상황 이지요. ~(^.^)~
그럼 이제 SMS 가 잘 도착했는지, 프로그래밍으로 확인해 볼까요?
bluehouselab:curl $ sh result.sh 201411XXXXXXXXXXXXXXX
HTTP/1.1 200 OK
Date: Mon, 03 Nov 2014 14:18:27 GMT
Server: Apache/2.2.22 (Ubuntu)
Transfer-Encoding: chunked
Content-Type: application/json; charset=utf-8
{"status": 0, "destination": "010XXXXXXXX", "sent_time": "2014-11-03T14:09:47Z"}
bluehouselab:curl $
result.sh 예제도 env.sh 에 저장된 APP ID와 API Key 값을 읽어 들여 Delivery 성공 여부를 체크하는 스크립트 입니다. 200 OK 와 JSON 데이타가 리턴 되었습니다.status: 0 은 메시지가 성공적으로 도착했음을 의미 합니다. 받는 사람의 휴대폰이 꺼져 있거나 존재하지 않는 번호 라면 다른 값을 받게 됩니다. 받을 수 있는 모든 status 값들은 http://bluehouselab-sms-openapi.readthedocs.org/ko... 을 참조하세요.
만약 전화번호는 정확 하지만 휴대전화가 꺼져 있다면 -1을 리턴 받습니다. 최대 이틀 까지 -1 상태가 유지될 수 있으며, 휴대폰이 켜지고 문자수신이 완료 되면 0으로 바뀌게 됩니다. 이틀 후까지 전송되지 않는 다면 발송에 사용한 Credit은 Point 로 환급 됩니다.
발송 여부 확인은 청기와랩 홈페이지의 발송 내역 Report 페이지에서 화려한 Graph와 표로 보실 수도 있습니다. 프로그램을 작성하여 확인하기 어려운 상황에서 유용한 정보를 제공해 줍니다.
Tutorial 2를 마치며...
May the code be with you...
다음 튜토리얼에서는 다른 언어 예제에 대한 더 자세한 비하인드 스토리가 이어 집니다!
sms smsapi example tutorial