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

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

Để 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 fields tham số hệ thống trong lệnh gọi phương thức.

Để biết thông tin về các tham số hệ thống khác áp dụng cho API Drive, hãy xem Các tham số hệ thống thay thế.

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 gồm các trường mà yêu cầu sẽ trả về. Việc sử dụng mặt nạ trường là một phương pháp thiết kế tốt để đảm bảo rằng bạn không yêu cầu dữ liệu không cần thiết, nhờ đó 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, máy chủ sẽ trả về một tập hợp trường mặc định dành riêng cho phương thức đó. 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 fields. Phương thức get trên tài nguyên permissions trả về một tập hợp 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 trường mặc định.

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 trường mà bạn chọn. Ví dụ: files.list(fields='files(id,capabilities,canAddChildren)') tạo ra lỗi "Invalid field selection canAddChildren." Tham số fields 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 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. Để biết thêm các cụm từ truy vấn dành riêng cho tệp, hãy xem bài viết Cụm từ và toán tử truy vấn 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 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 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 bài viết Tìm nạp các trường của tài nguyên được lồng.

• Sử dụng bộ chọn phụ để yêu cầu một tập hợp 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ã quyền đối với 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.

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

{
  "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 những trường nào của tài nguyên được lồng cần được tìm nạp.

Ví dụ: để truy xuất trường role (tài nguyên được lồng) của tài nguyên permissions, hãy sử dụng một trong các lựa chọn sau:

• 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).

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

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

Các tham số hệ thống thay thế

Các tham số truy vấn áp dụng cho tất cả các thao tác của API Google Drive được ghi lại tại Tham số hệ thống.

Chủ đề có liên quan

• Khắc phục lỗi
• Khắc phục sự cố về xác thực và uỷ quyền
• Cải thiện hiệu suất