2025-07-06-재난문자 API 활용 데이터 파이프라인 미니 프로젝트

[Projects] 재난문자 API 활용 실시간 알림 시스템 구축

1. 프로젝트 개요

• 문제 정의 : 기존 재난문자 알림은 정부 시스템을 통해 일괄적으로 제공되지만, 개발자나 특정 팀이 새로운 재난문자를 실시간으로 감지하고 특정 채널(예: Teams 메신저)로 즉시 알림을 받으며, 이력 관리까지 할 수 있는 자동화된 시스템은 부재했다. 실시간 정보의 중요성이 커지는 현대 사회에서, 이러한 정보의 신속한 파악과 공유는 필수적이다.
• 프로젝트 목표 : 행정안전부 재난문자 공공API를 활용하여, 새로운 재난문자가 발생할 경우 이를 실시간으로 감지하고, 팀 채널(Teams, Slack 등)로 즉시 알림을 전송하는 자동화된 시스템을 구축하는 것을 목표로 했다. 또한, 불필요한 중복 알림을 방지하고, 시스템 상태를 추적할 수 있도록 구현했다.
• 주요 성과 : Azure Functions의 서버리스 특성과 Event Hub의 스트리밍 기능을 활용하여, 5분마다 API를 수집하고 새로운 메시지를 감지하여 Teams에 실시간 알림을 보내는 End-to-End 파이프라인을 성공적으로 구현했다.

2. 아키텍처 및 기술 스택

이 프로젝트는 Azure 클라우드 서비스의 다양한 구성 요소를 활용하여 유연하고 확장 가능한 실시간 데이터 파이프라인을 구축했다.

2.1 아키텍처 다이어그램

2.2 사용 기술 스택

• Azure Functions (Python 3.11) : 재난문자 API 호출 및 데이터 처리, Event Hub로 데이터 전송, 웹훅 알림 전송 등 핵심 로직을 담당하는 서버리스 컴퓨팅 서비스. (자세한 내용은 Azure Functions 블로그 포스팅 링크참조)
  • 트리거 : Time Trigger (5분 주기 실행)
  • 바인딩 : Event Hub Output Binding, Blob Storage Input/Output Binding, HTTP Output Binding (Webhook)
• Azure Event Hubs : Functions App에서 전송된 새로운 재난문자 데이터를 안정적으로 수집하고 스트리밍하는 고처리량 이벤트 허브(Event hub 블로그 포스팅 링크)
• Azure Blob Storage : 이전에 처리된 재난문자 ID를 저장하여 중복 알림을 방지하는 상태 관리 저장소
• Teams Webhook (또는 Slack/Discord Webhook) : Functions에서 처리된 알림 메시지를 팀 채널로 실시간 전송하는 통신 채널
• Python : 프로젝트 로직 구현 언어
  • requests : 외부 API 호출을 위한 라이브러리
  • azure-storage-blob : Blob Storage 연동을 위한 라이브러리
• Azure Stream Analytics & Power BI : Event Hubs로 수집된 데이터를 실시간으로 분석하고 시각화 하기 위한 추가 계획

3. 주요 기능 및 구현

3.1 주기적인 재난문자 API 호출

• Time Trigger 활용 : Azure Functions의 Time Trigger를 사용하여 5분마다 행정안전부 재난문자 API를 자동으로 호출한다. 이는 수동 작업 없이 항상 최신 정보를 확인하는 자동화된 시스템을 구축한다.

  3.2 새로운 메시지 감지 및 중복 방지

• Blob Storage 기반 상태 관리 : Blob Storage의 특정 txt 파일에 마지막으로 처리된 재난문자의 고유 ID (예: ‘SN’ 값)를 저장한다.
• ID 비교 로직 : API를 통해 새로 가져온 재난문자 목록을 Blob Storage에 저장된 이전 ID와 비교하여, 아직 처리되지 않은 ‘새로운’ 메시지만을 정확하게 식별한다.

3.3 실시간 데이터 스트리밍 및 알림

• Event Hubs로 데이터 전송 : 새로 감지된 재난문자 데이터는 Azure Functions의 Event Hub Output Binding을 통해 Event Hub로 즉시 전송된다. 이는 이후 실시간 분석 파이프라인의 기초를 마련한다.
• 조건부 웹훅 알림 :
  • 새로운 메시지 발생 시 : 새로운 재난문자가 감지되면, 해당 내용을 상세히 포함한 알림 메시지를 Teams 웹훅으로 즉시 전송한다.
  • 변동 없을 시 : 새로운 메시지가 없더라도, 시스템이 정상적으로 작동하고 있음을 확인하는 간략한 알림을 주기적으로 전송하여 모니터링을 돕는다.

3.4 시스템 작동 확인 및 모니터링

4. 프로젝트 진행 과정에서 어려웠던 점과 해결

이 미니 프로젝트는 재난문자 API라는 외부 서비스와 다양한 Azure 클라우스 서비스를 통합하는 과정에서 여러가지 기술적 어려움을 겪게 되었다. 해결하는 과정은 Functions, Event Hubs, Blob Storage등 Azure 서비스에 대한 깊이 있는 이해와 문제 해결 능력을 향상시키는 중요한 학습 경험이 되었다.

4.1 외부 API 연동의 안정성 확보

• 난관: 행정안전부 재난문자 API는 때때로 응답 지연이나 일시적인 오류를 발생시켰다. 또한, 예상치 못한 JSON 응답 구조 변화가 있을 경우 파싱 오류가 발생할 수 있었다.

• 해결:

  • requests 라이브러리의 timeout 옵션을 사용하여 API 호출 지연을 방지했다.

  • try-except 구문을 활용하여 API 호출 실패, JSON 파싱 오류 등 발생 가능한 모든 예외를 포괄적으로 처리했다.

  • API 응답의 ‘body’ 필드 존재 여부 및 데이터 타입(리스트 여부)을 사전에 검사하여 안정성을 높였다.

  • API 호출 실패 시 Teams 웹훅을 통해 즉시 알림을 보내도록 구현하여 시스템의 이상 상태를 신속하게 파악할 수 있도록 했다.

4.2 Blob Storage를 활용한 상태 관리의 견고성 확보

• 난관: 재난문자 중복 알림을 방지하기 위해 Blob Storage에 마지막 처리 ID를 저장하는 방식은 파일이 없거나, 읽기/쓰기 중 오류가 발생할 경우 시스템이 멈출 수 있는 위험이 있었다. 또한, ID가 숫자가 아닌 경우 비교 로직에서 문제가 발생할 수 있었다.

• 해결:

  • Blob Storage 연결 문자열(BlobStorageConnectionString)이 환경 변수에 설정되지 않았을 경우를 감지하여 함수 실행을 중단하고 알림을 보내도록 했다.

  • 컨테이너가 존재하지 않을 경우 자동으로 생성하는 로직을 추가하여 초기 설정의 편의성을 높였다.

  • Blob 파일이 존재하지 않거나, ID 로드 중 오류 발생 시에도 함수가 비정상 종료되지 않고 초기값으로 진행되도록 예외 처리했다.

  • 메시지 ID(SN)를 비교하기 전에 int()로 변환하여 숫자 비교의 안정성을 확보하고, 변환 실패 시 해당 메시지를 건너뛰도록 처리했다.

4.3 Azure Functions 환경 변수 및 바인딩 구성의 정확성

• 난관: local.settings.json에 정의된 환경 변수들이 Azure Functions App의 ‘애플리케이션 설정’으로 정확하게 업로드되지 않거나, EventHubName, EventHubConnectionString, AzureWebHookUrl 등의 이름이 코드와 function.json (Python V2 앱 모델에서는 데코레이터 매개변수) 간에 불일치하여 발생하는 문제가 있었다.

• 해결:

  • VS Code의 Azure Functions 확장 기능을 활용하여 local.settings.json의 설정을 Azure에 정확하게 업로드했다.

  • 환경 변수 이름을 os.environ.get("변수명")으로 가져올 때, 해당 변수가 설정되지 않았을 경우를 대비하여 오류 로깅 및 Teams 알림을 추가했다.

  • Event Hubs 이름(EventHubName)과 연결 문자열(EventHubConnection), 웹훅 URL(AzureWebHookUrl)을 local.settings.json에 명확히 정의하고, 코드의 데코레이터 및 환경 변수 호출 부분에서 이 이름들을 정확히 일치시켰다.

5. 향후 발전 방향 및 확장 계획

이 프로젝트는 현재 실시간 재난문자 알림이라는 핵심 기능을 성공적으로 구현했다. 하지만 수집된 데이터를 더욱 깊이 있게 분석하고 활용하며, 시스템의 유연성을 높이기 위한 다양한 발전 방향을 계획하고 있다.

5.1 실시간 데이터 분석 및 시각화 강화

• Azure Stream Analytics 연동: Event Hubs로 수집된 재난문자 데이터를 Azure Stream Analytics로 전달하여, 실시간으로 특정 키워드 출현 빈도, 지역별 재난문자 발생량, 유형별 트렌드 등을 분석하고 집계할 계획이다.

• Power BI 대시보드 구축: Stream Analytics의 분석 결과를 Power BI 대시보드와 연동하여, 재난문자 발생 현황, 유형별 분포, 시간대별 트렌드 등을 실시간으로 시각화할 예정이다. 이는 운영팀이 한눈에 재난 상황을 파악하는 데 큰 도움이 될 것이다.

5.2 데이터 저장 및 관리 고도화

• 영구 데이터베이스 저장: 현재는 Blob Storage에 최신 ID만 저장하고 있지만, 수집된 모든 재난문자 데이터를 Azure SQL Database나 Azure Cosmos DB와 같은 데이터베이스에 영구적으로 저장하는 방안을 고려 중이다. 이를 통해 과거 데이터에 대한 심층 분석 및 보고서 생성이 가능해진다.

5.3 추가 기능 구현 및 시스템 확장

• 사용자 맞춤 알림: 특정 지역이나 재난 유형에 대한 맞춤 알림을 받을 수 있도록 사용자 설정 기능을 추가할 계획이다.

• 다양한 알림 채널 연동: Teams 외에 SMS, 이메일, 모바일 푸시 알림 등 다양한 채널로 알림을 확장한다.

• AI/ML 기반 분석: 재난문자 텍스트의 감성 분석, 이상 징후 패턴 예측 등 머신러닝 기반의 고급 분석 기능을 도입하여 알림의 정확성과 통찰력을 높이는 방안을 검토한다.

6. 프로젝트 코드 저장소

• 프로젝트의 모든 소스 코드는 다음 GitHub 저장소에서 확인할 수 있습니다.

• 2025 10