Cải thiện hiệu suất

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 vai trò. 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 một trường b được lồng trong trường a; sử dụng a/b/c để chọn trường 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 các 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 một toán tử 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 những 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.