Google Health API là một API mới được xây dựng từ đầu, cho phép nhà phát triển truy vấn dữ liệu người dùng Fitbit. Đây không chỉ là một bản cập nhật mà còn là một bước đi chiến lược để đảm bảo ứng dụng của bạn an toàn, đáng tin cậy và sẵn sàng cho những tiến bộ trong tương lai về công nghệ y tế. API này hỗ trợ một bảng điều khiển mới để đăng ký ứng dụng, hỗ trợ Google OAuth 2.0, các loại dữ liệu mới, giản đồ điểm cuối mới và định dạng phản hồi mới.
Hướng dẫn này được thiết kế để giúp nhà phát triển di chuyển các ứng dụng API Fitbit Web hiện có sang Google Health API mới.
Tại sao bạn nên di chuyển?
Sau đây là những lợi ích khi sử dụng Google Health API:
- Bảo mật nâng cao: Tuân thủ các phương pháp bảo mật hay nhất của Google, phù hợp với các tiêu chuẩn của Google về bảo mật, quyền riêng tư và danh tính.
- Tính nhất quán: Loại bỏ sự không nhất quán của các phiên bản cũ trong định dạng dữ liệu, múi giờ, đơn vị đo lường và việc xử lý lỗi để mang lại trải nghiệm trực quan hơn cho nhà phát triển.
- Khả năng mở rộng và đảm bảo cho tương lai: Được thiết kế để mở rộng quy mô nhằm đáp ứng nhu cầu trong tương lai và hỗ trợ các giao thức hiện đại như gRPC.
Đăng ký ứng dụng
Bạn phải đăng ký tất cả các ứng dụng Google Health API bằng Google Cloud Console. Đây là một trung tâm quản lý tất cả các ứng dụng Google của bạn.
Để biết hướng dẫn về cách đăng ký ứng dụng, hãy làm theo các bước trong phần Bắt đầu. Sau đây là những điểm khác biệt mà bạn sẽ nhận thấy khi đăng ký ứng dụng.
| Fitbit Web API | Google Health API | |
| Đường liên kết công khai | https://dev.fitbit.com/apps | https://console.cloud.google.com |
| Thêm ứng dụng mới | Nhấn vào Đăng ký ứng dụng mới |
|
| Thông tin cơ bản | Các trường cần điền:
|
Các trường cần điền:
|
| Các loại ứng dụng | Nhà phát triển phải chọn:
|
|
| ID khách hàng | Được đăng ký khi bạn lưu chế độ cài đặt ứng dụng | Được đăng ký riêng |
| Loại quyền truy cập | Quyền đọc và ghi được kiểm soát ở cấp ứng dụng | Quyền đọc và ghi được kiểm soát ở cấp phạm vi |
| URL bổ sung |
|
|
Triển khai OAuth
Các ứng dụng Google Health API chỉ hỗ trợ Thư viện ứng dụng Google OAuth2. Thư viện ứng dụng có sẵn cho các khung hình phổ biến, giúp việc triển khai OAuth 2.0 trở nên đơn giản hơn. Sau đây là sự khác biệt giữa thư viện Google OAuth2 và thư viện OAuth2 nguồn mở:
| Fitbit Web API | Google Health API | |
| Hỗ trợ thư viện OAuth2 | Nguồn mở | Thư viện ứng dụng Google OAuth2 |
| Chức năng | Không nhất quán trên các nền tảng | Nhất quán trên nhiều nền tảng |
| URL uỷ quyền | https://www.fitbit.com/oauth2/authorize | https://accounts.google.com/o/oauth2/v2/auth |
| URL mã thông báo | https://api.fitbit.com/oauth2/token | https://oauth2.googleapis.com/token |
| Thời gian tồn tại của mã truy cập | 8 giờ | 1 giờ |
| Kích thước mã truy cập | 1024 byte | 2048 byte |
| Mã làm mới | Mã làm mới được tạo khi bạn sử dụng Quy trình cấp mã uỷ quyền. Bạn chỉ có thể tạo 1 mã làm mới cho mỗi người dùng. Mã thông báo không bao giờ hết hạn và chỉ có thể được sử dụng một lần. | Để tạo mã làm mới, chuỗi uỷ quyền phải chứa tham số truy vấn "access_type=offline". Bạn có thể tạo nhiều mã làm mới cho một người dùng. Mã làm mới có thể dựa trên thời gian. Các mã này sẽ hết hạn nếu chưa được sử dụng trong 6 tháng, người dùng được cấp quyền truy cập dựa trên thời gian hoặc ứng dụng đang ở chế độ "Kiểm thử". Hãy xem phần Thời gian hết hạn của mã làm mới để biết thêm thông tin chi tiết. |
| Phản hồi bằng mã thông báo | Phản hồi JSON chứa:
|
Phản hồi JSON chứa:
Để lấy mã nhận dạng người dùng, hãy sử dụng điểm cuối users.getIdentity. |
Xác thực lại người dùng (Bắt buộc phải đồng ý lại)
Người dùng Fitbit phải đồng ý lại với chế độ tích hợp mới của bạn, vì ứng dụng của bạn đang sử dụng một thư viện OAuth khác. Không thể chuyển mã truy cập và mã làm mới sang Google Health API và hoạt động.
Phạm vi
Bạn phải cập nhật yêu cầu uỷ quyền để sử dụng các phạm vi của Google Health API. Các phạm vi này xác định xem ứng dụng của bạn có hỗ trợ các thao tác đọc hoặc ghi hay không. Không sử dụng những phạm vi không cần thiết cho ứng dụng của bạn. Bạn luôn có thể thêm nhiều phạm vi hơn sau này nếu thiết kế của ứng dụng thay đổi.
Phạm vi Google Health API là một URL loại HTTP bắt đầu bằng https://www.googleapis.com/auth/googlehealth.{scope}. Ví dụ: https://www.googleapis.com/auth/googlehealth.activity_and_fitness.
Liên kết phạm vi
Sau đây là cách các phạm vi của Fitbit Web API ánh xạ đến các phạm vi của Google Health API:
| Phạm vi của Fitbit Web API | Phạm vi của Google Health API |
|---|---|
| hoạt động | .activity_and_fitness .activity_and_fitness.readonly |
| cardio_fitness | .activity_and_fitness .activity_and_fitness.readonly |
| nhịp tim | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
| vị trí | .location.readonly |
| dinh dưỡng | .nutrition .nutrition.readonly |
| oxygen_saturation | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
| hồ sơ | .profile .profile.readonly |
| respiratory_rate | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
| cài đặt | .settings .settings.readonly |
| ngủ | .sleep .sleep.readonly |
| nhiệt độ | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
| cân nặng | .health_metrics_and_measurements .health_metrics_and_measurements.readonly |
Loại dữ liệu
Sau đây là danh sách các loại dữ liệu của Google Health API và cách các loại dữ liệu này liên kết với API Fitbit Web.
| Loại dữ liệu của Fitbit Web API | Loại dữ liệu API Google Health Mã nhận dạng điểm cuối |
|---|---|
| Số phút hoạt động cho vùng nhịp tim | Số phút hoạt động cho vùng nhịp timactive-zone-minutes
|
| Chứa các thay đổi về mức độ hoạt động của người dùng | Mức độ hoạt độngactivity-level
|
| Độ cao | Độ caoaltitude
|
| Lượng mỡ trong cơ thể | Lượng mỡ trong cơ thểbody-fat
|
caloriesOut trong mỗi vùng nhịp tim |
Lượng calo tiêu thụ theo vùng nhịp timcalories-in-heart-rate-zone
|
| Tóm tắt về HRV | Sự thay đổi tần số tim hằng ngàydaily-heart-rate-variability
|
| Tóm tắt SpO2 | Độ bão hoà oxy hằng ngàydaily-oxygen-saturation
|
| Tần số tim lúc nghỉ ngơi | Tần số tim lúc nghỉ ngơi hằng ngàydaily-resting-heart-rate
|
| Nhiệt độ trên da | Dữ liệu nhiệt độ cơ thể hằng ngày trong lúc ngủdaily-sleep-temperature-derivations
|
| Khoảng cách | Khoảng cáchdistance
|
| Hoạt động đã ghi | Bài tậpexercise
|
| Tầng | Số tầngfloors
|
| Nhịp tim | Nhịp timheart-rate
|
| Biến thiên nhịp tim trong ngày | Sự thay đổi tần số timheart-rate-variability
|
| SpO2 trong ngày | Độ bão hoà oxyoxygen-saturation
|
| Giá trị VO2 Max khi người dùng chạy | Tốc độ tiêu thụ oxy tối đa khi chạyrun-vo2-max
|
| Số phút ít vận động theo chuỗi thời gian hoạt động | Khoảng thời gian ít vận độngsedentary-period
|
| Ngủ | Ngủsleep
|
| Các bước | Các bướcsteps
|
Hoạt động caloriesOut |
Tổng lượng calototal-calories
|
| Giá trị tốc độ tiêu thụ oxy tối đa | Tốc độ tiêu thụ oxy tối đavo2-max
|
| Trọng lượng | Trọng lượngweight
|
Điểm cuối
Các điểm cuối REST sử dụng một cú pháp nhất quán cho tất cả các loại dữ liệu.
- Điểm cuối dịch vụ: URL loại HTTP cơ sở thay đổi thành https://health.googleapis.com.
- Cú pháp điểm cuối: Google Health API hỗ trợ một số lượng hạn chế các điểm cuối mà hầu hết các loại dữ liệu được hỗ trợ đều có thể sử dụng. Điều này cung cấp cú pháp nhất quán cho tất cả các kiểu dữ liệu và giúp bạn dễ dàng sử dụng các điểm cuối hơn.
- Giá trị nhận dạng người dùng: Bạn phải chỉ định user ID hoặc me trong cú pháp điểm cuối. Khi sử dụng tôi, mã nhận dạng người dùng sẽ được suy luận từ mã truy cập.
Ví dụ: Sau đây là ví dụ về điểm cuối GET Profile được gọi bằng Google Health API
GET https://health.googleapis.com/v4/users/me/profile
Mối liên kết điểm cuối
Hãy xem bảng Tính sẵn có của kiểu dữ liệu để biết danh sách các kiểu dữ liệu có sẵn và các phương thức API mà chúng hỗ trợ.
| Loại điểm cuối Fitbit Web API | Google Health API |
| GET (Log | Summary | Daily Summary) khi bạn yêu cầu một ngày dữ liệu | phương thức dailyRollup với windowSize = 1 ngày |
| GET (Trong ngày) khi bạn yêu cầu dữ liệu chi tiết | Phương thức list |
| GET (Chuỗi thời gian) theo Ngày hoặc Khoảng thời gian | Phương thức rollUp hoặc dailyRollUp bao gồm một phạm vi ngày |
| GET (Danh sách nhật ký) | Phương thức list |
| TẠO VÀ CẬP NHẬT Nhật ký | Phương thức patch |
| XOÁ Nhật ký | Phương thức batchDelete |
| Lấy hồ sơ | users.getProfile trả về thông tin cụ thể của người dùng
users.getSettings trả về đơn vị và múi giờ của người dùng |
| CẬP NHẬT Hồ sơ | users.updateProfile sửa đổi thông tin cụ thể của người dùng
users.updateSettings sửa đổi đơn vị và múi giờ của người dùng |
| Lấy mã nhận dạng người dùng | users.getIdentity trả về mã nhận dạng người dùng Fitbit cũ và mã nhận dạng người dùng Google. |
Di chuyển người dùng
Việc di chuyển từ Fitbit Web API sang Google Health API không chỉ là một bản cập nhật kỹ thuật. Người dùng phải đồng ý lại với chế độ tích hợp mới của bạn do bạn thay đổi thư viện OAuth. Không thể chuyển mã truy cập và mã làm mới sang API Google Health và hoạt động. Để hỗ trợ việc giữ chân người dùng trong quá trình di chuyển, sau đây là một số đề xuất về kỹ thuật và chiến lược để di chuyển thành công.
Chiến lược sử dụng hai thư viện
Vì Fitbit Web API và Google Health API sử dụng các thư viện OAuth2 khác nhau, nên bạn phải quản lý một khoảng thời gian "kết nối" trong đó cả hai thư viện đều tồn tại trong cơ sở mã của bạn.
Quản lý uỷ quyền song song
- Đóng gói các ứng dụng: Tạo một lớp hoặc giao diện trừu tượng cho "Dịch vụ y tế". Điều này cho phép phần còn lại của ứng dụng yêu cầu dữ liệu mà không cần biết thư viện nào (Fitbit OAuth so với Google OAuth) đang hoạt động cho người dùng cụ thể đó.
- Cập nhật giản đồ cơ sở dữ liệu: Cập nhật bảng người dùng để thêm cờ
oauth_type. Ví dụ: sử dụngfitbitcho Fitbit OAuth vàgooglecho Google OAuth.- Người dùng mới: Mặc định là Google Health API và thư viện Google OAuth. Đặt
oauth_typethànhgoogle. - Người dùng hiện tại: Tiếp tục sử dụng Fitbit Web API cho đến khi họ hoàn tất quy trình đồng ý lại. Đặt
oauth_typethànhfitbit.
- Người dùng mới: Mặc định là Google Health API và thư viện Google OAuth. Đặt
Quy trình đồng ý lại "từng bước"
Thay vì buộc người dùng đăng xuất, hãy sử dụng phương pháp uỷ quyền gia tăng:
- Phát hiện mã thông báo nguồn mở của Fitbit: Khi người dùng Fitbit Web API mở ứng dụng, hãy kích hoạt thông báo "Cập nhật dịch vụ".
- Khởi chạy quy trình OAuth của Google: Khi người dùng nhấp vào "Cập nhật", hãy bắt đầu quy trình thư viện OAuth2 của Google.
- Thay thế và thu hồi: Sau khi nhận được mã thông báo Google OAuth, hãy lưu mã thông báo đó vào hồ sơ người dùng, cập nhật
oauth_typetừfitbitthànhgooglevà (nếu có thể) thu hồi mã thông báofitbitcũ theo phương thức lập trình để giữ cho hồ sơ bảo mật của người dùng luôn sạch sẽ.
Tối đa hoá tỷ lệ giữ chân người dùng
Việc yêu cầu người dùng đồng ý lại là "vùng nguy hiểm" đối với tình trạng rời bỏ. Để ngăn người dùng rời bỏ ứng dụng, hãy làm theo các phương pháp hay nhất về trải nghiệm người dùng sau đây:
Thông tin liên lạc "Đặt giá trị lên hàng đầu"
Đừng bắt đầu bằng câu "Chúng tôi đã cập nhật API của mình". Hãy nêu bật những lợi ích của hệ thống mới do Google hỗ trợ:
- Bảo mật nâng cao: Đề cập đến khả năng bảo vệ tài khoản đầu ngành của Google và tính năng xác thực 2 yếu tố.
- Độ tin cậy: Thời gian đồng bộ hoá nhanh hơn và kết nối dữ liệu ổn định hơn.
- Phân phối có chọn lọc: Nhẹ nhàng thông báo cho người dùng rằng các tính năng và loại dữ liệu mới yêu cầu họ cập nhật.
Thời gian thông minh
- Không làm gián đoạn các tác vụ có giá trị cao: Đừng bao giờ kích hoạt màn hình yêu cầu đồng ý lại khi người dùng đang tập luyện hoặc ghi nhật ký thực phẩm.
- Giai đoạn "Nhắc nhở": Trong 30 ngày đầu tiên, hãy sử dụng một biểu ngữ có thể đóng.
- Giai đoạn "Ngừng hỗ trợ hoàn toàn": Chỉ bắt buộc người dùng đồng ý lại sau vài tuần cảnh báo, trùng với thời hạn ngừng hỗ trợ chính thức của Fitbit Web API.
So sánh quy trình di chuyển
Sự khác biệt rõ ràng về mặt hình ảnh giữa quy trình cũ và quy trình mới giúp nhà phát triển hiểu được nơi phân nhánh logic.
| Tính năng | Fitbit Web API (Phiên bản cũ) | Google Health API (Google-Identity) |
| Thư viện xác thực | Nguồn mở tiêu chuẩn | Dịch vụ nhận dạng của Google (GIS) / Google Auth |
| Tài khoản Người dùng | Thông tin đăng nhập cũ của Fitbit | Tài khoản Google |
| Loại mã thông báo | Quyền truy cập / làm mới dành riêng cho Fitbit | Mã truy cập/Mã làm mới do Google phát hành |
| Quản lý phạm vi | Quyền truy cập rộng | Quyền chi tiết / Quyền gia tăng |
Xử lý sắc thái của việc di chuyển tài khoản
Theo tài liệu của Fitbit, người dùng di chuyển tài khoản sang Google thường không mất ngay các mối kết nối với bên thứ ba, nhưng việc thay đổi phiên bản API là một yêu cầu về phía nhà phát triển.
- Kiểm tra tính hợp lệ của mã thông báo: Sử dụng backgroundworker để kiểm tra xem mã thông báo Fitbit có gặp lỗi "Không được phép" hay không. Điều này có thể cho thấy người dùng đã di chuyển tài khoản của họ nhưng ứng dụng của bạn chưa bắt kịp.
- Lỗi duyên dáng: Nếu lệnh gọi Fitbit OAuth không thành công, hãy chuyển hướng người dùng đến trang "Kết nối lại Fitbit" tuỳ chỉnh, trong đó sử dụng cụ thể quy trình Google OAuth mới.
Ví dụ về mã
Để di chuyển từ Fitbit Web API cũ sang Google Health API, bạn sẽ chuyển từ các thư viện OAuth2 chung sang Thư viện xác thực của Google. Sau đây là một đề xuất về cấu trúc và một cách triển khai mã giả được viết bằng JavaScript để xử lý trạng thái "Thư viện kép" này.
1. "Middleware Switch" (Công tắc phần mềm trung gian)
Vì bạn không thể di chuyển tất cả người dùng cùng một lúc, nên phần phụ trợ của bạn cần xác định thư viện nào sẽ sử dụng dựa trên apiVersion hiện tại của người dùng được lưu trữ trong cơ sở dữ liệu của bạn.
Triển khai
const { OAuth2Client } = require('google-auth-library');
const FitbitV1Strategy = require('fitbit-oauth2-library').Strategy;
// 1. Initialize the Google Health API Client
const GHAClient = new OAuth2Client(
process.env.GOOGLE_CLIENT_ID,
process.env.GOOGLE_CLIENT_SECRET,
process.env.REDIRECT_URI
);
// 2. Create a Unified Fetcher
async function fetchSteps(user) {
if (user.apiVersion === 4) {
// ---- GOOGLE OAUTH LIBRARY LOGIC ----
GHAClient.setCredentials({ refresh_token: user.refreshToken });
const url = 'GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints';
const res = await GHAClient.request({ url });
return res.data;
} else {
// ---- FITBIT WEB API LEGACY LOGIC ----
// Use your existing Fitbit open-source library logic here
return callLegacyV1Api(user.accessToken);
}
}
2. Di chuyển quy trình trải nghiệm người dùng
Để tối đa hoá tỷ lệ giữ chân, hãy sử dụng mẫu "Làm gián đoạn và nâng cấp". Điều này đảm bảo người dùng không bị buộc phải đăng nhập lại cho đến khi họ đã tương tác với ứng dụng.
Logic chuyển hướng
Khi người dùng Fitbit Web API sử dụng một tính năng cụ thể, hãy kích hoạt quy trình di chuyển:
app.get('/dashboard', async (req, res) => {
const user = await db.users.find(req.user.id);
if (user.apiVersion === 1) {
// Render a "soft" migration page explaining the Google transition
return res.render('migrate-to-google', {
title: "Keep your data syncing",
message: "Fitbit is moving to Google accounts. Re-connect now to stay updated."
});
}
const data = await fetchSteps(user);
res.render('dashboard', { data });
});
3. Các bước chuyển đổi kỹ thuật chính
Khi viết tập lệnh di chuyển JavaScript, hãy lưu ý những điểm khác biệt sau:
| Tính năng | Fitbit Web API (Phiên bản cũ) | Google Health API (Google-Identity) |
| Điểm cuối mã thông báo | https://api.fitbit.com/oauth2/token | https://oauth2.googleapis.com/token |
| Thư viện xác thực | Nguồn mở tiêu chuẩn | Google Auth |
| Phạm vi | hoạt động | https://www.googleapis.com/auth/googlehealth.activity_and_fitness |
| User ID | Mã nhận dạng được mã hoá của Fitbit được trả về trong phản hồi /oauth2/token | Mã nhận dạng người dùng được trả về từ điểm cuối users.getIdentity |
4. Danh sách kiểm tra việc lưu giữ
- Tính năng duy trì phiên: Đừng xoá phiên API Fitbit Web cũ của người dùng cho đến khi access_token của Google Health API được xác minh thành công và lưu vào cơ sở dữ liệu của bạn.
- Tự động thu hồi: Sau khi quá trình di chuyển API Google Health hoàn tất, hãy sử dụng yêu cầu POST đến điểm cuối thu hồi Fitbit cũ: https://api.fitbit.com/oauth2/revoke. Điều này đảm bảo người dùng không thấy các quyền cho ứng dụng "trùng lặp" trong phần cài đặt Fitbit.
- Xử lý lỗi: Nếu một lệnh gọi Fitbit trả về trạng thái 401 Unauthorized (Không được phép), hãy tự động chuyển hướng đến quy trình Google OAuth thay vì hiển thị thông báo lỗi.