Điểm cuối

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

Quy ước về API REST

Google Health API tuân theo các tiêu chuẩn Đề 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 ánh xạ từ một thông báo giao thức sang 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 cá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ạ đến một tham số truy vấn.
  • Phù hợp nhất với: Các loại đơn giản (chuỗi, số nguyên, enum) và các trường lặp lại.

Ví dụ về cú pháp:

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 dùng khi dữ liệu sửa đổi trạng thái của một tài nguyên hoặc có kích thước quá lớn đối với một URL. Nội dung thường là một biểu diễn JSON của chính tài nguyên đó. Thường được dùng cho các thao tác POST, PATCH và PUT.

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

Ví dụ về cú pháp:

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"
}

Hộp sạc 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à một tham số truy vấn (thường là update_mask) chỉ định những 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ổng quan 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 Được dùng cho các thao tác tìm kiếm, lọc và đọc. Được dùng cho các thao tác ghi.
Chế độ hiển thị Xuất hiện trong nhật ký trình duyệt và nhật ký máy chủ. Bị ẩn khỏi URL.
Độ phức tạp Chỉ giới hạn ở các cấu trúc phẳng hoặc lặp lại. Hỗ trợ các đối tượng JSON lồng nhau.
Mã hoá Phải được mã hoá URL (ví dụ: khoảng trắng sẽ trở thành %20). Mã hoá JSON tiêu chuẩn.

Ngày

Tất cả ngày tháng trong Google Health API đều được hiển thị ở đị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 áp dụng các quy định hạn chế về ngày bắt đầu theo tiêu chuẩn ISO-8601 hoặc các thời đại 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 phù hợp. Bạn nên 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 một chỉ mục về các tác vụ thường gặp của Google Health API và ví dụ về từng tác 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. Để lấy mã nhận dạng người dùng, hãy gọi điểm cuối getIdentity. getIdentity trả về cả mã nhận dạng người dùng cũ của Fitbit và mã nhận dạng người dùng của Google.

Bạn nên gọi điểm cuối getIdentity và lưu trữ cả hai mã nhận dạng người dùng ngay khi người dùng mới đồng ý thông qua OAuth. Điều này giúp bạn có khả năng tương thích ngược và tương thích xuôi trong quá trình tích hợp.

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

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

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 list điểm cuối cho một loại dữ liệu cụ thể để nhận 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"
}

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

Sử dụng điểm cuối list với tham số filter để lọc dữ liệu theo thời gian dân sự hoặc một 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 của một mẫu quan sát

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

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/2515055256096816351/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 dữ liệu theo nguồn dữ liệu, chẳng hạn như thiết bị đeo

Sử dụng reconcile điểm cuối để lấy dữ liệu theo "nhóm nguồn dữ liệu" trong một luồng được đối chiếu.

Dưới đây là ví dụ về cách lọc chỉ giấc ngủ được thiết bị theo dõi ghi lại cho ngày sau 2026-03-03:

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 khoảng thời gian

Sử dụng điểm cuối rollUp để trả về tổng 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, trong phạm vi datetime dựa trên thời gian thực của người dùng (theo giờ UTC).

Khi gọi điểm cuối rollUp, bạn phải cung cấp phần nội dung yêu cầu đại diện cho phạm vi ngày bắt buộc theo giờ dân sự của người dùng. Ví dụ:

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-02-17T17:00:00Z",
    "endTime": "2026-02-17T17:59:59Z"
  },
  "windowSize": "30s"
}

Phản hồi

{
  "rollupDataPoints": [
    {
      "startTime": "2026-02-17T17:55:00Z",
      "endTime": "2026-02-17T17:55:30Z",
      "steps": {
        "countSum": "41"
      }
    },
    {
      "startTime": "2026-02-17T17:54:00Z",
      "endTime": "2026-02-17T17:54:30Z",
      "steps": {
        "countSum": "31"
      }
    },
...
  ]
}

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

Bạn nên sử dụng dailyRollUpđiểm cuối khi muốn tổng hợp dữ liệu trong một hoặc nhiều ngày, còn gọi là windowSize. Cung cấp khoảng thời gian dân sự khép kín 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, bạn sẽ nhận được tổng hoặc giá trị trung bình trong khoảng thời gian đó.

Ví dụ:

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": 2,
        "day": 26
      },
      "time": {
        "hours": 0,
        "minutes": 0,
        "seconds": 0,
        "nanos": 0
      }
    },
    "end": {
      "date": {
        "year": 2026,
        "month": 2,
        "day": 26
      },
      "time": {
        "hours": 23,
        "minutes": 59,
        "seconds": 59,
        "nanos": 0
      }
    }
  },
  "windowSizeDays": 1
}

Phản hồi

{
  "rollupDataPoints": [
    {
      "civilStartTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {}
      },
      "civilEndTime": {
        "date": {
          "year": 2026,
          "month": 2,
          "day": 26
        },
        "time": {
          "hours": 23,
          "minutes": 59,
          "seconds": 59
        }
      },
      "steps": {
        "countSum": "3822"
      }
    }
  ]
}

Chèn hoặc cập nhật dữ liệu sức khoẻ của người dùng

Sử dụng điểm cuối patch để chèn hoặc cập nhật dữ liệu ứng dụng Fitbit của người dùng.

Sau đây là ví dụ về trường hợp người dùng ghi lại 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-length: 329

{
  "name": "bodyFatName",
  "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/2515055256096816351/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
    }
  }
}

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

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

Sau đây là ví dụ về trường hợp người dùng đã từ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/2515055256096816351/dataTypes/body-fat/dataPoints/1234567890"
  ]
}

Phản hồi

{
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.devicesandservices.health.v4main.BatchDeleteDataPointsResponse"
  }
}
Trước
Thư viện ứng dụng
Tiếp
Đường liên kết phổ quát và đường liên kết đến ứng dụng