294 lines
6.3 KiB
Markdown
294 lines
6.3 KiB
Markdown
# 리스크/알림 위젯 API 키 발급 가이드 🚨
|
||
|
||
## 📌 개요
|
||
|
||
리스크/알림 위젯은 **공공데이터포털 API**를 사용합니다:
|
||
|
||
1. ✅ **기상청 API** (날씨 특보) - **이미 설정됨!**
|
||
2. 🔧 **국토교통부 도로교통 API** (교통사고, 도로공사) - **신규 발급 필요**
|
||
|
||
---
|
||
|
||
## 🔑 1. 기상청 특보 API (이미 설정됨 ✅)
|
||
|
||
현재 `.env`에 설정된 키:
|
||
```bash
|
||
KMA_API_KEY=ogdXr2e9T4iHV69nvV-IwA
|
||
```
|
||
|
||
**사용 API:**
|
||
- 기상특보조회서비스 (기상청)
|
||
- URL: https://www.data.go.kr/data/15000415/openapi.do
|
||
|
||
**제공 정보:**
|
||
- ☁️ 대설특보
|
||
- 🌀 태풍특보
|
||
- 💨 강풍특보
|
||
- 🌊 호우특보
|
||
|
||
---
|
||
|
||
## 🚗 2. 국토교통부 도로교통 API (신규 발급)
|
||
|
||
### 2️⃣-1. 공공데이터포털 회원가입
|
||
|
||
```
|
||
👉 https://www.data.go.kr
|
||
```
|
||
|
||
1. 우측 상단 **회원가입** 클릭
|
||
2. 이메일 입력 및 인증
|
||
3. 약관 동의 후 가입 완료
|
||
|
||
---
|
||
|
||
### 2️⃣-2. API 활용신청
|
||
|
||
#### A. 실시간 교통사고 정보
|
||
|
||
```
|
||
👉 https://www.data.go.kr/data/15098913/openapi.do
|
||
```
|
||
|
||
**"실시간 교통사고 정보제공 서비스"** 페이지에서:
|
||
|
||
1. **활용신청** 버튼 클릭
|
||
2. 활용 목적: `기타`
|
||
3. 상세 기능 설명: `물류 대시보드 리스크 알림`
|
||
4. 신청 완료
|
||
|
||
#### B. 도로공사 및 통제 정보
|
||
|
||
```
|
||
👉 https://www.data.go.kr/data/15071004/openapi.do
|
||
```
|
||
|
||
**"도로공사 및 통제정보 제공 서비스"** 페이지에서:
|
||
|
||
1. **활용신청** 버튼 클릭
|
||
2. 활용 목적: `기타`
|
||
3. 상세 기능 설명: `물류 대시보드 리스크 알림`
|
||
4. 신청 완료
|
||
|
||
⚠️ **승인까지 약 2-3시간 소요** (즉시 승인되는 경우도 있음)
|
||
|
||
---
|
||
|
||
### 2️⃣-3. 인증키 확인
|
||
|
||
```
|
||
👉 https://www.data.go.kr/mypage/myPageOpenAPI.do
|
||
```
|
||
|
||
**마이페이지 > 오픈API > 인증키**에서:
|
||
|
||
1. **일반 인증키(Encoding)** 복사
|
||
2. 긴 문자열 전체를 복사하세요!
|
||
|
||
**예시:**
|
||
```
|
||
aBc1234dEf5678gHi9012jKl3456mNo7890pQr1234sTu5678vWx9012yZa3456bCd7890==
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ 환경 변수 설정
|
||
|
||
### .env 파일 수정
|
||
|
||
```bash
|
||
cd /Users/leeheejin/ERP-node/backend-node
|
||
nano .env
|
||
```
|
||
|
||
### 다음 내용 **추가**:
|
||
|
||
```bash
|
||
# 기상청 API Hub 키 (기존 - 예특보 활용신청 완료 시 사용)
|
||
KMA_API_KEY=ogdXr2e9T4iHV69nvV-IwA
|
||
|
||
# 국토교통부 도로교통 API 키 (활용신청 완료 시 추가)
|
||
MOLIT_TRAFFIC_API_KEY=여기에_발급받은_교통사고_API_인증키_붙여넣기
|
||
MOLIT_ROADWORK_API_KEY=여기에_발급받은_도로공사_API_인증키_붙여넣기
|
||
```
|
||
|
||
⚠️ **주의사항:**
|
||
- API 활용신청이 **승인되기 전**에는 더미 데이터를 사용합니다
|
||
- **승인 후** API 키만 추가하면 **자동으로 실제 데이터로 전환**됩니다
|
||
- 승인 여부는 각 포털의 마이페이지에서 확인 가능합니다
|
||
|
||
### 저장 및 종료
|
||
- `Ctrl + O` (저장)
|
||
- `Enter` (확인)
|
||
- `Ctrl + X` (종료)
|
||
|
||
---
|
||
|
||
## 🔄 백엔드 재시작
|
||
|
||
```bash
|
||
docker restart pms-backend-mac
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 사용 가능한 API 정보
|
||
|
||
### 1️⃣ 기상청 특보 (KMA_API_KEY)
|
||
|
||
**엔드포인트:**
|
||
```
|
||
GET /api/risk-alerts/weather
|
||
```
|
||
|
||
**응답 예시:**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "weather-001",
|
||
"type": "weather",
|
||
"severity": "high",
|
||
"title": "대설특보",
|
||
"location": "강원 영동지역",
|
||
"description": "시간당 2cm 이상 폭설 예상",
|
||
"timestamp": "2024-10-14T10:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2️⃣ 교통사고 (MOLIT_TRAFFIC_API_KEY)
|
||
|
||
**엔드포인트:**
|
||
```
|
||
GET /api/risk-alerts/accidents
|
||
```
|
||
|
||
**응답 예시:**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "accident-001",
|
||
"type": "accident",
|
||
"severity": "high",
|
||
"title": "교통사고 발생",
|
||
"location": "경부고속도로 서울방향 189km",
|
||
"description": "3중 추돌사고로 2차로 통제 중",
|
||
"timestamp": "2024-10-14T10:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3️⃣ 도로공사 (MOLIT_ROADWORK_API_KEY)
|
||
|
||
**엔드포인트:**
|
||
```
|
||
GET /api/risk-alerts/roadworks
|
||
```
|
||
|
||
**응답 예시:**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": "construction-001",
|
||
"type": "construction",
|
||
"severity": "medium",
|
||
"title": "도로 공사",
|
||
"location": "서울외곽순환 목동IC~화곡IC",
|
||
"description": "야간 공사로 1차로 통제 (22:00~06:00)",
|
||
"timestamp": "2024-10-14T10:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 테스트
|
||
|
||
### 1. API 키 발급 확인
|
||
```bash
|
||
curl "https://www.data.go.kr/mypage/myPageOpenAPI.do"
|
||
```
|
||
|
||
### 2. 백엔드 API 테스트
|
||
```bash
|
||
# 날씨 특보
|
||
curl "http://localhost:9771/api/risk-alerts/weather" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
|
||
# 교통사고
|
||
curl "http://localhost:9771/api/risk-alerts/accidents" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
|
||
# 도로공사
|
||
curl "http://localhost:9771/api/risk-alerts/roadworks" \
|
||
-H "Authorization: Bearer YOUR_TOKEN"
|
||
```
|
||
|
||
### 3. 대시보드에서 위젯 확인
|
||
1. `http://localhost:9771/admin/dashboard` 접속
|
||
2. 우측 사이드바 → **🚨 리스크 / 알림** 드래그
|
||
3. 실시간 정보 확인!
|
||
|
||
---
|
||
|
||
## 🔧 트러블슈팅
|
||
|
||
### 1. "API 키가 유효하지 않습니다" 오류
|
||
|
||
**원인**: API 키가 잘못되었거나 활성화되지 않음
|
||
|
||
**해결방법**:
|
||
1. 공공데이터포털에서 API 키 재확인
|
||
2. 신청 후 **승인 대기** 상태인지 확인 (2-3시간 소요)
|
||
3. `.env` 파일에 복사한 키가 정확한지 확인
|
||
4. 백엔드 재시작 (`docker restart pms-backend-mac`)
|
||
|
||
---
|
||
|
||
### 2. "서비스가 허용되지 않습니다" 오류
|
||
|
||
**원인**: 신청한 API와 요청한 서비스가 다름
|
||
|
||
**해결방법**:
|
||
1. 공공데이터포털 마이페이지에서 **신청한 서비스 목록** 확인
|
||
2. 필요한 서비스를 **모두 신청**했는지 확인
|
||
3. 승인 완료 상태인지 확인
|
||
|
||
---
|
||
|
||
### 3. 데이터가 표시되지 않음
|
||
|
||
**원인**: API 응답 형식 변경 또는 서비스 중단
|
||
|
||
**해결방법**:
|
||
1. 공공데이터포털 **공지사항** 확인
|
||
2. API 문서에서 **응답 형식** 확인
|
||
3. 백엔드 로그 확인 (`docker logs pms-backend-mac`)
|
||
|
||
---
|
||
|
||
## 💡 참고 링크
|
||
|
||
- 공공데이터포털: https://www.data.go.kr
|
||
- 기상청 Open API: https://data.kma.go.kr
|
||
- 국토교통부 Open API: https://www.its.go.kr
|
||
- API 활용 가이드: https://www.data.go.kr/tcs/dss/selectApiDataDetailView.do
|
||
|
||
---
|
||
|
||
**완료되면 브라우저 새로고침 (Cmd + R) 하세요!** 🚨✨
|
||
|