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 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 đượ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 trả về một nhóm 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ệ 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 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. Ví dụ: files.list(fields='files(id,capabilities,canAddChildren)') sẽ dẫn đến 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 những trường bạn có thể trả về bằ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 thông số trường

Định dạng của các giá trị tham số yêu cầu các trường phụ thuộc dựa vào cú pháp CUE. Sau đây là các quy tắc định dạng cho thông 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 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 công cụ chọn phụ để yêu cầu một tập hợp các trường con hoặc đối tượng cụ thể của mả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 thông tin chi tiết về quyền cho mỗi quyền. Xin lưu ý rằng việc sử dụng ký tự đại diện này 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 tôi cung cấp tham số đường dẫn ID 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ị 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 một tài nguyên lồng nhau

Khi một trường đề cập đế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 đượ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 bất kỳ tuỳ chọn nào 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 ID tệp và nhiều trường, bao gồm 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ị 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"
    }
  ]
}