此页面由 Cloud Translation API 翻译。

会话数

在 Health Connect 中，时段是指用户为从事某个活动而花费的时长。SleepSessionRecord 和 ExerciseSessionRecord 数据类型都是时段。

通过时段，用户可以衡量一段时间内基于时间的性能，例如连续心率或位置数据。

ExerciseSessionRecord 时段涵盖了各种各样的活动，从跑步到打羽毛球都在范围内。

SleepSessionRecord 时段包含记录睡眠阶段的数据，例如 AWAKE、SLEEPING 和 DEEP。

子类型数据是“属于”某时段的数据，仅当与父时段（例如睡眠阶段、锻炼细分）一起被读取时才有意义。

关联数据是指可被单独读取或可被与其他时段一起读取的 Record 数据（例如步数、心率）。

常规准则

以下是一些有关如何在 Health Connect 中使用时段的最佳实践准则。

时段应被用于添加特定锻炼或活动的数据，或者用于睡眠：

suspend fun writeExerciseSession(healthConnectClient: HealthConnectClient) {
    healthConnectClient.insertRecords(
        listOf(
            ExerciseSessionRecord(
                startTime = Instant.parse("2022-05-10T10:00:00.000Z"),
                startZoneOffset = ZoneOffset.of("-08:00"),
                endTime = Instant.parse("2022-05-10T11:00:00.000Z"),
                endZoneOffset = ZoneOffset.of("-08:00"),
                exerciseType = ExerciseSessionRecord.ExerciseType.WALKING,
                title = "My Walk"
            ),
            StepsRecord(
                startTime = Instant.parse("2022-05-10T10:00:00.000Z"),
                startZoneOffset = ZoneOffset.of("-08:00"),
                endTime = Instant.parse("2022-05-10T10:30:00.000Z"),
                endZoneOffset = ZoneOffset.of("-08:00"),
                count = 2800
            ),
StepsRecord(
                startTime = Instant.parse("2022-05-10T10:30:00.000Z"),
                startZoneOffset = ZoneOffset.of("-08:00"),
                endTime = Instant.parse("2022-05-10T11:00:00.000Z"),
                endZoneOffset = ZoneOffset.of("-08:00"),
                count = 3200
            ),  
        )
    )
}

时段不应被用于常规测量，例如每日步数。
子类型数据不包含 UID，但关联的数据具有各不相同的 UID。
子类型数据需要在时段中与不重叠的依序时间戳对应。不过，允许设置间隔。
如果用户想让数据关联到时段（并作为时段的一部分进行跟踪）而不是持续记录，时段非常有用。

睡眠时段

您可以在 Health Connect 中读取或写入睡眠数据。睡眠数据会显示为时段，且可分为 8 个各不相同的睡眠阶段：

UNKNOWN：未指明或不清楚用户是否正在睡觉。
AWAKE：用户在一个睡眠周期内（而不是在白天）处于清醒状态。
SLEEPING：对睡眠的通用或粗略描述。
OUT_OF_BED：用户在睡眠时段下床。
AWAKE_IN_BED：用户在床上但处于清醒状态。
LIGHT：用户处于浅层睡眠周期。
DEEP：用户处于深层睡眠周期。
REM：用户处于快速眼动睡眠周期。

这些值表示用户在特定时间范围内的睡眠类型。写入睡眠阶段是可选操作，但建议执行（如果可以的话）。

写入包含或不包含睡眠阶段的睡眠时段

SleepSessionRecord 数据类型包含 2 个部分：

整个时段（跨越睡眠的全部时长）。
睡眠时段的各个阶段，例如浅层睡眠或深层睡眠。

下面展示了如何插入不包含阶段的睡眠时段：

      SleepSessionRecord(
        title = "weekend sleep",
        startTime = startTime,
        endTime = endTime,
        startZoneOffset = ZoneOffset.UTC,
        endZoneOffset = ZoneOffset.UTC,
      )

下面展示了如何添加涵盖睡眠时段全部时长的各个阶段：

val stages = listOf(
    SleepSessionRecord.Stage(
        startTime = START_TIME
        endTime = END_TIME,
        stage = SleepSessionRecord.STAGE_TYPE_SLEEPING,
    )
)

SleepSessionRecord(
        title = "weekend sleep",
        startTime = START_TIME,
        endTime = END_TIME,
        startZoneOffset = START_ZONE_OFFSET,
        endZoneOffset = END_ZONE_OFFSET,
        stages = stages,
      )
  }

读取睡眠时段

对于返回的每个睡眠时段，您应检查是否也有睡眠阶段数据：

suspend fun readSleepSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response =
        healthConnectClient.readRecords(
            ReadRecordsRequest(
                SleepSessionRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
    for (sleepRecord in response.records) {
        // Retrieve relevant sleep stages from each sleep record
        val sleepStages = sleepRecord.stages
    }
}

删除睡眠时段

下面展示了如何删除时段。在此示例中，我们使用了睡眠时段：

suspend fun deleteSleepSession(
    healthConnectClient: HealthConnectClient,
    sleepRecord: SleepSessionRecord,
) {
    val timeRangeFilter = TimeRangeFilter.between(sleepRecord.startTime, sleepRecord.endTime)
    healthConnectClient.deleteRecords(SleepSessionRecord::class, timeRangeFilter)
}

锻炼时段

锻炼时段可涵盖跑步、打羽毛球等各种活动。

写入锻炼时段

下面展示了如何构建包含时段的插入请求：

suspend fun writeExerciseSession(healthConnectClient: HealthConnectClient) {
    healthConnectClient.insertRecords(
        listOf(
            ExerciseSessionRecord(
                startTime = START_TIME,
                startZoneOffset = START_ZONE_OFFSET,
                endTime = END_TIME,
                endZoneOffset = END_ZONE_OFFSET,
                exerciseType = ExerciseSessionRecord.ExerciseType.RUNNING,
                title = "My Run"
            ),
            DistanceRecord(
                startTime = START_TIME,
                startZoneOffset = START_ZONE_OFFSET,
                endTime = END_TIME,
                endZoneOffset = END_ZONE_OFFSET,
                distance = 5000.meters
            ),
            // ... other records
        )
    )
}

注意看前面的示例如何为 Distance 添加一条记录，该记录跨越时段的全部时长，但数据可以按照不同的粒度添加。

如果应用在用户跑步期间定期测量距离，另一种方法是添加许多条 Distance 记录，每条记录表示一部分跑步时长所覆盖的距离。

读取锻炼时段

下面的示例展示了如何读取锻炼时段：

suspend fun readExerciseSessions(
    healthConnectClient: HealthConnectClient,
    startTime: Instant,
    endTime: Instant
) {
    val response =
        healthConnectClient.readRecords(
            ReadRecordsRequest(
                ExerciseSessionRecord::class,
                timeRangeFilter = TimeRangeFilter.between(startTime, endTime)
            )
        )
    for (exerciseRecord in response.records) {
        // Process each exercise record
        // Optionally pull in with other data sources of the same time range.
        val distanceRecord =
            healthConnectClient
                .readRecords(
                    ReadRecordsRequest(
                        DistanceRecord::class,
                        timeRangeFilter =
                            TimeRangeFilter.between(
                                exerciseRecord.startTime,
                                exerciseRecord.endTime
                            )
                    )
                )
                .records
    }
}

写入子类型数据

时段还可由非必要的子类型数据组成，这类数据会利用更多信息使时段变得更丰富。

例如，锻炼时段可涵盖 ExerciseSegment、ExerciseLap 和 ExerciseRoute 类：

val segments = listOf(
  ExerciseSegment(
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
    segmentType = ActivitySegmentType.BENCH_PRESS,
    repetitions = 373
  )
)

val laps = listOf(
  ExerciseLap(
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
    length = 0.meters
  )
)

ExerciseSessionRecord(
  exerciseType = ExerciseSessionRecord.EXERCISE_TYPE_CALISTHENICS,
    startTime = Instant.parse("2022-01-02T10:10:10Z"),
    endTime = Instant.parse("2022-01-02T10:10:13Z"),
  startZoneOffset = ZoneOffset.UTC,
  endZoneOffset = ZoneOffset.UTC,
  segments = segments,
  laps = laps,
  route = route
)

删除锻炼时段

您可通过以下 2 种方式删除锻炼时段：

根据时间范围。
根据 UID。

下面展示了如何根据时间范围删除子类型数据：

suspend fun deleteExerciseSession(
    healthConnectClient: HealthConnectClient,
    exerciseRecord: ExerciseSessionRecord,
) {
    val timeRangeFilter = TimeRangeFilter.between(sleepRecord.startTime, sleepRecord.endTime)
    healthConnectClient.deleteRecords(SleepSessionRecord::class, timeRangeFilter)
    // delete the associated distance record
    healthConnectClient.deleteRecords(DistanceRecord::class, timeRangeFilter)
}

您还可根据 UID 删除子类型数据。不过，这样做只会删除锻炼时段，不会删除关联的数据：

suspend fun deleteExerciseSession(
    healthConnectClient: HealthConnectClient,
    exerciseRecord: ExerciseSessionRecord,
) {
    healthConnectClient.deleteRecords(
        ExerciseSessionRecord::class,
        recordIdsList = listOf(exerciseRecord.metadata.id),
        clientRecordIdsList = emptyList()
    )
}