Để 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ườngb
lồng trong trườnga
, 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ớifields=role
hoặcfields=*
.files.get
vớifields=permissions(role)
hoặcfields=permissions/role
.files.get
vớifields=permissions
để ngụ ý tất cả các trường của tài nguyên lồng nhau.changes.list
bằngfields=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" } ] }