daglo API 가이드

Korean

English

Korean

English

Appearance

Get(Polling)과 Callback ​

이 문서는 STT(음성 인식) 서비스를 제공하는 API의 응답 방식 중 GET(Polling)과 CALLBACK의 차이에 대해 설명합니다. 이 가이드는 개발자와 서비스 담당자가 API를 효과적으로 활용할 수 있도록 돕기 위해 작성되었습니다.

1. GET(Polling) 방식 ​

개념 설명 ​

Polling 방식은 클라이언트가 서버로부터 정보를 요청할 때 사용하는 HTTP 메소드입니다. 클라이언트는 특정 리소스를 식별하기 위해 URL을 통해 요청을 보내고, 서버는 해당 리소스에 대한 응답을 반환합니다. 이 방식은 주로 데이터를 읽어오는 데 사용되며, 서버에 영향을 미치지 않는 안전한 요청입니다.

Polling 요청의 구조 ​

  • HTTP 메소드: GET
  • URL: 요청할 리소스를 식별하는 URL (예: https://apis.daglo.ai/stt/v1/async/transcripts/{rid})
  • 쿼리 파라미터: 요청 시 필요한 추가 정보 (필요에 따라 사용)

예시 ​

text
GET https://apis.daglo.ai/stt/v1/async/transcripts/12345

응답 예시 ​

json
{
  "status": "transcribed",
  "sttResults": [
    "transcript": "안녕하세요, 예제입니다."
  ]
}

도식 ​

text
클라이언트 --(GET)--> 서버
클라이언트 <--(응답)-- 서버

2. CALLBACK 방식 ​

개념 설명 ​

CALLBACK 방식은 서버가 클라이언트에게 비동기적으로 데이터를 전달하는 방법입니다. 클라이언트는 서버에 요청을 보낼 때 콜백 URL을 제공하며, 서버는 처리가 완료된 후 해당 URL로 결과를 전송합니다. 이 방식은 비동기 작업에 유용하며, 클라이언트가 지속적으로 서버에 상태를 확인할 필요가 없습니다.

CALLBACK 요청의 구조 ​

  • HTTP 메소드: POST (콜백 URL 등록 시)
  • URL: 클라이언트가 결과를 받을 콜백 URL
  • 본문: 요청에 필요한 데이터 (예: 받아쓰기 결과)

예시 ​

  1. 클라이언트가 비동기 요청을 보낼 때 콜백 URL을 포함

    shell
    {
    // ...
    "callback": {
        "url": "https://client.example.com/callback",
        "headers": { "<Header1_KEY>": "<Header1_Value>" } // Optional
    }
}

  2. 서버가 처리를 완료하고 콜백 URL로 결과를 전송

    shell
    POST https://client.example.com/callback
Content-Type: application/json

{
  "status": "transcribed",
  "sttResults": [
    "transcript": "안녕하세요, 예제입니다."
  ]
}

도식 ​

text
클라이언트 --(POST 요청, 콜백 URL 포함)--> 서버
(서버 처리 중)
서버 --(결과 전달)--> 클라이언트 (콜백 URL로 POST)

3. GET(Polling) 방식과 CALLBACK 방식의 차이 ​

구분GET(Polling) 방식CALLBACK 방식
요청 방식클라이언트가 직접 요청 후 응답 수신클라이언트가 요청 시 콜백 URL 제공, 서버가 결과를 비동기적으로 전송
데이터 전달요청 시점에 즉시 응답처리 완료 후 콜백 URL로 비동기적 전달
사용 사례단순 조회, 즉시 응답이 필요한 경우비동기 처리, 대기 시간이 긴 작업
네트워크 부하클라이언트가 주기적으로 상태 확인 필요서버가 한 번의 콜백으로 결과 전달
구현 복잡도비교적 간단콜백 URL 관리 및 보안 고려 필요

4. 결론 ​

GET(Polling) 방식과 CALLBACK 방식은 각각의 장단점이 있으며, 사용자의 필요와 시스템의 특성에 따라 적절한 방식을 선택하여 활용할 수 있습니다. GET(Polling) 방식은 간단하고 직관적이며, 즉시 응답이 필요한 경우에 적합합니다. CALLBACK 방식은 비동기 작업에 유리하며, 클라이언트가 지속적으로 서버 상태를 확인할 필요가 없는 장점이 있습니다.

5. CALLBACK 서버 구성 방식 ​

CALLBACK 서버는 클라이언트가 서버로부터 비동기적으로 데이터를 받을 수 있도록 구성됩니다. 이를 위해 클라이언트는 콜백 URL을 서버에 제공하고, 서버는 작업 완료 후 해당 URL로 결과를 전송합니다. CALLBACK 서버를 구성하는 방법은 다음과 같은 단계로 이루어집니다.

1) 서버 설정 ​

서버 프레임워크 선택

CALLBACK 서버를 구현하기 위해서는 적절한 서버 프레임워크를 선택해야 합니다. 예를 들어, Python의 Flask, Node.js의 Express, Java의 Spring Boot 등이 사용될 수 있습니다.

2) 콜백 엔드포인트 설정 ​

엔드포인트 정의

콜백 URL로 사용할 엔드포인트를 정의합니다. 이 엔드포인트는 서버가 작업 완료 후 결과를 POST 요청으로 전송받을 수 있도록 준비되어야 합니다.

예시 (Python Flask)

text
from flask import Flask, request

app = Flask(__name__)

@app.route('/callback', methods=['POST'])
def stt_callback():
    data = request.get_json()
    # Callback 받은 데이터 처리 로직
    print(data['rid'])
    print(data['status'])
    print(data['sttResults'])

    return 'OK'

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)

3) 보안 설정 ​

인증 및 인가

콜백 URL이 외부에서 접근 가능하기 때문에, 인증 및 인가를 통해 보안을 강화해야 합니다. 이를 위해 JWT 토큰, API 키 등을 사용하여 요청을 인증할 수 있습니다.

예시 (JWT 토큰 인증)

text
python코드 복사
import jwt

SECRET_KEY = 'your_secret_key'

def verify_token(token):
    try:
        jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
        return True
    except jwt.ExpiredSignatureError:
        return False
    except jwt.InvalidTokenError:
        return False

@app.route('/callback', methods=['POST'])
def callback():
    token = request.headers.get('Authorization')
    if not token or not verify_token(token):
        return jsonify({'message': 'Unauthorized'}), 401

    data = request.get_json()
    # 콜백 데이터 처리 로직 추가

    return jsonify({'message': 'Callback received successfully'}), 200

4) 로깅 및 모니터링 ​

요청 로깅

콜백 요청을 로깅하여 추후에 문제 발생 시 디버깅할 수 있도록 합니다.

예시 (로깅 추가)

text
python코드 복사
import logging

logging.basicConfig(level=logging.INFO)

@app.route('/callback', methods=['POST'])
def callback():
    data = request.get_json()
    logging.info(f"Received callback with data: {data}")

    # 콜백 데이터 처리 로직 추가

    return jsonify({'message': 'Callback received successfully'}), 200

5) 테스트 및 배포 ​

테스트

콜백 서버를 충분히 테스트하여 모든 시나리오에서 올바르게 동작하는지 확인합니다. 유닛 테스트, 통합 테스트 등을 통해 안정성을 검증합니다.

배포

테스트가 완료되면 콜백 서버를 프로덕션 환경에 배포합니다. 이 과정에서 로드 밸런싱, 스케일링 등을 고려하여 안정적인 운영을 보장합니다.

결론

CALLBACK 서버를 구성하는 방식은 클라이언트가 비동기적으로 데이터를 받을 수 있도록 설계되어야 합니다. 이를 위해 서버 프레임워크 선택, 엔드포인트 설정, 보안 강화, 로깅 및 모니터링, 테스트 및 배포 등의 단계가 필요합니다. 이러한 과정을 통해 안정적이고 안전한 CALLBACK 서버를 구현할 수 있습니다.

업데이트 이력

  • 20240902 ver1.0 API 문서가 작성되었습니다.