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 API Google Trang tính.
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ỉ yêu cầu 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.
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.
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ườngb
được lồng trong trườnga
; sử dụnga/b/c
để chọn trườngc
được lồng trongb
.
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ạngdata: { ... }
, thì đừng thêm "data
" trong quy cáchfields
. 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ậ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 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ớ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ụ 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ả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à phần tử con củapagemap
.
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ượ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 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.