대기 중인 데이터 수집 요청 조회 API
공통 요청 헤더
모든 dha-sleep API 요청은 공통 요청 헤더를 준수해야 합니다. User-Agent, Accept-Language, 인증 헤더 요구사항을 먼저 확인하세요.
개요
대기 중인 데이터 수집 요청 조회 API는 모바일 앱이 서버에서 생성된 건강 데이터 수집 요청 목록을 조회하는 기능을 제공합니다. LLM/Agent가 사용자별로 분석하여 생성한 개인화된 데이터 수집 요청을 앱에서 확인하고, HealthKit/Health Connect SDK를 통해 해당 데이터를 수집할 수 있습니다.
주요 특징
- 개인화된 데이터 수집: 모든 사용자에게 동일한 데이터가 아닌, LLM/Agent가 분석한 사용자별 필요 데이터만 요청
- 플랫폼별 필터링: iOS/Android 플랫폼에 맞는 요청만 조회
- 권한 기반 필터링: 사용자가 승인한 권한에 해당하는 요청만 필터링 가능
- 집계 간격 지원: 시간/일/월 단위 집계 데이터 또는 Raw Data 요청 지원
호출 시점
앱에서 이 API를 호출해야 하는 시점:
- Onboarding 완료 시점: HealthKit/Health Connect 권한 동의 후 즉시
- Home Screen 진입 시점: 앱 실행 또는 Home Screen 표시 시
대기 중인 요청 조회
사용자의 대기 중인 데이터 수집 요청 목록을 조회합니다.
- HTTP Method:
GET - Path:
/v1/external-health/requests - 인증: 액세스 토큰 (
accessToken) 필요
Headers
| Header | Type | Description | Required |
|---|---|---|---|
Authorization | Bearer {accessToken} | 사용자 인증을 통해 발급받은 액세스 토큰입니다. | Yes |
Query Parameters
| Parameter | Type | Description | Required |
|---|---|---|---|
platform | string | 플랫폼 지정 (iOS 또는 Android) | Yes |
filterByGrantedPermissions | boolean | 승인된 권한 기준 필터링 여부 (기본값: false) | No |
Responses
| HTTP Status Code | 설명 | Error Code(s) |
|---|---|---|
200 OK | 성공 | - |
401 Unauthorized | 인증 실패 (유효하지 않은 액세스 토큰) | 10001 |
403 Forbidden | 권한이 승인되지 않음 | 21022 |
200 OK - 성공
데이터 수집 요청 목록 조회 성공:
{
"requests": [
{
"id": "B437BCAC-CFFF-468C-9A30-5786F74BDB87",
"type": "stepCount",
"startTime": 1764550800000,
"endTime": 1764637200000,
"interval": {
"type": "day",
"value": 1
}
},
{
"id": "BEC32F44-2647-44C8-8C74-1DF64097FA31",
"type": "heartRate",
"startTime": 1764550800000,
"endTime": 1764637200000,
"interval": {
"type": "hour",
"value": 1
}
},
{
"id": "6406D4AE-9C55-40D3-BE25-5EE0AD3859E9",
"type": "sleepAnalysis",
"startTime": 1764550800000,
"endTime": 1764637200000
}
]
}
수집할 데이터가 없는 경우:
{
"requests": []
}
응답 필드 명세
| Field | Data Type | Required | Description |
|---|---|---|---|
requests | Array<Object> | YES | 수집 요청 배열 (최소한 빈 배열) |
request.id | UUID | YES | 요청의 고유 식별자 |
request.type | String (Enum) | YES | 데이터 유형: stepCount, heartRate, sleepAnalysis 등 |
request.startTime | Int | YES | 수집 시작 시각 (Unix Epoch Time, milliseconds, Kotlin: Long, Swift: Int64) |
request.endTime | Int | YES | 수집 종료 시각 (Unix Epoch Time, milliseconds, Kotlin: Long, Swift: Int64) |
request.interval | Object | NO | 집계 간격 설정 (없을 경우 Raw Data 반환) |
request.interval.type | String (Enum) | Conditional | 간격 유형: year, month, day, hour, minute, second |
request.interval.value | Int | Conditional | 집계 간격 값 |
지원하는 데이터 유형 (type)
| Type | Category | Description |
|---|---|---|
stepCount | Quantity | 걸음 수 |
heartRate | Quantity | 심박수 |
heartRateVariability | Quantity | 심박변이도 |
respiratoryRate | Quantity | 호흡수 |
oxygenSaturation | Quantity | 산소포화도 |
activeEnergyBurned | Quantity | 활동 에너지 |
sleepAnalysis | Category | 수면 분석 |
403 Forbidden - 권한 없음
예시: 데이터 유형에 대한 권한 없음 (PERMISSION_NOT_GRANTED - 21022)
{
"code": 21022,
"message": "PERMISSION_NOT_GRANTED",
"detail": "요청된 데이터 유형에 대한 권한이 승인되지 않았습니다.",
"requiredPermissions": ["heartRate", "sleepAnalysis"],
"grantedPermissions": ["stepCount"]
}
참고:
filterByGrantedPermissions=true파라미터를 사용하면, 권한이 없는 데이터 유형의 요청은 오류 대신 응답에서 제외됩니다.
설명
- 이 API는 앱이 수집해야 할 건강 데이터 목록을 조회하는 핵심 기능입니다.
- 요청 목록이 비어있는 경우:
requests: []가 반환되면 데이터 수집 단계를 건너뛰어야 합니다. - 집계 간격 (interval):
interval이 있는 경우: 해당 간격으로 집계된 데이터를 수집 (예: 1시간 단위 평균 심박수)interval이 없는 경우: Raw Data를 수집
- 플랫폼별 처리:
- iOS: HealthKit SDK를 사용하여 데이터 수집
- Android: Health Connect SDK를 사용하여 데이터 수집
- 권한 필터링:
filterByGrantedPermissions=true를 사용하면 403 오류 없이 승인된 권한에 해당하는 요청만 반환됩니다.