Tài liệu này đề cập đến những điểm cần cân nhắc quan trọng khi đặt tên tệp và làm việc với siêu dữ liệu như văn bản có thể lập chỉ mục và hình thu nhỏ. Để chèn và truy xuất tệp, hãy xem
tài nguyên files.
Tổng quan về siêu dữ liệu
Trong API Google Drive, tài nguyên files đại diện cho siêu dữ liệu. Không giống như các API có siêu dữ liệu là đối tượng con, API Drive coi toàn bộ tài nguyên files là siêu dữ liệu. Bạn có thể truy cập trực tiếp vào siêu dữ liệu thông qua các phương thức
get hoặc list trên tài nguyên files.
Theo mặc định, các phương thức get và list chỉ trả về một tập hợp trường một phần. Để
truy xuất dữ liệu cụ thể, bạn phải xác định fields tham số
hệ thống trong
yêu cầu. Nếu bạn bỏ qua, máy chủ sẽ trả về một tập hợp con mặc định của các trường dành riêng cho phương thức. Ví dụ: phương thức list chỉ trả về các trường kind, id, name, mimeType và resourceKey cho mỗi tệp. Để trả về các trường khác, hãy xem phần Trả về các trường cụ thể.
Ngoài ra, khả năng hiển thị siêu dữ liệu còn tuỳ thuộc vào vai trò của người dùng đối với tệp. Tài nguyên
permissions không xác định các hành động được phép của
người dùng đối với một tệp hoặc thư mục. Thay vào đó, tài nguyên files chứa một tập hợp các trường boolean capabilities. API Google Drive lấy các capabilities này từ tài nguyên permissions được liên kết với tệp hoặc thư mục. Để biết thêm thông tin, hãy xem phần Tìm hiểu về các tính năng của tệp.
API Drive cung cấp 2 phạm vi siêu dữ liệu bị hạn chế: drive.metadata
và drive.metadata.readonly. Phạm vi drive.metadata cho phép bạn xem và
quản lý siêu dữ liệu tệp, trong khi drive.metadata.readonly là chỉ đọc. Cả hai đều nghiêm cấm quyền truy cập vào nội dung tệp. Để biết thêm thông tin, hãy xem phần Chọn
phạm vi API Google Drive.
Cuối cùng, hãy luôn xác minh logic của bạn liên quan đến quyền và phạm vi. Ví dụ: người dùng có thể sở hữu một tệp có đầy đủ quyền, nhưng API Drive sẽ chặn các nỗ lực sửa đổi hoặc tải tệp xuống nếu ứng dụng của bạn chỉ có phạm vi drive.metadata.readonly.
Chỉ định tên và đuôi tệp
Các ứng dụng phải chỉ định đuôi tệp trong thuộc tính
name) khi chèn
tệp bằng API Google Drive. Ví dụ: một thao tác chèn tệp JPEG
phải chỉ định nội dung như "name": "cat.jpg" trong siêu dữ liệu.
Các phản hồi GET tiếp theo có thể bao gồm thuộc tính fileExtension chỉ đọc được điền sẵn bằng
đuôi tệp được chỉ định ban đầu trong thuộc tính name. Khi người dùng Google Drive yêu cầu tải một tệp xuống hoặc khi tệp được tải xuống thông qua ứng dụng đồng bộ hoá, Drive sẽ tạo một tên tệp đầy đủ (có đuôi tệp) dựa trên tên. Trong trường hợp thiếu đuôi tệp, Drive sẽ cố gắng xác định đuôi tệp dựa trên loại MIME của tệp.
Lưu văn bản có thể lập chỉ mục
Drive tự động lập chỉ mục tài liệu để tìm kiếm khi nhận dạng loại tệp, bao gồm tài liệu văn bản, tệp PDF, hình ảnh có văn bản và các loại phổ biến khác. Nếu ứng dụng của bạn lưu các loại tệp khác (chẳng hạn như bản vẽ,
video và lối tắt), bạn có thể cải thiện khả năng tìm thấy bằng cách cung cấp
văn bản có thể lập chỉ mục trong trường
contentHints.indexableText
của tệp.
Văn bản có thể lập chỉ mục được lập chỉ mục dưới dạng HTML. Nếu bạn lưu chuỗi văn bản có thể lập chỉ mục
<section attribute="value1">Here's some text</section>, thì "Here's some
text" sẽ được lập chỉ mục, nhưng "value1" thì không. Do đó, việc lưu XML dưới dạng văn bản có thể lập chỉ mục không hữu ích bằng việc lưu HTML.
Khi chỉ định indexableText, bạn cũng cần lưu ý:
- Giới hạn kích thước cho
contentHints.indexableTextlà 128 KB. - Ghi lại các thuật ngữ và khái niệm chính mà bạn dự kiến người dùng sẽ tìm kiếm.
- Đừng cố gắng sắp xếp văn bản theo mức độ quan trọng vì trình lập chỉ mục sẽ thực hiện việc đó một cách hiệu quả cho bạn.
- Ứng dụng của bạn phải cập nhật văn bản có thể lập chỉ mục mỗi khi lưu.
- Đảm bảo văn bản có liên quan đến nội dung hoặc siêu dữ liệu của tệp.
Điểm cuối cùng này có vẻ hiển nhiên, nhưng lại rất quan trọng. Bạn không nên thêm các cụm từ thường được tìm kiếm để buộc một tệp xuất hiện trong kết quả tìm kiếm. Điều này có thể khiến người dùng thất vọng và thậm chí thúc đẩy họ xoá tệp.
Tải hình thu nhỏ lên
Drive tự động tạo hình thu nhỏ cho nhiều loại tệp phổ biến, chẳng hạn như Google Tài liệu, Trang tính và Trang trình bày. Hình thu nhỏ giúp người dùng xác định rõ hơn các tệp trong Drive.
Đối với các loại tệp mà Drive không thể tạo hình thu nhỏ tiêu chuẩn, bạn có thể cung cấp hình ảnh thu nhỏ do ứng dụng của bạn tạo. Trong quá trình tạo hoặc cập nhật tệp, hãy tải hình thu nhỏ lên bằng cách đặt trường
contentHints.thumbnail trên tài nguyên files.
Cụ thể:
- Đặt trường
contentHints.thumbnail.imagethành hình ảnh được mã hoá base64 an toàn với URL và tên tệp (xem mục 5, RFC 4648). - Đặt trường
contentHints.thumbnail.mimeTypethành loại MIME thích hợp cho hình thu nhỏ.
Nếu có thể tạo hình thu nhỏ từ tệp, Drive sẽ sử dụng hình thu nhỏ được tạo tự động và bỏ qua mọi hình thu nhỏ mà bạn có thể đã tải lên. Nếu không thể tạo hình thu nhỏ, Drive sẽ sử dụng hình thu nhỏ mà bạn cung cấp.
Hình thu nhỏ phải tuân thủ các quy tắc sau:
- Có thể tải lên ở định dạng PNG, GIF hoặc JPG.
- Chiều rộng được đề xuất là 1600 pixel.
- Chiều rộng tối thiểu là 220 pixel.
- Kích thước tệp tối đa là 2 MB.
- Ứng dụng của bạn phải cập nhật các hình thu nhỏ này mỗi khi lưu.
Để biết thêm thông tin, hãy xem tài nguyên files.
Truy xuất hình thu nhỏ
Bạn có thể truy xuất siêu dữ liệu, bao gồm cả hình thu nhỏ, cho các tệp trong Drive.
Thông tin về hình thu nhỏ được lưu trữ trong trường
thumbnailLink của
tài nguyên files.
Trả về một hình thu nhỏ cụ thể
Mã mẫu sau đây cho thấy yêu cầu phương thức get có nhiều trường dưới dạng tham số truy vấn để trả về siêu dữ liệu thumbnailLink cho một tệp cụ thể. Để biết thêm thông tin, hãy xem phần Trả về các trường cụ thể
cho một tệp.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
Thay thế FILE_ID bằng fileId của tệp mà bạn muốn
tìm.
Nếu có, yêu cầu sẽ trả về một URL tồn tại trong thời gian ngắn cho hình thu nhỏ của tệp.
Thông thường, đường liên kết này tồn tại trong vài giờ. Trường này chỉ được điền sẵn khi ứng dụng yêu cầu có thể truy cập vào nội dung của tệp. Nếu tệp không được chia sẻ
công khai, thì URL được trả về trong thumbnailLink phải được tìm nạp bằng yêu cầu có
thông tin xác thực.
Trả về danh sách hình thu nhỏ
Mẫu mã sau đây cho thấy yêu cầu phương thức list có nhiều trường dưới dạng tham số truy vấn để trả về siêu dữ liệu thumbnailLink
cho danh sách tệp. Để biết thêm thông tin, hãy xem phần Tìm kiếm tệp và
thư mục.
GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)
Để giới hạn kết quả tìm kiếm trong một loại tệp cụ thể, hãy áp dụng một chuỗi truy vấn để đặt loại MIME. Ví dụ: mã mẫu sau đây cho thấy cách giới hạn danh sách trong các tệp Google Trang tính. Để biết thêm thông tin về các loại MIME, hãy xem Các loại MIME được Google Workspace và Google Drive hỗ trợ.
GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)