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

Để trả về các trường chính xác bạn cần và cải thiện hiệu suất, hãy sử dụng 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 được truy vấn. Ví dụ: files.get chỉ có thể trả về id, name và mimeType cho Tài nguyên files. Chiến lược phát hành đĩa đơn Phương thức permissions.get trả về một tập hợp các trường mặc định khác nhau cho Tài nguyên permissions.

Sau khi máy chủ xử lý yêu cầu hợp lệ bao gồm truy vấn fields nó sẽ gửi lại mã trạng thái HTTP 200 OK cùng với mã trạng thái đượ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ì giá trị máy chủ trả về một mã trạng thái HTTP 400 Bad Request kèm theo một lỗi cho biết có lỗi gì trong việc lựa chọn trường của bạn. Ví dụ: files.list(fields='files(id,capabilities,canAddChildren)') tạo ra lỗi "Có thể chọn trường không hợp lệ cho trẻ." 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 mà bạn có thể trả về bằng cách sử dụng tham số fields, hãy truy cập vào của tài nguyên mà bạn đang truy vấn. Ví dụ: để xem 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 thông số trường

Định dạng của giá trị thông số yêu cầu của trường được thoải mái dựa trên Tên của bạn. Sau đây là các quy tắc định dạng cho tham số fields. Toàn bộ các quy tắc này sử dụng các ví dụ liên quan đến phương thức files.get.

  • Hãy 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 lồng ghép .

  • 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 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 trường lựa chọn. Ví dụ: 'permissions/permissionDetails/*' chọn tất 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ể gây ảnh hưở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 ta 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 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 được lồng

Khi một trường tham chiếu đến một tài nguyên khác, bạn có thể chỉ định các trường nào của tài nguyên 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 permissions tài nguyên, hãy sử dụng bất kỳ tuỳ chọn nào sau đây:

  • permissions.get cho thành viên fields=role hoặc fields=*.
  • files.get cho thành viên fields=permissions(role) hoặc fields=permissions/role.
  • files.get có fields=permissions để ngụ ý tất cả các trường của phần tử lồng nhau nguồn.
  • changes.list cho thành viên 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 cho thành viên 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 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"
    }
  ]
}