Tài liệu này trình bày các điểm quan trọng cần cân nhắc 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.
Chỉ định tên tệp và đuôi tệp
Ứng dụng nên 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ụ: một 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 được điền bằng tiện ích đượ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 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 các tài liệu để tìm kiếm khi nhận ra loại tệp, bao gồm cả tài liệu văn bản, PDF, hình ảnh có văn bản và các loại tệp 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 được 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 sẽ đượ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ì "Đây là một số văn bản" sẽ được lập chỉ mục, nhưng "giá trị1" 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 như việc lưu HTML.
Khi chỉ định indexableText, cũng xin lưu ý:
- Giới hạn kích thước cho
contentHints.indexableTextlà 128 KB. - Nắm bắt những từ khoá và khái niệm chính mà bạn muốn người dùng 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 với mỗi lần lưu.
- Đảm bảo văn bản 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ừ được tìm kiếm phổ biến để buộc tệp xuất hiện trong kết quả tìm kiếm. Điều này có thể gây khó chịu cho người dùng và thậm chí có thể 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 các tệp trên Drive 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ỏ 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 URL và hình ảnh được mã hoá base64 an toàn cho tên tệp (xem phần RFC 4648 5). - Đặ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ỏ bạn có thể đã tải lên. Nếu không thể tạo hình thu nhỏ, thì mô-đun này 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ể được 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 phải cập nhật các thông tin này sau mỗi lần 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 tệp trên Drive.
Thông tin về hình thu nhỏ được nằm 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 mà bạn muốn tìm.
Nếu có, yêu cầu sẽ trả về một URL ngắn hạn cho hình thu nhỏ của tệp.
Thông thường, đường liên kết này sẽ tồn tại trong vài giờ. Trường này chỉ được điề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 xác thực.
Trả về danh sách hình thu nhỏ
Mã mẫu sau đây cho thấy một yêu cầu phương thức files.list 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 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)
Để hạn chế kết quả tìm kiếm ở một loại tệp cụ thể, hãy áp dụng 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 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 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)