API Google Fit, bao gồm cả API Google Fit REST, sẽ ngừng hoạt động sau ngày 30 tháng 6 năm 2025. Kể từ ngày 1 tháng 5 năm 2024, nhà phát triển không thể đăng ký sử dụng các API này.

Để biết hướng dẫn về API hoặc nền tảng mà bạn muốn di chuyển sang, hãy truy cập vào Hướng dẫn di chuyển của Health Connect. Để so sánh Health Connect với API Google Fit và API Fitbit Web, hãy xem phần hướng dẫn so sánh Health Connect.

Tìm hiểu thêm về Health Connect và cách tích hợp với API này.

Trang này được dịch bởi Cloud Translation API.

Mẹo tăng hiệu suất

Tài liệu này bao gồm một số kỹ thuật mà bạn có thể sử dụng để cải thiện hiệu suất của ứng dụng. Trong một số trường hợp, ví dụ từ các API khác hoặc API chung được sử dụng để minh hoạ các ý tưởng được trình bày. Tuy nhiên, các khái niệm tương tự cũng có thể áp dụng cho Fitness API.

Nén bằng gzip

Một cách dễ dàng và thuận tiện để giảm băng thông cần thiết cho mỗi yêu cầu là bật chức năng nén gzip. Mặc dù điều này đòi hỏi thêm thời gian của CPU để giải nén kết quả, nhưng việc đánh đổi với chi phí mạng thường khiến việc đánh đổi bằng chi phí mạng thường rất đáng giá.

Để nhận phản hồi được mã hoá bằng gzip, bạn phải làm hai việc: Đặt tiêu đề Accept-Encoding và sửa đổi tác nhân người dùng để chứa chuỗi gzip. Dưới đây là ví dụ về tiêu đề HTTP được định dạng đúng cách để bật nén gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

Xử lý các tài nguyên một phần

Một cách khác để cải thiện hiệu suất của lệnh gọi API là chỉ gửi và nhận phần dữ liệu mà bạn quan tâm. Điều này giúp ứng dụng của bạn tránh được việc chuyển, phân tích cú pháp và lưu trữ các trường không cần thiết để có thể sử dụng các tài nguyên bao gồm mạng, CPU và bộ nhớ một cách hiệu quả hơn.

Có hai loại yêu cầu không hoàn chỉnh:

Phản hồi một phần: Yêu cầu trong đó bạn chỉ định những trường cần đưa vào phản hồi (sử dụng tham số yêu cầu fields).
Bản vá: Yêu cầu cập nhật mà trong đó bạn chỉ gửi các trường mình muốn thay đổi (sử dụng động từ HTTP PATCH).

Bạn có thể xem thêm thông tin chi tiết về việc gửi yêu cầu một phần trong các phần sau.

Phản hồi một phần

Theo mặc định, máy chủ gửi lại bản trình bày đầy đủ của một tài nguyên sau khi xử lý yêu cầu. Để có hiệu suất tốt hơn, bạn có thể yêu cầu máy chủ chỉ gửi những trường bạn thực sự cần và nhận phản hồi một phần.

Để yêu cầu phản hồi một phần, hãy sử dụng tham số yêu cầu fields để chỉ định các trường bạn muốn được trả về. Bạn có thể sử dụng tham số này với bất kỳ yêu cầu nào trả về dữ liệu phản hồi.

Lưu ý rằng tham số fields chỉ ảnh hưởng đến dữ liệu phản hồi; thì dữ liệu đó cũng không ảnh hưởng đến dữ liệu bạn cần gửi (nếu có). Để giảm lượng dữ liệu mà bạn gửi khi sửa đổi tài nguyên, hãy sử dụng yêu cầu bản vá.

Ví dụ:

Ví dụ sau đây cho thấy việc sử dụng tham số fields với một "Bản minh hoạ" chung chung (giả tưởng) API.

Yêu cầu đơn giản: Yêu cầu HTTP GET này sẽ bỏ tham số fields và trả về toàn bộ tài nguyên.

https://www.googleapis.com/demo/v1

Phản hồi tài nguyên đầy đủ: Dữ liệu tài nguyên đầy đủ bao gồm các trường sau, cùng với nhiều trường khác đã bị bỏ qua để cho ngắn gọn.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

Yêu cầu phản hồi một phần: Yêu cầu sau đây cho cùng một tài nguyên này sử dụng tham số fields để giảm đáng kể lượng dữ liệu được trả về.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Phản hồi một phần: Để phản hồi yêu cầu trên, máy chủ sẽ gửi lại một phản hồi chỉ chứa thông tin về loại cùng với một mảng mặt hàng đã rút gọn chỉ bao gồm thông tin về đặc điểm tiêu đề HTML và độ dài trong mỗi mặt hàng.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Lưu ý rằng phản hồi là đối tượng JSON chỉ bao gồm các trường đã chọn và đối tượng mẹ đi kèm các trường đó.

Thông tin chi tiết về cách định dạng tham số fields sẽ được đề cập trong phần tiếp theo, theo sau là thông tin chi tiết về những dữ liệu được trả về chính xác trong phản hồi.

Tóm tắt cú pháp tham số trường

Định dạng của giá trị tham số yêu cầu fields được thoải mái dựa trên cú pháp Tên. Cú pháp được hỗ trợ được tóm tắt bên dưới và ví dụ khác được cung cấp trong phần sau.

Sử dụng danh sách được phân tách bằng dấu phẩy để chọn nhiều trường.
Sử dụng a/b để chọn một trường b được lồng trong trường a; sử dụng a/b/c để chọn trường c được lồng trong b.

Trường hợp ngoại lệ: Đối với các phản hồi của API sử dụng "dữ liệu" trình bao bọc, trong đó phản hồi được lồng trong một đối tượng data có dạng data: { ... }, thì đừng thêm "data" trong quy cách fields. Việc đưa đối tượng dữ liệu vào với thông số của trường như data/a/b sẽ gây ra lỗi. Thay vào đó, chỉ cần sử dụng thông số kỹ thuật fields như a/b.
Sử dụng bộ chọn phụ để yêu cầu một tập hợp các trường phụ cụ thể của mảng hoặc đối tượng bằng cách đặt biểu thức trong dấu ngoặc đơn "( )".
Ví dụ: fields=items(id,author/email) chỉ trả về mã mặt hàng và email của tác giả cho từng phần tử trong mảng items. Bạn cũng có thể chỉ định một trường phụ duy nhất, trong đó fields=items(id) tương đương với fields=items/id.
Sử dụng ký tự đại diện trong các lựa chọn trường, nếu cần.
Ví dụ: fields=items/pagemap/* chọn tất cả đối tượng trong sơ đồ trang.

Ví dụ khác về cách sử dụng thông số trường

Các ví dụ dưới đây bao gồm nội dung mô tả về cách giá trị tham số fields ảnh hưởng đến phản hồi.

Lưu ý: Giống như tất cả giá trị tham số truy vấn, giá trị tham số fields phải là URL được mã hoá. Để dễ đọc hơn, các ví dụ trong tài liệu này sẽ bỏ kiểu mã hoá.

Xác định những trường mà bạn muốn được trả về hoặc chọn trường.

Giá trị tham số yêu cầu fields là một danh sách các trường được phân tách bằng dấu phẩy và mỗi trường được chỉ định tương ứng với thư mục gốc của phản hồi. Do đó, nếu bạn đang thực hiện thao tác list (danh sách), thì phản hồi là một tập hợp và thường bao gồm một mảng tài nguyên. Nếu bạn đang thực hiện thao tác trả về một tài nguyên duy nhất, các trường sẽ được chỉ định tương ứng với tài nguyên đó. Nếu trường bạn chọn là (hoặc là một phần của) một mảng, máy chủ sẽ trả về phần được chọn của tất cả các phần tử trong mảng đó.

Sau đây là một số ví dụ ở cấp bộ sưu tập:

Ví dụ	Hiệu quả
`items`	Trả về tất cả phần tử trong mảng items, bao gồm tất cả các trường trong mỗi phần tử, ngoại trừ tất cả các trường khác.
`etag,items`	Trả về cả trường `etag` và tất cả các phần tử trong mảng items.
`items/title`	Chỉ trả về trường `title` cho tất cả các phần tử trong mảng items. Bất cứ khi nào một trường lồng nhau được trả về, phản hồi sẽ bao gồm các đối tượng mẹ bao gồm. Các trường mẹ không bao gồm bất kỳ trường con nào khác, trừ phi các trường đó cũng được chọn rõ ràng.
`context/facets/label`	Chỉ trả về trường `label` cho mọi thành phần của mảng `facets`. Mảng này được lồng trong đối tượng `context`.
`items/pagemap/*/title`	Đối với mỗi phần tử trong mảng items, chỉ trả về trường `title` (nếu có) của mọi đối tượng là phần tử con của `pagemap`.

Sau đây là một số ví dụ ở cấp tài nguyên:

Ví dụ	Hiệu quả
`title`	Trả về trường `title` của tài nguyên được yêu cầu.
`author/uri`	Trả về trường con `uri` của đối tượng `author` trong tài nguyên được yêu cầu.
`links/*/href`	Trả về trường `href` của mọi đối tượng là con của `links`.

Chỉ yêu cầu các phần của những trường cụ thể bằng cách sử dụng lựa chọn phụ.

Theo mặc định, nếu yêu cầu của bạn chỉ định các trường cụ thể, thì máy chủ sẽ trả về toàn bộ các đối tượng hoặc phần tử mảng. Bạn có thể chỉ định phản hồi chỉ bao gồm một số trường phụ nhất định. Bạn thực hiện việc này bằng cách sử dụng "( )" như trong ví dụ dưới đây.

Ví dụ:	Hiệu quả
`items(title,author/uri)`	Chỉ trả về các giá trị của `title` và `uri` của tác giả cho từng phần tử trong mảng items.

Xử lý phản hồi một phần

Sau khi máy chủ xử lý yêu cầu hợp lệ bao gồm tham số truy vấn fields, máy chủ sẽ gửi lại mã trạng thái HTTP 200 OK cùng với dữ liệu được yêu cầu. Nếu tham số truy vấn fields có lỗi hoặc không hợp lệ, máy chủ sẽ trả về mã trạng thái HTTP 400 Bad Request, cùng với thông báo lỗi cho người dùng biết lựa chọn trường của họ là không đúng (ví dụ: "Invalid field selection a/b").

Sau đây là ví dụ về phản hồi một phần xuất hiện trong phần giới thiệu ở trên. Yêu cầu sử dụng tham số fields để chỉ định những trường cần trả về.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

Phản hồi một phần sẽ có dạng như sau:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

Lưu ý: Đối với các API hỗ trợ tham số truy vấn để phân trang dữ liệu (ví dụ: maxResults và nextPageToken), hãy sử dụng các tham số đó để giảm kết quả của mỗi truy vấn xuống kích thước có thể quản lý. Nếu không, hiệu suất đạt được với phản hồi một phần có thể không được xác định.

Bản vá (cập nhật một phần)

Bạn cũng có thể tránh gửi dữ liệu không cần thiết khi sửa đổi tài nguyên. Để chỉ gửi dữ liệu đã cập nhật cho các trường cụ thể mà bạn đang thay đổi, hãy sử dụng động từ HTTP PATCH. Ngữ nghĩa của bản vá được mô tả trong tài liệu này khác (và đơn giản hơn) so với cách triển khai GData cũ của quá trình cập nhật một phần.

Ví dụ ngắn bên dưới cho thấy cách sử dụng bản vá giảm thiểu dữ liệu bạn cần gửi để thực hiện một bản cập nhật nhỏ.

Ví dụ:

Ví dụ này cho thấy một yêu cầu bản vá đơn giản để chỉ cập nhật tiêu đề của một "Bản minh hoạ" chung chung (giả tưởng) Tài nguyên API. Tài nguyên này cũng có một nhận xét, một tập hợp các đặc điểm, trạng thái và nhiều trường khác, nhưng yêu cầu này chỉ gửi trường title, vì đó là trường duy nhất đang được sửa đổi:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

Phản hồi:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

Máy chủ sẽ trả về một mã trạng thái 200 OK, cùng với thông tin trình bày đầy đủ của tài nguyên đã cập nhật. Vì chỉ có trường title được đưa vào yêu cầu bản vá nên đó là giá trị duy nhất khác với trước đó.

Lưu ý: Nếu sử dụng tham số fields phản hồi một phần kết hợp với bản vá, bạn có thể tăng hiệu quả của các yêu cầu cập nhật hơn nữa. Yêu cầu bản vá chỉ làm giảm dung lượng của yêu cầu. Phản hồi một phần sẽ làm giảm kích thước của phản hồi. Vì vậy, để giảm lượng dữ liệu được gửi theo cả hai hướng, hãy sử dụng yêu cầu bản vá có tham số fields.

Ngữ nghĩa của yêu cầu bản vá

Phần nội dung của yêu cầu bản vá chỉ bao gồm các trường tài nguyên mà bạn muốn sửa đổi. Khi chỉ định một trường, bạn phải bao gồm mọi đối tượng mẹ đi kèm, giống như đối tượng mẹ bao gồm được trả về bằng phản hồi một phần. Dữ liệu sửa đổi mà bạn gửi sẽ được hợp nhất vào dữ liệu cho đối tượng mẹ (nếu có).

Thêm: Để thêm một trường chưa tồn tại, hãy chỉ định trường mới và giá trị của trường đó.
Sửa đổi: Để thay đổi giá trị của một trường hiện có, hãy chỉ định trường và đặt thành giá trị mới.
Xoá: Để xoá một trường, hãy chỉ định trường đó rồi đặt thành null. Ví dụ: "comment": null. Bạn cũng có thể xoá toàn bộ đối tượng (nếu đối tượng đó có thể thay đổi) bằng cách đặt đối tượng đó thành null. Nếu bạn đang sử dụng Thư viện ứng dụng API Java, hãy sử dụng Data.NULL_STRING; với chi tiết, hãy xem giá trị rỗng JSON.

Lưu ý về mảng: Yêu cầu vá lỗi chứa mảng sẽ thay thế mảng hiện có bằng mảng mà bạn cung cấp. Bạn không thể sửa đổi, thêm hoặc xoá các mục trong một mảng theo kiểu từng phần.

Sử dụng bản vá theo chu kỳ đọc-sửa đổi-ghi

Bắt đầu bằng cách truy xuất một phần phản hồi kèm theo dữ liệu bạn muốn sửa đổi có thể là một phương pháp hữu ích. Điều này đặc biệt quan trọng đối với những tài nguyên sử dụng ETag, vì bạn phải cung cấp giá trị ETag hiện tại trong tiêu đề HTTP If-Match để cập nhật tài nguyên thành công. Sau khi nhận được dữ liệu, bạn có thể sửa đổi các giá trị mà mình muốn thay đổi và gửi lại bản trình bày một phần đã sửa đổi cùng với yêu cầu bản vá. Dưới đây là một ví dụ giả định tài nguyên Bản minh hoạ sử dụng ETag:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

Đây là phản hồi một phần:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

Yêu cầu bản vá sau đây dựa trên phản hồi đó. Như hình minh hoạ dưới đây, API này cũng sử dụng tham số fields để giới hạn dữ liệu được trả về trong phản hồi bản vá:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

Máy chủ phản hồi bằng mã trạng thái HTTP 200 OK và biểu thị một phần của tài nguyên đã cập nhật:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

Trực tiếp tạo yêu cầu vá

Đối với một số yêu cầu về bản vá, bạn cần phải dựa vào dữ liệu bạn đã truy xuất trước đó. Ví dụ: nếu bạn muốn thêm một mặt hàng vào mảng và không muốn mất bất kỳ phần tử mảng hiện có nào, trước tiên bạn phải lấy dữ liệu hiện có. Tương tự, nếu một API sử dụng ETag, bạn cần phải gửi giá trị ETag trước đó cùng với yêu cầu của mình để cập nhật tài nguyên thành công.

Lưu ý: Bạn có thể sử dụng tiêu đề HTTP "If-Match: *" để buộc thực hiện bản vá khi ETag đang được sử dụng. Nếu làm như vậy, bạn không cần đọc trước khi ghi.

Tuy nhiên, trong các trường hợp khác, bạn có thể tạo trực tiếp yêu cầu bản vá mà không cần truy xuất dữ liệu hiện có trước. Ví dụ: bạn có thể dễ dàng thiết lập một yêu cầu bản vá để cập nhật một trường thành giá trị mới hoặc thêm một trường mới. Dưới đây là ví dụ:

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

Với yêu cầu này, nếu trường nhận xét hiện có một giá trị, thì giá trị mới sẽ ghi đè giá trị đó; nếu không giá trị sẽ được đặt thành giá trị mới. Tương tự, nếu có một đặc tính âm lượng, thì giá trị của đặc tính đó sẽ bị ghi đè; nếu không thì hệ thống sẽ tạo ra. Trường độ chính xác (nếu có) sẽ bị xoá.

Xử lý phản hồi cho bản vá

Sau khi xử lý yêu cầu bản vá hợp lệ, API này sẽ trả về một mã phản hồi HTTP 200 OK cùng với thông tin đầy đủ về tài nguyên đã sửa đổi. Nếu API sử dụng thẻ ETag, máy chủ sẽ cập nhật các giá trị ETag khi xử lý thành công yêu cầu vá, giống như cách thực hiện với PUT.

Yêu cầu bản vá sẽ trả về toàn bộ thông tin trình bày tài nguyên trừ phi bạn sử dụng tham số fields để giảm lượng dữ liệu mà yêu cầu này trả về.

Nếu yêu cầu vá lỗi dẫn đến trạng thái tài nguyên mới không hợp lệ về cú pháp hoặc về mặt ngữ nghĩa, máy chủ sẽ trả về mã trạng thái HTTP 400 Bad Request hoặc 422 Unprocessable Entity và trạng thái tài nguyên vẫn không thay đổi. Ví dụ: nếu bạn cố gắng xoá giá trị cho một trường bắt buộc, máy chủ sẽ trả về một lỗi.

Ký hiệu thay thế khi động từ PATCH HTTP không được hỗ trợ

Nếu tường lửa của bạn không cho phép các yêu cầu HTTP PATCH, hãy thực hiện một yêu cầu HTTP POST và thiết lập tiêu đề ghi đè thành PATCH, như minh hoạ dưới đây:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

Sự khác biệt giữa bản vá và bản cập nhật

Trên thực tế, khi gửi dữ liệu cho một yêu cầu cập nhật sử dụng động từ HTTP PUT, bạn chỉ cần gửi các trường đó (bắt buộc hoặc không bắt buộc); nếu bạn gửi giá trị cho các trường do máy chủ thiết lập thì các trường đó sẽ bị bỏ qua. Mặc dù đây có vẻ là một cách khác để cập nhật một phần, nhưng phương pháp này vẫn có một số hạn chế. Với các bản cập nhật sử dụng động từ HTTP PUT, yêu cầu sẽ không thành công nếu bạn không cung cấp các tham số bắt buộc, đồng thời sẽ xoá dữ liệu đã đặt trước đó nếu bạn không cung cấp các tham số không bắt buộc.

Vì lý do này, việc sử dụng bản vá sẽ an toàn hơn nhiều. Bạn chỉ cung cấp dữ liệu cho các trường mà bạn muốn thay đổi; mà bạn bỏ qua sẽ không bị xoá. Ngoại lệ duy nhất của quy tắc này xảy ra với các phần tử hoặc mảng lặp lại: Nếu bạn bỏ qua tất cả các phần tử hoặc mảng đó, chúng vẫn giữ nguyên; nếu bạn cung cấp bất kỳ giá trị nào trong số đó, toàn bộ tập hợp sẽ được thay thế bằng tập hợp mà bạn cung cấp.