Tài liệu này bao gồm 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, các ví dụ từ các API khác hoặc API chung được dùng để minh hoạ các ý tưởng trình bày. Tuy nhiên, các khái niệm tương tự cũng áp dụng cho API Google Trang trình bày.
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 tính năng nén gzip. Mặc dù điều này yêu cầu thêm thời gian của CPU để giải nén kết quả, nhưng sự đánh đổi với chi phí mạng thường làm cho rất đáng giá.
Để nhận phản hồi được mã hoá 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ề tiêu đề HTTP được định dạng đúng để bật tính 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 cho lệnh gọi API là chỉ yêu cầu phần dữ liệu mà bạn quan tâm. Điều này cho phép ứng dụng của bạn tránh được việc truyề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ể sử dụng tài nguyên như mạng, CPU và bộ nhớ một cách hiệu quả hơn.
Phản hồi một phần
Theo mặc định, máy chủ sẽ gửi lại bản trình bày đầy đủ của một tài nguyên sau khi xử lý các yêu cầu. Để cải thiện hiệu suất, bạn có thể yêu cầu máy chủ chỉ gửi những trường mà bạn thực sự cần và nhận một phần phản hồi.
Để 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 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.
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 (hư cấu).
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 đủ tài nguyên: Dữ liệu đầy đủ về tài nguyên bao gồm các trường sau đây cùng với nhiều trường khác đã bị bỏ qua để 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 cho 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 phản hồi chỉ chứa thông tin loại cùng với một mảng mục được phân tích cú pháp chỉ bao gồm thông tin đặc trưng về độ dài và tiêu đề HTML 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à các đối tượng mẹ trong đó.
Tiếp theo là thông tin chi tiết về cách định dạng thông số fields
, tiếp theo là thông tin chi tiết hơn về nội dung được trả về chính xác trong phản hồi.
Tóm tắt cú pháp thông số trường
Định dạng của giá trị tham số yêu cầu fields
là thoải mái dựa trên cú pháp CUE. Cú pháp được hỗ trợ được tóm tắt bên dưới và ví dụ bổ sung đượ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 trườngb
lồng trong trườnga
; sử dụnga/b/c
để chọn trườngc
lồng trongb
.
Ngoại lệ: Đối với các phản hồi API sử dụng trình bao bọc "dữ liệu", trong đó phản hồi được lồng vào một đối tượng
data
trông giống nhưdata: { ... }
, không bao gồm "data
" trong thông số kỹ thuậtfields
. Việc bao gồm đối tượng dữ liệu có thông số kỹ thuật cho các trường nhưdata/a/b
sẽ gây ra lỗi. Thay vào đó, bạn chỉ cần sử dụng quy cáchfields
nhưa/b
. - Sử dụng một bộ chọn phụ để yêu cầu một tập hợp các trường phụ hoặc mảng cụ thể bằng cách đặt các 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 mặt hàng. 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ả đố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ụ bên dưới bao gồm mô tả về cách giá trị tham số fields
ảnh hưởng đế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 được mã hóa URL. Để dễ đọc hơn, các ví dụ trong tài liệu này sẽ bỏ qua việc mã hoá.
- Xác định các trường bạn muốn trả về hoặc chọn trường.
- Giá trị tham số yêu cầu
fields
là 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 danh sách, thì phản hồi sẽ là một tập hợp và thường bao gồm một loạt tài nguyên. Nếu bạn đang thực hiện một thao tác trả về một tài nguyên, các trường đượ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 đã 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ử) nhưng không trả về trường nào khác. etag,items
Trả về cả trường etag
và tất 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ẹ trong đó. Các trường mẹ không bao gồm bất kỳ trường con nào khác trừ khi các trường đó cũng được chọn rõ ràng.context/facets/label
Chỉ trả về trường label
cho tất cả các thành phần của mảngfacets
. Lớp này tự lồng nhau 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 tất cả các đối tượng 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 tất cả các đối tượng là phần tử con củalinks
. - Chỉ yêu cầu một số phần của trường cụ thể bằng cách sử dụng tính năng 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 một phản hồi chỉ bao gồm một số trường phụ. 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ụ bên dưới.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ý các phản hồi một phần
Sau khi xử lý một 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
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 về sự cố đã chọn trong các trường (ví dụ: "Invalid field selection a/b"
).
Dưới đây là ví dụ về một phần phản hồi hiển thị trong phần giới thiệu ở trên. Yêu cầu này sử dụng tham số fields
để chỉ định trường nào cần trả về.
https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)
Câu trả lờ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ợ các 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 thành kích thước có thể quản lý. Nếu không, hiệu suất có thể đạt được nếu phản hồi một phần có thể không nhận ra.