Trả về các trường cụ thể

Để trả về chính xác các trường bạn cần và cải thiện hiệu suất, hãy sử dụng thông số hệ thống fields trong lệnh gọi phương thức.

Tham số fields sử dụng FieldMask để lọc phản hồi. Mặt nạ trường được dùng để chỉ định một tập hợp con các trường mà yêu cầu sẽ trả về. Sử dụng mặt nạ trường là một phương pháp thiết kế hiệu quả để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, từ đó giúp tránh thời gian xử lý không cần thiết.

Theo mặc định, máy chủ trả về một tập hợp các trường cụ thể cho tài nguyên đang được truy vấn. Ví dụ: phương thức get() trên tài nguyên files có thể chỉ trả về id, name và mimeType. Phương thức get() trên tài nguyên permissions trả về một nhóm các trường mặc định khác.

Sau khi máy chủ xử lý một yêu cầu hợp lệ bao gồm tham số fields, máy chủ sẽ trả về mã trạng thái HTTP 200 OK cùng với dữ liệu được yêu cầu. Nếu thông số trường 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 biết lỗi xảy ra với lựa chọn trường của bạn. Ví dụ: files.list(fields='files(id,capabilities,canAddChildren)') sẽ trả về lỗi "Lựa chọn trường không hợp lệ canAddChildren". Tham số trường chính xác cho ví dụ này là files.list(fields='files(id,capabilities/canAddChildren)').

Để xác định các trường mà bạn có thể trả về bằng cách sử dụng tham số fields, hãy truy cập trang tài liệu của tài nguyên mà bạn đang truy vấn. Ví dụ: để xem những trường bạn có thể trả về cho một tệp, hãy tham khảo tài liệu về tài nguyên files.

Quy tắc định dạng tham số trường

Định dạng của giá trị tham số yêu cầu trường dựa trên cú pháp XPath. Sau đây là các quy tắc định dạng cho tham số fields. Tất cả các quy tắc này đều sử dụng các ví dụ liên quan đến phương thức files.get().

  • Sử dụng danh sách được phân tách bằng dấu phẩy để chọn nhiều trường, chẳng hạn như 'name, mimeType'.

  • Sử dụng a/b để chọn trường b lồng trong trường a, chẳng hạn như 'capabilities/canDownload'. Để biết thêm thông tin, hãy xem phần Tìm nạp các trường của tài nguyên lồng nhau.

  • Sử dụng bộ chọn phụ để yêu cầu một tập hợp các trường con 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ụ: 'permissions(id)' chỉ trả về mã quyền cho mỗi phần tử trong mảng quyền.

  • Để trả về tất cả các trường trong một đối tượng, hãy sử dụng dấu hoa thị (*) làm ký tự đại diện trong các lựa chọn trường. Ví dụ: 'permissions/permissionDetails/*' chọn tất cả các trường chi tiết về quyền hiện có cho mỗi quyền. Xin lưu ý rằng việc sử dụng ký tự đại diện có thể ảnh hưởng tiêu cực đến hiệu suất của yêu cầu.

Hiển thị ví dụ

Yêu cầu

Trong ví dụ này, chúng ta cung cấp tham số đường dẫn mã tệp và nhiều trường dưới dạng tham số truy vấn trong yêu cầu. Phản hồi trả về các giá trị trường cho mã tệp.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared

Đáp

{
  "name": "File1",
  "starred": false,
  "shared": true
  }
}

Tìm nạp các trường của tài nguyên lồng nhau

Khi một trường tham chiếu đến một tài nguyên khác, bạn có thể chỉ định những trường của tài nguyên lồng nhau cần tìm nạp.

Ví dụ: để truy xuất trường role (tài nguyên lồng nhau) của tài nguyên permissions, hãy sử dụng tuỳ chọn bất kỳ sau đây:

  • permissions.get() với fields=role.
  • permissions.get() với fields=* để hiển thị tất cả các trường permissions.
  • files.get() với fields=permissions(role) hoặc fields=permissions/role.
  • files.get() với fields=permissions để hiển thị tất cả các trường permissions.
  • changes.list() với fields=changes(file(permissions(role))).

Để truy xuất nhiều trường, hãy sử dụng danh sách được phân tách bằng dấu phẩy. Ví dụ: files.list() với fields=files(id,name,createdTime,modifiedTime,size).

Hiển thị ví dụ

Yêu cầu

Trong ví dụ này, chúng ta cung cấp tham số đường dẫn mã nhận dạng tệp và nhiều trường, bao gồm cả một số trường nhất định của tài nguyên quyền lồng nhau dưới dạng tham số truy vấn trong yêu cầu. Phản hồi sẽ trả về các giá trị trường cho mã tệp.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)

Đáp

{
  "name": "File1",
  "starred": false,
  "shared": true,
  "permissions": [
    {
      "kind": "drive#permission",
      "type": "user",
      "role": "owner"
    }
  ]
}