Trả về các trường cụ thể cho tệp

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

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

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ột 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 của trường 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 thông báo lỗi cho biết đã xảy ra sự cố với lựa chọn trường của bạn. Ví dụ: files.list(fields='files(id,capabilities,canAddChildren)') trả về lỗi "Chọn trường không hợp lệ canAddChildren". Tham số truy vấn 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 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ụ: để xem những trường mà 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 các trường yêu cầu giá trị tham số thường dựa trên cú pháp XPath. Dưới đâ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'.

  • 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 tài nguyên lồng nhau.

  • Sử dụng một trình 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 các 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 này có thể tác động tiêu cực đến hiệu suất đối với yêu cầu.

Hiển thị ví dụ

Yêu cầu

Trong ví dụ này, chúng tôi 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 này trả về các giá trị của 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 sẽ đượ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 sử dụng tuỳ chọn bất kỳ sau đây:

  • permissions.get với fields=role hoặc fields=*.
  • files.get với fields=permissions(role) hoặc fields=permissions/role.
  • files.get với fields=permissions để ngụ ý tất cả các trường của tài nguyên lồng nhau.
  • changes.list bằng 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 tôi cung cấp tham số đường dẫn mã 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 được lồ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ị của 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"
    }
  ]
}