Đ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 chỉ mục các tác vụ phổ biến của API Google Health và ví dụ về từng tác vụ.

Các quy ước của 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 tiêu chuẩn). Các tiêu chuẩn này xác định cách dữ liệu được ánh xạ từ thông báo proto sang 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. Chủ yếu là 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ạ đế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.

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 dùng khi dữ liệu sửa đổi trạng thái của một tài nguyên hoặc quá lớn đối với một URL. Nội dung này 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 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ông báo 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 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.

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

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 dùng. URL chứa tên tài nguyê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 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ề các đ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 của AIP Dùng để tìm kiếm, lọc và đọc các thao tác. Dùng cho các thao tác ghi.
Khả năng hiển thị Hiển thị trong nhật ký trình duyệt và nhật ký máy chủ. Bị ẩn khỏi URL.
Độ phức tạp 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 sâu.
Mã hoá Phải được mã hoá thành URL (ví dụ: dấu cách trở thành %20). Mã hoá JSON tiêu chuẩn.

Ngày

Tất cả ngày trong API Google Health đề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 phạm vi từ 0000 đến 9999
  • Không thực thi các hạn chế về ngày bắt đầu do tiêu chuẩn ISO-8601 hoặc kỷ nguyên khác ngụ ý

Tiêu đề

Để thực thi các điểm cuối của API Google Health, 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 đây 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 chỉ mục các tác vụ phổ biến của API Google Health 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 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 tích hợp của bạn có khả năng tương thích ngược và tương thích tiến.

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

Lấy dữ liệu chi tiết hoặc dữ liệu trong ngày đượ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ể để lấy dữ liệu chi tiết hoặc dữ liệu trong ngày được thu thập trong suốt 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 một 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 tế quan sát mẫu

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ế 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/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 các nguồn dữ liệu như thiết bị đeo

Sử dụng reconcile điểm cuối để lấy dữ liệu theo "họ nguồn dữ liệu" trong một luồng đã đối chiếu.

Dưới đây là ví dụ về cách chỉ lọc giấc ngủ do trình theo dõi ghi lại cho ngày sau ngày 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 rollUp điểm cuối để trả về tổng hợp các điểm dữ liệu dựa trên một cửa sổ tính bằng giây, trong phạm vi datetime dựa trên thời gian thực tế của người dùng (theo UTC).

Khi gọi điểm cuối rollUp, bạn phải cung cấp nội dung yêu cầu đại diện cho phạm vi ngày bắt buộc theo thời gian 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 ngày 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 ngày hoặc nhiều ngày, được gọi là windowSize. Cung cấp phạm vi thời gian dân sự đóng-mở 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 patch điểm cuối để chèn hoặc cập nhật 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 một chiếc cân có tên là "HumanScale" của công ty "Scales R Us". Số đo mới về lượng mỡ trong cơ thể của người dùng là 20% cho ngày 10/03/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 batchDelete điểm cuối để 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 từng ghi lại lượng mỡ trong cơ thể trên một chiếc cân, nhưng họ 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