Immuni API 接口详解与技术实现分析

概述

Immuni 是一款基于接触者追踪技术的公共卫生应用，其 API 设计遵循了隐私保护和数据安全的原则。本文将深入解析 Immuni API 的技术架构、核心功能模块及其实现细节。

API 架构设计

Immuni API 采用 RESTful 风格设计，基于 OpenAPI 3.0.1 规范，主要包含五个核心功能模块：

1. 应用配置服务
2. OTP 验证服务
3. 暴露数据采集服务
4. 暴露数据报告服务
5. 分析服务

核心功能模块详解

1. 应用配置服务

功能描述：提供移动客户端启动时所需的配置参数，包括风险评估权重等关键参数。

技术实现：

• 支持平台差异化配置（iOS/Android）
• 支持按构建版本号区分配置
• 响应缓存60分钟

请求示例：

GET /v1/settings?platform=ios&build=123

关键参数：

• platform: 客户端平台（ios/android）
• build: 应用构建版本号（≥1的整数）

2. OTP 验证服务

功能描述：为医疗机构提供一次性密码(OTP)授权机制，用于验证用户上传数据的合法性。

技术特点：

• OTP 格式为10位大写字母和数字组合（正则：^[AEFHIJKLQRSUWXYZ1-9]{10}$）
• 包含症状开始日期
• 204响应禁止缓存

数据模型：

OTPUpload:
  properties:
    otp: 9K2RAY8UUQ  # 示例值
    symptoms_started_on: 2020-10-01  # 日期格式

3. 暴露数据采集服务

3.1 OTP 预验证

功能：在正式上传前验证OTP有效性

安全机制：

• 使用OTP Bearer Token认证
• 支持模拟请求头（Immuni-Dummy-Data）

3.2 数据上传

技术细节：

• 上传过去14天的TEK（临时暴露密钥）
• 包含用户居住地区代码（2位大写字母）
• 客户端时钟同步机制（Immuni-Client-Clock头）
• 服务端会覆盖客户端计算的transmission_risk_level

TEK数据结构：

TEK:
  properties:
    key_data: utdH33iMRTapATp7iK3hdA==  # Base64编码
    rolling_start_number: 2648160  # ≥0的整数
    rolling_period: 144  # ≥0的整数

4. 暴露数据报告服务

功能架构：

1. 获取TEK区块索引（/keys/index）

   • 返回最近14天的TEK区块范围
   • 缓存30分钟

2. 下载特定TEK区块（/keys/{TEKChunkIndex}）

   • 区块索引从1开始递增
   • 区块缓存15天

数据流：

移动客户端 → 获取索引 → 下载新TEK → 本地匹配计算

5. 分析服务

数据采集类型：

1. iOS设备运行数据

   • 使用设备认证SDK验证分析令牌
   • 遵循月度数据收集策略

2. Android设备运行数据

   • 使用SafetyNet硬件证明令牌认证

安全机制：

• 所有请求支持模拟模式（Dummy-Data）
• 区分平台的数据收集策略

关键技术实现

1. 隐私保护设计

• TEK有效期严格限制为14天
• 所有个人数据去标识化处理
• 客户端计算的传播风险分数会被服务端覆盖

2. 性能优化

• 分级缓存策略（配置60分钟，TEK索引30分钟，TEK数据15天）
• 区块化TEK分发机制减少重复下载

3. 安全机制

• 双重认证（OTP+Bearer Token）
• 设备级认证（iOS设备认证SDK/Android SafetyNet）
• 模拟请求标识（Immuni-Dummy-Data头）

4. 数据模型

暴露检测摘要：

ExposureDetectionSummary:
  properties:
    date: 2020-10-01
    matched_key_count: 2  # ≥1
    days_since_last_exposure: 1  # 0-14
    attenuation_durations: [300, 0, 0]  # 3个≥0的整数
    maximum_risk_score: 4  # 0-4096

暴露信息详情：

ExposureInfo:
  properties:
    date: 2020-10-01
    duration: 1800  # 秒
    attenuation_value: 45  # dB
    total_risk_score: 7
    transmission_risk_level: 5

最佳实践建议

1. 客户端实现：

   • 实现严格的TEK本地管理（14天滚动窗口）
   • 合理使用缓存策略减少网络请求
   • 正确处理时钟偏差（Immuni-Client-Clock）

2. 服务端集成：

   • 医疗机构系统应实现OTP自动注册流程
   • 分析数据收集应遵循最小必要原则

3. 测试策略：

   • 充分利用Dummy-Data头进行集成测试
   • 模拟各种时钟偏差场景

总结

Immuni API 设计体现了隐私优先、安全可靠的技术理念，通过模块化的服务设计和严格的数据管控机制，在保障用户隐私的前提下实现了有效的接触者追踪功能。其技术实现中的区块化数据分发、分级缓存策略等设计值得类似系统参考借鉴。