Tài liệu này trình bày những điểm cần cân nhắc quan trọng khi đặt tên tệp và xử lý 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.
Chỉ định tên và đuôi tệp
Ứng dụng phải chỉ định đuôi tệp trong thuộc tính tiêu đề khi chèn tệp bằng API Google Drive. Ví dụ: thao tác chèn tệp JPEG phải chỉ định một 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ó thể đọc được điền sẵn bằng phần mở rộng ban đầu được chỉ định 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 tên tệp đầy đủ (có đuôi) dựa trên tiêu đề. Trong trường hợp thiếu tiện ích, Drive sẽ cố gắng xác định tiện ích 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 được 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 phát hiện 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" (Đây là một số văn bản) 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, hãy lưu ý những điều sau:
- 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 cho rằng người dùng sẽ tìm kiếm.
- Đừng cố gắng sắp xếp văn bản theo thứ tự 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 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í có thể khiến 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 tệp trên Drive một cách dễ dàng hơn.
Đố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 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 trong 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ỏ, thì ứng dụng 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 đề 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 sẽ cập nhật các giá trị 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 trên 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 một yêu cầu phương thức files.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 bạn muốn tìm.
Nếu có, yêu cầu sẽ trả về một URL ngắn hạn đến hình thu nhỏ của tệp.
Thông thường, đường liên kết này có hiệu lực 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 trả về trong thumbnailLink phải được tìm nạp bằng yêu cầu đã được xác thực.
Trả về danh sách hình thu nhỏ
Mã mẫu sau đây hiển thị yêu cầu phương thức files.list với 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 bài viết Tì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 biết cách giới hạn danh sách ở các tệp Google Trang tính. Để biết thêm thông tin về các loại MIME, hãy xem bài viết 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)