Điểm cuối

Trang này cung cấp thông tin tổng quan về các quy ước của API REST, cùng với danh mục các tác vụ phổ biến của API Google Health và ví dụ về từng tác vụ.

Quy ước API REST

API Google Health tuân theo các tiêu chuẩn của Đề xuất cải tiến API của Google (AIP), cụ thể là AIP-127 (Chuyển mã HTTP và gRPC) và AIP-131 đến AIP-135 (Phương thức chuẩn). Các tiêu chuẩn này xác định cách dữ liệu được liên kết từ một thông báo proto đến một yêu cầu HTTP.

Tham số truy vấn

Tham số truy vấn được dùng khi dữ liệu là một phần của URL. Điều này chủ yếu dành cho các yêu cầu GET (tìm nạp tài nguyên) hoặc yêu cầu LIST (lọc/phân trang), nhưng cũng được dùng cho các thao tác DELETE.

  • Vị trí: Được thêm vào URL sau dấu ?.
  • Cú pháp: Các cặp khoá-giá trị được phân tách bằng &.
  • Ánh xạ: Mọi trường trong thông báo yêu cầu không thuộc mẫu đường dẫn URL đều được ánh xạ tới một tham số truy vấn.
  • Phù hợp nhất cho: Các loại đơn giản (chuỗi, số nguyên, enum) và trường lặp lại.

Để biết danh sách chi tiết về các định dạng bộ lọc, thông tin tham khảo về trường, quy tắc xác thực và ví dụ, hãy xem Hướng dẫn lọc dữ liệu.

Cú pháp ví dụ:

GET https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints?page_size=10&filter=data_type.interval.start_time >= "2025-10-01T00:00:00Z"

Nội dung yêu cầu

Nội dung yêu cầu được sử dụng khi dữ liệu sửa đổi trạng thái của tài nguyên hoặc quá lớn đối với một URL. Nội dung thường là một bản trình bày JSON của chính tài nguyên đó. Thường dùng cho các thao tác POST, PATCH và PUT.

  • Vị trí: Bên trong tải trọng HTTP (không hiển thị trong URL).
  • Cú pháp: Được định dạng dưới dạng đối tượng JSON.
  • Ánh xạ: Được xác định trong chú thích google.api.http.
    • body: "*" có nghĩa là toàn bộ thư là nội dung.
    • body: "resource_name" có nghĩa là chỉ một trường cụ thể trong proto là nội dung.
  • Phù hợp nhất cho: Đối tượng phức tạp, thông báo lồng nhau và dữ liệu nhạy cảm.

Để biết hướng dẫn chi tiết về kích thước cửa sổ tổng hợp, quy tắc phân nhóm và ví dụ về dữ liệu tổng hợp, hãy xem Hướng dẫn về dữ liệu tổng hợp.

Cú pháp ví dụ:

POST https://health.googleapis.com/v4/users/me/dataTypes/data-type/dataPoints:rollUp
Content-Type: application/json

{
  "range": {
    "startTime": "2025-11-05T00:00:00Z",
    "endTime": "2025-11-13T00:00:00Z"
  },
  "windowSize": "3600s"
}

Trường hợp kết hợp

Trong phương thức Update tuân thủ AIP-134 hoặc thao tác PATCH, cả hai đều được sử dụng. URL chứa tên tài nguyên, phần nội dung chứa dữ liệu tài nguyên đã cập nhật và tham số truy vấn (thường là update_mask) chỉ định các trường cần thay đổi.

PATCH https://health.googleapis.com/v4/projects/project-id/subscribers/subscriber-id
Content-Type: application/json

{
  "endpointUri": "https://myapp.com/new-webhooks/health"
}

Tóm tắt về những điểm khác biệt chính

Tính năng Tham số truy vấn Nội dung yêu cầu
Hướng dẫn về AIP Dùng cho các thao tác tìm kiếm, lọc và đọc. Dùng cho các thao tác ghi.
Chế độ hiển thị Xuất hiện trong nhật ký duyệt web và nhật ký máy chủ. Đã ẩn khỏi URL.
Độ phức tạp Giới hạn ở cấu trúc phẳng hoặc lặp lại. Hỗ trợ các đối tượng JSON lồng nhau sâu.
Mã hoá Phải được mã hoá URL (ví dụ: dấu cách trở thành %20). Mã hoá JSON chuẩn.

Ngày

Tất cả ngày trong Google Health API đều được hiển thị theo định dạng YYYY-MM-DD. Nutrition API hỗ trợ tiêu chuẩn ISO-8601 cho các giá trị ngày với các điều kiện sau:

  • Năm có 4 chữ số YYYY
  • Giá trị năm trong khoảng từ 0000 đến 9999
  • Không thực thi các quy định hạn chế về ngày bắt đầu theo tiêu chuẩn ISO-8601 hoặc kỷ nguyên khác

Tiêu đề

Để thực thi các điểm cuối của Google Health API, bạn cần sử dụng tiêu đề và mã truy cập thích hợp. Bạn nên sử dụng tiêu đề sau cho cả yêu cầu GET và POST:

Authorization: Bearer access-token
Accept: application/json

Chỉ mục tác vụ API

Phần này cung cấp danh mục các nhiệm vụ phổ biến của Google Health API và ví dụ về từng nhiệm vụ.

Lấy mã nhận dạng người dùng Fitbit hoặc Google

Sau khi người dùng đồng ý thông qua Google OAuth 2.0, phản hồi mã thông báo sẽ không chứa mã nhận dạng người dùng Fitbit hoặc Google. Gọi điểm cuối getIdentity ngay sau khi trao đổi mã uỷ quyền để truy xuất cả legacyUserId và healthUserId, đồng thời xác minh rằng Tài khoản Google của người dùng đã được liên kết với Google Health. Nếu tài khoản chưa được liên kết, getIdentity sẽ trả về 400 Bad Request kèm theo lý do ACCOUNT_NOT_LINKED (xem phần Xử lý Tài khoản Google chưa liên kết).

Ví dụ:

Yêu cầu

GET https://health.googleapis.com/v4/users/me/identity
Authorization: Bearer access-token
Accept: application/json

Phản hồi (200 OK)

{
  "name": "users/me/identity",
  "legacyUserId": "A1B2C3",
  "healthUserId": "111111256096816351"
}

Phản hồi (400 ACCOUNT_NOT_LINKED)

{
  "error": {
    "code": 400,
    "message": "The account is not linked to Google Health.",
    "status": "FAILED_PRECONDITION",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "ACCOUNT_NOT_LINKED",
        "domain": "health.googleapis.com",
        "metadata": {
          "redirect_uri": "https://fitbit.google.com/auth/signup"
        }
      }
    ]
  }
}

Nhận dữ liệu trong ngày hoặc dữ liệu chi tiết được thu thập trong suốt một ngày

Sử dụng điểm cuối list cho một loại dữ liệu cụ thể để lấy dữ liệu trong ngày hoặc dữ liệu chi tiết được thu thập trong suốt cả ngày theo các khoảng thời gian được hỗ trợ cho loại dữ liệu đó.

Ví dụ:

Yêu cầu

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints
Authorization: Bearer access-token
Accept: application/json

Phản hồi

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
    },
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuWjx5bmvy98zj85uG34tuMn16mu2pntsnZI32iqhq"
}

Xem dữ liệu khoảng thời gian đã đối chiếu

Để truy xuất dữ liệu khoảng thời gian mà không có bản ghi trùng lặp hoặc xung đột giữa nhiều thiết bị, hãy gọi điểm cuối reconcile. Điểm cuối reconcile tự động loại bỏ các khoảng thời gian trùng lặp giữa các lô đồng bộ hoá và nhiều thiết bị ghi, trả về một luồng dữ liệu liên tục, đáng tin cậy, phù hợp để hiển thị dòng thời gian hoạt động và tính toán thời lượng.

Để biết thông tin cơ bản về lý do các thiết bị thông minh tạo ra các khoảng thời gian trùng lặp và so sánh hoạt động giữa list và reconcile, hãy xem Hướng dẫn quản lý dữ liệu.

Ví dụ sau đây so sánh phản hồi của list (trả về cả hai bản ghi trùng lặp) so với reconcile (giải quyết xung đột bằng cách trả về bản ghi có thẩm quyền) cho một người dùng có hai phiên tập thể dục trùng lặp:

Danh sách thô

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    },
    {
      "name": "users/111111256096816351/dataTypes/exercise/dataPoints/4389052750481144696",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:00:00Z",
          "endTime": "2026-09-03T11:30:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

Đã đối chiếu

GET https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints:reconcile
Authorization: Bearer access-token
Accept: application/json
 
{
  "dataPoints": [
    {
      "dataPointName": "users/111111256096816351/dataTypes/exercise/dataPoints/7797422996486764704",
      "exercise": {
        "interval": {
          "startTime": "2026-09-03T11:20:00Z",
          "endTime": "2026-09-03T11:50:00Z"
        },
        "exerciseType": "RUNNING"
      }
    }
  ]
}

Quá trình điều chỉnh sẽ giải quyết các phiên xung đột bằng cách loại bỏ trùng lặp và chọn bản ghi có thẩm quyền thay vì tổng hợp một liên kết thời gian nhân tạo (chẳng hạn như 11:00:00Z đến 11:50:00Z). Phản hồi đã điều chỉnh sẽ trả về điểm dữ liệu chiến thắng (7797422996486764704) cùng với khoảng thời gian được ghi lại ban đầu (11:20:00Z đến 11:50:00Z), giúp duy trì tính toàn vẹn của dữ liệu đo từ xa và chỉ số đo lường của phiên đó.

Lọc dữ liệu

Để truy xuất các nhóm nhỏ cụ thể của bản ghi điểm dữ liệu khớp với các tiêu chí như khoảng thời gian, ngày hoặc thời gian quan sát, hãy sử dụng điểm cuối list hoặc reconcile có tham số filter.

Để biết hướng dẫn chi tiết, quy tắc định dạng, lỗi xác thực và ví dụ về truy vấn, hãy xem Hướng dẫn lọc dữ liệu.

Lọc theo nhóm nguồn dữ liệu

Để tách riêng hoặc tổng hợp dữ liệu từ các loại nguồn cụ thể (ví dụ: thiết bị đeo thực tế so với mục nhập thủ công), hãy sử dụng tham số dataSourceFamily.

Để biết hướng dẫn chi tiết, các nhóm được hỗ trợ, cũng như ví dụ về yêu cầu và phản hồi cho reconcile, rollUp và dailyRollUp, hãy xem phần Lọc theo nhóm nguồn dữ liệu trong hướng dẫn Lọc dữ liệu.

Lọc dữ liệu theo thời gian bắt đầu theo giờ dân sự của khoảng thời gian

Sử dụng điểm cuối list có tham số filter để lọc dữ liệu theo giờ dân sự hoặc khoảng thời gian.

Ví dụ:

Yêu cầu

GET https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints?filter=steps.interval.civil_start_time >= "2026-03-04T00:00:00"
Authorization: Bearer access-token
Accept: application/json

Phản hồi

{
  "dataPoints": [
    {
      "dataSource": {
        "recordingMethod": "PASSIVELY_MEASURED",
        "device": {
          "manufacturer": "",
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "steps": {
        "interval": {
          "startTime": "2026-03-04T07:05:00Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T07:06:00Z",
          "endUtcOffset": "0s",
          "civilStartTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 5
            }
          },
          "civilEndTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 4
            },
            "time": {
              "hours": 7,
              "minutes": 6
            }
          }
        },
        "count": "40"
      }
...
  ],
  "nextPageToken": "Xm5h-6L0viZxIlRuQjp5bml1bZ4ve2dhNmZvMnt4Yn7qIGQhbHN3YQ"
}

Lọc dữ liệu theo thời gian thực tế của một quan sát mẫu

Sử dụng điểm cuối list có tham số filter để lọc dữ liệu theo thời gian thực tế quan sát mẫu.

Ví dụ:

Yêu cầu

GET https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints?filter=body_fat.sample_time.physical_time >= "2026-03-01T00:00:00Z"
Authorization: Bearer access-token
Accept: application/json

Phản hồi

{
  "dataPoints": [
    {
      "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
      "dataSource": {
        "recordingMethod": "UNKNOWN",
        "application": {
          "packageName": "",
          "webClientId": "",
          "googleWebClientId": "google-web-client-id"
        },
        "platform": "GOOGLE_WEB_API"
      },
      "bodyFat": {
        "sampleTime": {
          "physicalTime": "2026-03-10T10:00:00Z",
          "utcOffset": "0s",
          "civilTime": {
            "date": {
              "year": 2026,
              "month": 3,
              "day": 10
            },
            "time": {
              "hours": 10
            }
          }
        },
        "percentage": 20
      }
    }
  "nextPageToken": ""
}

Lọc và tổng hợp theo nhóm nguồn dữ liệu

Nhóm nguồn dữ liệu là một nhóm logic gồm các nguồn dữ liệu (chẳng hạn như đồng hồ thông minh, ứng dụng di động hoặc mục nhập thủ công). Tính năng này cho phép bạn tách riêng hoặc tổng hợp dữ liệu từ các loại nguồn cụ thể (ví dụ: thiết bị đeo thực tế so với dữ liệu nhập thủ công).

Các điểm cuối reconcile, rollUp và dailyRollUp đều hỗ trợ tham số dataSourceFamily. Cơ chế truyền phụ thuộc vào điểm cuối:

Điểm cuối (phương thức HTTP) Cơ chế
reconcile (GET) Truyền dataSourceFamily dưới dạng tham số truy vấn URL.
rollUp (POST) Truyền dataSourceFamily dưới dạng một trường trong phần nội dung yêu cầu JSON.
dailyRollUp (POST) Truyền dataSourceFamily dưới dạng một trường trong phần nội dung yêu cầu JSON.

Nhóm nguồn dữ liệu được hỗ trợ

Bảng sau đây mô tả các giá trị dataSourceFamily được hỗ trợ:

Phương thức Mô tả
users/me/dataSourceFamilies/all-sources Giá trị mặc định. Trả về các điểm dữ liệu được điều chỉnh trên tất cả các nguồn dữ liệu đã đăng ký của bên thứ nhất (1P) và bên thứ ba (3P). Dữ liệu ứng dụng của bên thứ ba sẽ được trả về khi bạn chọn chế độ này (chẳng hạn như số bước trên đồng hồ thông minh + số bước trên ứng dụng bên thứ ba + số bước trên điện thoại di động + số bước được thêm thủ công).
users/me/dataSourceFamilies/google-wearables Bao gồm dữ liệu do các thiết bị theo dõi của Google và Fitbit ghi lại (chẳng hạn như thiết bị theo dõi đeo được của Fitbit và Pixel Watch). Không bao gồm dữ liệu được ghi lại theo cách thủ công và dữ liệu do điện thoại ước tính. Hãy sử dụng tuỳ chọn này khi quá trình tích hợp yêu cầu dữ liệu đo từ xa thô của cảm biến được ghi lại trực tiếp bằng phần cứng thiết bị đeo.
users/me/dataSourceFamilies/google-sources Bao gồm các nguồn của bên thứ nhất là Google và Fitbit. Dữ liệu này bao gồm hồ sơ trên thiết bị theo dõi thể chất, dữ liệu từ Health Connect và mọi mục nhập thủ công được ghi lại thông qua các ứng dụng của bên thứ nhất (chẳng hạn như ứng dụng Fitbit hoặc Google Fit).

Để nhận luồng dữ liệu đã điều chỉnh từ một nhóm nguồn dữ liệu cụ thể, hãy gọi điểm cuối reconcile bằng tham số truy vấn dataSourceFamily.

Ví dụ: yêu cầu GET sau đây sẽ tìm nạp dữ liệu giấc ngủ do thiết bị theo dõi ghi lại cho ngày sau ngày 3 tháng 3 năm 2026:

Yêu cầu

GET https://health.googleapis.com/v4/users/me/dataTypes/sleep/dataPoints:reconcile?dataSourceFamily=users/me/dataSourceFamilies/google-wearables&filter=sleep.interval.civil_end_time >= "2026-03-03"
Authorization: Bearer access-token
Accept: application/json

Phản hồi

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/sleep/dataPoints/2724123844716220216",
      "dataSource": {
        "recordingMethod": "DERIVED",
        "device": {
          "displayName": "Charge 6"
        },
        "platform": "FITBIT"
      },
      "sleep": {
        "interval": {
          "startTime": "2026-03-03T20:57:30Z",
          "startUtcOffset": "0s",
          "endTime": "2026-03-04T04:41:30Z",
          "endUtcOffset": "0s"
        },
        "type": "STAGES",
        "stages": [
          {
            "startTime": "2026-03-03T20:57:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-03T20:59:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          },
          {
            "startTime": "2026-03-04T04:07:30Z",
            "startUtcOffset": "0s",
            "endTime": "2026-03-04T04:41:30Z",
            "endUtcOffset": "0s",
            "type": "AWAKE",
            "createTime": "2026-03-04T04:43:40.937183Z",
            "updateTime": "2026-03-04T04:43:40.937183Z"
          }
        ],
        "metadata": {
          "stagesStatus": "SUCCEEDED",
          "processed": true,
          "main": true
        },
        "summary": {
          "minutesInSleepPeriod": "464",
          "minutesAfterWakeUp": "0",
          "minutesToFallAsleep": "0",
          "minutesAsleep": "407",
          "minutesAwake": "57",
          "stagesSummary": [
            {
              "type": "AWAKE",
              "minutes": "56",
              "count": "12"
            },
            {
              "type": "LIGHT",
              "minutes": "198",
              "count": "19"
            },
            {
              "type": "DEEP",
              "minutes": "114",
              "count": "10"
            },
            {
              "type": "REM",
              "minutes": "94",
              "count": "4"
            }
          ]
        },
        "createTime": "2026-03-04T04:43:40.337983Z",
        "updateTime": "2026-03-04T04:43:40.937183Z"
      }
    }
  ],
  "nextPageToken": ""
}

Để tổng hợp các điểm dữ liệu trong một kích thước cửa sổ cụ thể bị giới hạn ở một nhóm nguồn dữ liệu cụ thể, hãy gọi điểm cuối rollUp và truyền trường dataSourceFamily trong phần nội dung yêu cầu JSON.

Yêu cầu POST sau đây truy vấn số bước đi bộ trong ngày theo khoảng thời gian hằng giờ (3600s), được tổng hợp riêng từ các thiết bị đeo:

Yêu cầu

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:rollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "startTime": "2026-07-29T00:00:00Z",
    "endTime": "2026-07-29T23:59:59Z"
  },
  "windowSize": "3600s",
  "dataSourceFamily": "users/me/dataSourceFamilies/google-wearables"
}

Phản hồi

{
  "rollupDataPoints": [
    {
      "startTime": "2026-07-29T08:00:00Z",
      "endTime": "2026-07-29T09:00:00Z",
      "steps": {
        "countSum": "1200"
      }
    },
    {
      "startTime": "2026-07-29T09:00:00Z",
      "endTime": "2026-07-29T10:00:00Z",
      "steps": {
        "countSum": "3450"
      }
    }
  ]
}

Để tổng hợp các điểm dữ liệu hằng ngày cho một nhóm nguồn cụ thể, hãy gọi điểm cuối dailyRollUp và truyền trường dataSourceFamily vào nội dung yêu cầu.

Ví dụ: yêu cầu sau đây tính toán số bước hằng ngày của người dùng, bao gồm tất cả các nguồn của bên thứ nhất là Google và Fitbit (thiết bị đeo + mục nhập thủ công):

Yêu cầu

POST https://health.googleapis.com/v4/users/me/dataTypes/steps/dataPoints:dailyRollUp
Authorization: Bearer access-token
Accept: application/json

{
  "range": {
    "start": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 28
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 7,
        "day": 30
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1,
  "dataSourceFamily": "users/me/dataSourceFamilies/google-sources"
}

Phản hồi

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 28
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "8430"
      }
    },
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 7,
          "day": 29
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "11245"
      }
    }
  ]
}

Tổng hợp các điểm dữ liệu trong một khoảng thời gian

Sử dụng điểm cuối rollUp để trả về tập hợp các điểm dữ liệu dựa trên một khoảng thời gian tính bằng giây (windowSize), trong phạm vi datetime theo thời gian thực tế của người dùng (theo giờ UTC).

Khi gọi điểm cuối rollUp, hãy cung cấp nội dung yêu cầu đại diện cho thời gian đóng-mở bắt buộc range và windowSize (ít nhất là "1s"). Để biết hướng dẫn chi tiết về các yêu cầu windowSize, việc điều chỉnh độ phân giải bộ nhớ, quy tắc phân nhóm cũng như các ví dụ về yêu cầu và phản hồi, hãy xem phần Tổng hợp theo khoảng thời gian thực tế trong hướng dẫn dữ liệu tổng hợp.

Tổng hợp dữ liệu trong một ngày hoặc nhiều ngày

Sử dụng điểm cuối dailyRollUp để tổng hợp dữ liệu trong một ngày hoặc nhiều ngày (windowSizeDays). Cung cấp thời gian dân sự đóng-mở range cho khoảng thời gian bắt buộc trong nội dung yêu cầu. Tuỳ thuộc vào loại dữ liệu, điểm cuối sẽ trả về tổng hoặc giá trị trung bình trong mỗi khoảng thời gian.

Để biết thông tin chi tiết về hành vi tổng hợp hằng ngày, cách xử lý giờ dân sự, giới hạn phạm vi cho mỗi yêu cầu, cũng như các ví dụ về yêu cầu và phản hồi, hãy xem phần Tổng hợp theo ngày dương lịch trong hướng dẫn Tổng hợp dữ liệu.

Cập nhật dữ liệu sức khoẻ của người dùng

Sử dụng điểm cuối patch để cập nhật dữ liệu sức khoẻ của người dùng.

Điểm cuối patch cập nhật một bản ghi hiện có dựa trên giá trị nhận dạng được chỉ định trong URL yêu cầu. Cung cấp giá trị nhận dạng của một điểm dữ liệu đã chèn trước đó. API sẽ ghi đè bản ghi hiện có.

Dấu thời gian của khoảng thời gian của một điểm dữ liệu (startTime và endTime) cũng có thể được cập nhật bởi chủ sở hữu bản ghi hoặc được truyền từ các nền tảng ngược dòng như Health Connect. Để biết thông tin chi tiết về khả năng biến đổi dấu thời gian, hãy xem Hướng dẫn quản lý dữ liệu. Để xem ví dụ về cách cập nhật dấu thời gian của khoảng thời gian, hãy xem phần Cập nhật dấu thời gian của khoảng thời gian cho dữ liệu hiện có.

Trường hợp sử dụng giá trị nhận dạng điểm dữ liệu

Giá trị nhận dạng điểm dữ liệu là thông tin cần thiết trong các trường hợp sau:

  • Nội dung cập nhật được nhắm mục tiêu: Để cập nhật một phép đo cụ thể, hãy cung cấp giá trị nhận dạng của phép đo đó trong yêu cầu patch.
  • Xoá: Việc giữ lại giá trị nhận dạng cho phép ứng dụng của bạn xoá bản ghi sau này bằng cách sử dụng điểm cuối batchDelete.

Dưới đây là ví dụ về trường hợp người dùng cập nhật chỉ số lượng mỡ trong cơ thể trên một chiếc cân có tên là "HumanScale" của công ty "Scales R Us". Chỉ số lượng mỡ trong cơ thể mới của người dùng là 20% cho ngày 10/3/2026:

Yêu cầu

PATCH https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints/1234567890
Authorization: Bearer access-token
Content-Type: application/json

{
  "name": "users/me/dataTypes/body-fat/dataPoints/1234567890",
  "dataSource": {
    "recordingMethod": "ACTIVELY_MEASURED",
    "device": {
      "formFactor": "SCALE",
      "manufacturer": "Scales R Us",
      "displayName": "HumanScale"
    }
  },
  "bodyFat": {
    "sampleTime": {
      "physicalTime": "2026-03-10T10:00:00Z"
    },
    "percentage": 20
  }
}

Phản hồi

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.DataPoint",
    "name": "users/123456789/dataTypes/body-fat/dataPoints/1234567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "device": {
        "formFactor": "SCALE",
        "manufacturer": "Scales R Us",
        "displayName": "HumanScale"
      },
      "application": {
        "googleWebClientId": "618308034039.apps.googleusercontent.com"
      },
      "platform": "GOOGLE_WEB_API"
    },
    "bodyFat": {
      "sampleTime": {
        "physicalTime": "2026-03-10T10:00:00Z"
      },
      "percentage": 20
    }
  }
}

Cập nhật dấu thời gian của khoảng thời gian cho dữ liệu hiện có

Để cập nhật dấu thời gian của khoảng thời gian (startTime và endTime trong tải trọng JSON REST hoặc start_time và end_time trong gRPC) của một điểm dữ liệu hiện có, hãy gửi yêu cầu PATCH đến URI tài nguyên của điểm dữ liệu đó. Chỉ người tạo hoặc chủ sở hữu ban đầu của bản ghi mới có thể sửa đổi các trường của bản ghi đó. Ứng dụng không thể chỉnh sửa điểm dữ liệu mà ứng dụng không tạo.

Để biết thông tin cơ bản về khả năng biến đổi dấu thời gian, nội dung cập nhật từ Health Connect và ý nghĩa của việc lưu vào bộ nhớ đệm, hãy xem Hướng dẫn quản lý dữ liệu.

Ví dụ sau đây minh hoạ một ứng dụng của chủ sở hữu đang cập nhật dấu thời gian của khoảng thời gian trong nhật ký uống nước hiện có bằng cách sử dụng điểm cuối patch:

Yêu cầu

PATCH https://health.googleapis.com/v4/users/me/dataTypes/hydration-log/dataPoints/4093039283164890826
Authorization: Bearer access-token
Content-Type: application/json

{
  "hydrationLog": {
    "interval": {
      "startTime": "2026-09-03T10:05:00Z",
      "endTime": "2026-09-03T10:19:59Z"
    },
    "amountConsumed": {
      "milliliters": 350
    }
  }
}

Phản hồi

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/111111256096816351/dataTypes/hydration-log/dataPoints/4093039283164890826",
    "hydrationLog": {
      "interval": {
        "startTime": "2026-09-03T10:05:00Z",
        "endTime": "2026-09-03T10:19:59Z",
        "civilStartTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 5
          }
        },
        "civilEndTime": {
          "date": {
            "year": 2026,
            "month": 9,
            "day": 3
          },
          "time": {
            "hours": 10,
            "minutes": 19,
            "seconds": 59
          }
        }
      },
      "amountConsumed": {
        "milliliters": 350
      }
    }
  }
}

Ghi nhật ký về một món ăn

Để ghi lại một món ăn, hãy gửi yêu cầu POST đến điểm cuối nutrition-log dataPoints. Nội dung yêu cầu chứa một DataPoint có đối tượng nutritionLog. Để biết thêm thông tin, hãy xem Hướng dẫn về dinh dưỡng.

Ví dụ:

Yêu cầu

POST https://health.googleapis.com/v4/users/me/dataTypes/nutrition-log/dataPoints
Authorization: Bearer access-token
Content-Type: application/json

{
  "nutritionLog": {
    "interval": {
      "startTime": "2026-06-16T12:00:00Z",
      "endTime": "2026-06-16T12:30:00Z"
    },
    "foodDisplayName": "Banana",
    "mealType": "LUNCH",
    "energy": {
      "kcal": 105
    },
    "totalCarbohydrate": {
      "grams": 27
    },
    "totalFat": {
      "grams": 0.3
    }
  }
}

Phản hồi

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4.DataPoint",
    "name": "users/123456789/dataTypes/nutrition-log/dataPoints/567890",
    "dataSource": {
      "recordingMethod": "ACTIVELY_MEASURED",
      "platform": "GOOGLE_WEB_API"
    },
    "nutritionLog": {
      "interval": {
        "startTime": "2026-06-16T12:00:00Z",
        "startUtcOffset": "0s",
        "endTime": "2026-06-16T12:30:00Z",
        "endUtcOffset": "0s"
      },
      "energy": {
        "kcal": 105
      },
      "totalCarbohydrate": {
        "grams": 27
      },
      "totalFat": {
        "grams": 0.3
      },
      "mealType": "LUNCH",
      "foodDisplayName": "Banana"
    }
  }
}

Xoá dữ liệu sức khoẻ của người dùng

Sử dụng phương thức batchDelete để xoá một mảng dữ liệu ứng dụng Fitbit của người dùng.

Dưới đây là ví dụ về trường hợp người dùng đã ghi lại lượng mỡ trong cơ thể trên cân, nhưng muốn xoá bản ghi đó. Sử dụng user-id và data-point-id từ thao tác chèn ban đầu:

Yêu cầu

POST https://health.googleapis.com/v4/users/me/dataTypes/body-fat/dataPoints:batchDelete
Authorization: Bearer access-token
Accept: application/json
content-length: 93

{
  "names": [
    "users/123456789/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

Phản hồi

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}

Tìm thông tin thiết bị

Sử dụng điểm cuối list để truy xuất danh sách thiết bị được ghép nối với tài khoản của người dùng. Thông tin này bao gồm thông tin về kiểu máy của thiết bị (deviceVersion) và lần gần nhất thiết bị đồng bộ hoá với ứng dụng di động Google Health (lastSyncTime).

Thông tin về cấu hình và đồng bộ hoá danh sách rất hữu ích cho việc khắc phục sự cố đồng bộ hoá hoặc tìm nạp dữ liệu trong quá khứ kể từ lần đồng bộ hoá gần nhất.

Ví dụ:

Yêu cầu

GET https://health.googleapis.com/v4/users/me/pairedDevices
Authorization: Bearer access-token
Accept: application/json

Phản hồi

{
  "pairedDevices": [
    {
      "name": "users/me/pairedDevices/123456",
      "deviceType": "TRACKER",
      "batteryStatus": "High",
      "batteryLevel": 88,
      "lastSyncTime": "2026-03-04T07:05:00Z",
      "deviceVersion": "Charge 6",
      "macAddress": "00:11:22:33:44:55",
      "features": [
        "STEPS",
        "HEART_RATE"
      ]
    }
  ]
}

Truy vấn dữ liệu trước đây

Một trong những lợi ích cốt lõi của Google Health API là khả năng theo dõi hiệu suất của người dùng và theo dõi các chỉ số sức khoẻ quan trọng của họ trong thời gian dài. Bạn có thể truy vấn dữ liệu của người dùng từ thời điểm dữ liệu đó được ghi lại; API không áp đặt giới hạn hoặc hạn chế nào đối với lượng dữ liệu trong quá khứ mà ứng dụng của bạn có thể sử dụng.

Tuy nhiên, việc truy vấn dữ liệu trong quá khứ vẫn chịu sự điều chỉnh của giới hạn số lượng yêu cầu tiêu chuẩn. Để quản lý độ ổn định của hệ thống và ngăn chặn tải trọng quá mức, API Google Health sử dụng tính năng phân trang tự động với kích thước trang theo điểm cuối cụ thể. Hãy lưu ý các ranh giới và hành vi sau:

  • Tự động phân trang: Nếu bạn truy vấn một khoảng dữ liệu dài, thì API sẽ chỉ trả về trang kết quả đầu tiên cho đến giới hạn kích thước trang của điểm cuối đó, cùng với nextPageToken. Bạn phải sử dụng nextPageToken để yêu cầu các trang tiếp theo.
  • Kích thước trang biến: Giới hạn tối đa phụ thuộc vào điểm cuối và loại dữ liệu. Đối với hầu hết các loại dữ liệu, kích thước trang được giới hạn ở mức tối đa là 10.000. Tuy nhiên, đối với một số loại dữ liệu nhất định như exercise và sleep, kích thước trang mặc định và tối đa được giới hạn ở mức 25. Ví dụ: nếu ứng dụng yêu cầu tất cả dữ liệu giấc ngủ trong 10 năm qua, thì API vẫn chỉ trả về 25 phiên ngủ trên trang đầu tiên.
  • Các quy định hạn chế về phạm vi ngày tổng hợp: Đối với các điểm cuối tổng hợp và hợp nhất dữ liệu (chẳng hạn như rollUp và dailyRollUp), phạm vi ngày truy vấn sẽ bị hạn chế dựa trên loại dữ liệu:
    • Phạm vi tối đa là 14 ngày đối với calories-in-heart-rate-zone, heart-rate, active-minutes và total-calories.
    • Phạm vi tối đa là 90 ngày đối với tất cả các loại dữ liệu tổng hợp khác.

Tuỳ thuộc vào lượng dữ liệu trong quá khứ mà ứng dụng của bạn cần, việc truy xuất toàn bộ tập dữ liệu sẽ yêu cầu phân trang tuần tự. Hãy lưu ý điều này khi thiết kế quy trình đồng bộ hoá dữ liệu của ứng dụng.

Để đảm bảo hiệu suất tối ưu và tránh lỗi API, hãy làm theo các nguyên tắc sau khi truy vấn dữ liệu trong quá khứ:

Đồng bộ hoá dữ liệu theo giai đoạn (tải nóng so với tải nguội)

  • Tải "nóng" ban đầu: Chỉ tìm nạp và kết xuất dữ liệu của 7 đến 14 ngày gần đây nhất trong trình tự tải chính. Điều này đảm bảo người dùng thấy dữ liệu ngay lập tức mà không phải chờ các truy vấn chạy trong thời gian dài.
  • Tải nguội trong nền: Chuyển việc truy xuất dữ liệu trước đây sang một hàng đợi không đồng bộ, có mức độ ưu tiên thấp hơn hoặc tiến trình nền sau khi giao diện người dùng chính được hiển thị.

Phân đoạn truy vấn để tổng hợp

  • Vì các điểm cuối tổng hợp và tổng hợp hằng ngày thực thi giới hạn phạm vi ngày tối đa (14 hoặc 90 ngày tuỳ thuộc vào loại dữ liệu), nên bạn phải chia nhỏ các truy vấn tổng hợp lớn trước đây thành các khoảng thời gian nhỏ hơn, tuần tự trong các giới hạn này.
  • Xử lý hàng loạt hoặc sắp xếp các truy vấn con này một cách an toàn để tuân thủ giới hạn về tính đồng thời và duy trì các chỉ báo tiến trình ổn định trên giao diện người dùng.

Tận dụng các bản tổng hợp được tổng hợp trước

Tái cấu trúc trang tổng quan và biểu đồ xu hướng để sử dụng các điểm cuối tóm tắt, được tổng hợp trước (chẳng hạn như DailyRollUpDataPoints). Việc này sẽ giảm đáng kể mức hao tổn tài nguyên điện toán trên phần phụ trợ và thời gian truyền mạng đến máy khách.

Xử lý lỗi linh hoạt (thử lại thông minh)

  • Triển khai quy trình xử lý thời gian đợi luỹ tuyến nghiêm ngặt khi gặp phải giới hạn tốc độ (429 Too Many Requests) và lỗi hết thời gian chờ cổng máy chủ (504 Gateway Timeout). Đừng bao giờ thử lại ngay lập tức đối với các tải trọng lớn, không thành công. Việc thử lại ngay lập tức sẽ làm tăng tình trạng tắc nghẽn phần phụ trợ và làm trầm trọng thêm tình trạng suy giảm hệ thống.
Trước
Thư viện ứng dụng
Tiếp
Bộ lọc