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

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

Tài liệu này giải thích cách sử dụng tham số fields trong Google Drive.

Cách hoạt động của tham số fields

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à một 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ế hay để đả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.

Nếu bạn không chỉ định tham số fields, thì máy chủ sẽ trả về một nhóm trường mặc định dành riêng cho phương thức này. Ví dụ: phương thức list trên phương thức files chỉ trả về các trường kind, id, name và mimeType. Phương thức get trên tài nguyên permissions sẽ trả về một nhóm trường mặc định khác.

Đối với tất cả các phương thức của tài nguyên about, comments (ngoại trừ delete) và replies (ngoại trừ delete), bạn phải đặt tham số fields. Các phương thức này không trả về một tập hợp mặc định gồm các trường.

Sau khi xử lý một yêu cầu hợp lệ có chứa 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 tham số fields có lỗi hoặc không hợp lệ, thì máy chủ sẽ trả về mã trạng thái HTTP 400 Bad Request, cùng với một thông báo lỗi cho biết vấn đề với lựa chọn trường của bạn. Ví dụ: files.list(fields='files(id,capabilities,canAddChildren)') sẽ tạo ra lỗi "Invalid field selection 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 vào trang tài liệu của tài nguyên mà bạn đang truy vấn. Ví dụ: để biết 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. Để biết thêm các cụm từ tìm kiếm dành riêng cho tệp, hãy xem phần Cụm từ và toán tử tìm kiếm.

Quy tắc định dạng 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. 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 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 được 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 một 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 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ụ: 'permissions(id)' chỉ trả về mã nhận dạng quyền cho từng 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 lựa chọn trường. Ví dụ: 'permissions/permissionDetails/*' chọn tất cả các trường thông tin 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.

Yêu cầu

Trong ví dụ này, chúng tôi cung cấp tham số đường dẫn mã nhận dạng 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 này trả về các giá trị trường cho mã nhận dạng 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 một 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 nào của tài nguyên lồng nhau cần được 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 dùng một trong các lựa chọn sau:

  • permissions.get với fields=role.
  • permissions.get có fields=* để hiện tất cả các trường permissions.
  • files.get với fields=permissions(role) hoặc fields=permissions/role.
  • files.get có fields=permissions để hiện 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 một 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).

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 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 này trả về các giá trị trường cho mã nhận dạng 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"
    }
  ]
}