Tài liệu này trình bày một số kỹ thuật 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, chúng tôi sử dụng ví dụ từ các API khác hoặc API chung để minh hoạ các ý tưởng được trình bày. Tuy nhiên, các khái niệm tương tự có thể áp dụng cho API thư viện Google Photos.
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ù việc này yêu cầu thêm thời gian của CPU để giải nén kết quả, nhưng việc đánh đổi chi phí mạng thường rất đáng để thực hiện.
Để nhận được phản hồi được mã hoá bằng gzip, bạn phải thực hiện 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ề các tiêu đề HTTP được định dạng đúng để bật chức năng nén gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
Làm việc với một phần tài nguyên
Một cách khác để cải thiện hiệu suất của lệnh gọi API là chỉ yêu cầu phần dữ liệu mà bạn quan tâm. Việc này cho phép ứng dụng tránh chuyển, phân tích cú pháp và lưu trữ các trường không cần thiết, nhờ đó ứng dụng có thể dùng các tài nguyên như mạng, CPU và bộ nhớ một cách hiệu quả hơn.
Câu trả lờ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 tài nguyên sau khi xử lý các 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 các 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 mà bạn muốn trả về. Bạn có thể 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.
Ví dụ:
Ví dụ sau đây cho thấy việc sử dụng tham số fields
với API "Bản minh hoạ" chung (giả tưởng).
Yêu cầu đơn giản: Yêu cầu HTTP GET
này bỏ qua tham số fields
và trả về toàn bộ tài nguyên.
https://www.googleapis.com/demo/v1
Phản hồi đầy đủ đối với tài nguyên: 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ị loại bỏ vì lý do 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 chính 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 nêu trên, máy chủ 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 items được rút gọn chỉ bao gồm thông tin đặc điểm về tiêu đề HTML và độ dài trong mỗi mục.
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à một đối tượng JSON chỉ bao gồm các trường đã chọn và đối tượng mẹ bao quanh các trường đó.
Tiếp theo, chúng tôi sẽ trình bày thông tin chi tiết về cách định dạng tham số fields
, tiếp theo là thông tin chi tiết về chính xác nội dung được trả về trong phản hồi.
Bản tóm tắt về cú pháp tham số trường
Định dạng của giá trị tham số yêu cầu fields
dựa trên cú pháp XPath. Dưới đây là cú pháp được hỗ trợ và các ví dụ khác được cung cấp trong phần sau.
- Hãy sử dụng danh sách được phân tách bằng dấu phẩy để chọn nhiều trường.
- Dùng
a/b
để chọn một trườngb
lồng trong trườnga
; dùnga/b/c
để chọn một trườngc
lồng trongb
.
Ngoại lệ: Đối với phản hồi API sử dụng trình bao bọc "data", trong đó phản hồi được lồng trong đối tượng
data
trông giống nhưdata: { ... }
, đừng đưa "data
" vào quy cáchfields
. Việc đưa đối tượng dữ liệu vào có thông số kỹ thuật 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ậtfields
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 các 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ụ, trong đófields=items(id)
tương đương vớifields=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ả các đối tượng trong sơ đồ trang.
Các ví dụ khác về cách sử dụng thông số trường
Những ví dụ dưới đây bao gồm nội dung mô tả về mức độ ảnh hưởng của giá trị tham số fields
đến phản hồi.
Lưu ý: Giống như với tất cả cá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ỏ qua bộ mã hoá.
- Xác định các trường bạn muốn trả về hoặc chọn các 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 gốc của phản hồi. Do đó, nếu bạn đang thực hiện thao tác danh sách, 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, thì 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, thì máy chủ sẽ trả về phần đã chọn của tất cả các phần tử trong mảng đó.
Dưới đâ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ừ các trường khác. etag,items
Trả về cả trường etag
và mọi phần tử trong mảng items.items/title
Chỉ trả về trường title
cho mọi 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 quanh. 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 một cách rõ ràng.context/facets/label
Chỉ trả về trường label
cho mọi thành phần của mảngfacets
. Mảng này được lồng trong đối tượngcontext
.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à con củapagemap
.
Dưới đâ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 phụ uri
của đối tượngauthor
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ủalinks
. - Chỉ yêu cầu các phần của các 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 một số 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 một 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 cú pháp lựa chọn phụ "
( )
", 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 xử lý yêu cầu hợp lệ chứa 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
gặp lỗi hoặc không hợp lệ, máy chủ sẽ trả về một 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 đã xảy ra lỗi gì khi chọn trường (ví dụ: "Invalid field selection a/b"
).
Dưới đây là ví dụ về câu trả lời từng phần xuất hiện trong phần giới thiệu ở trên. Yêu cầu này 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 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, mức tăng hiệu suất có thể đạt được với phản hồi một phần có thể không được nhận dạng.