API Google Drive cho phép bạn tải dữ liệu tệp lên khi tạo hoặc cập nhật File
. Để biết thông tin về cách tạo tệp chỉ chứa siêu dữ liệu, chẳng hạn như thư mục, hãy xem phần Tạo tệp chỉ chứa siêu dữ liệu.
Bạn có thể thực hiện 3 loại hoạt động tải lên:
Tải lên đơn giản (
uploadType=media
): Sử dụng loại tải lên này để chuyển tệp nội dung nghe nhìn nhỏ (5 MB trở xuống) mà không cần cung cấp siêu dữ liệu. Để thực hiện một lượt tải lên đơn giản, hãy tham khảo bài viết Thực hiện một lượt tải lên đơn giản.Tải nhiều phần lên (
uploadType=multipart
): "Sử dụng loại tệp tải lên này để chuyển một tệp nhỏ (5 MB trở xuống) cùng với siêu dữ liệu mô tả tệp trong một yêu cầu duy nhất. Để thực hiện tính năng tải lên nhiều phần, hãy tham khảo bài viết Thực hiện tính năng tải lên nhiều phần.Tải lên có thể tiếp tục (
uploadType=resumable
): Sử dụng loại tải lên này cho các tệp lớn (lớn hơn 5 MB) và khi có nhiều khả năng bị gián đoạn mạng, chẳng hạn như khi tạo tệp từ ứng dụng di động. Tính năng tải lên có thể tiếp tục cũng là một lựa chọn phù hợp cho hầu hết các ứng dụng vì tính năng này cũng hoạt động cho các tệp nhỏ với chi phí tối thiểu là một yêu cầu HTTP bổ sung cho mỗi lần tải lên. Để thực hiện quá trình tải lên tiếp nối, hãy tham khảo phần Thực hiện quá trình tải lên tiếp nối.
Thư viện ứng dụng API của Google sẽ triển khai ít nhất một trong các loại tệp tải lên sau đây. Hãy tham khảo tài liệu về thư viện ứng dụng để biết thêm thông tin chi tiết về cách sử dụng từng loại.
Sử dụng PATCH
so với PUT
Để ôn lại, động từ HTTP PATCH
hỗ trợ cập nhật một phần tài nguyên tệp, trong khi động từ HTTP PUT
hỗ trợ thay thế toàn bộ tài nguyên. Lưu ý rằng PUT
có thể tạo ra các thay đổi có thể gây lỗi khi thêm một trường mới vào tài nguyên hiện có.
Khi tải tài nguyên tệp lên, hãy làm theo các nguyên tắc sau:
- Sử dụng động từ HTTP được ghi lại trong tài liệu tham khảo API cho yêu cầu ban đầu của quá trình tải lên tiếp nối hoặc cho yêu cầu duy nhất của một quá trình tải lên đơn giản hoặc nhiều phần.
- Sử dụng
PUT
cho tất cả các yêu cầu tiếp theo để tải lên tiếp tục sau khi yêu cầu bắt đầu. Các yêu cầu này đang tải nội dung lên bất kể phương thức nào được gọi.
Tải lên đơn giản
Để thực hiện một lượt tải lên đơn giản, hãy sử dụng phương thức files.create
với uploadType=media
.
Sau đây là cách thực hiện một tệp tải lên đơn giản:
HTTP
Tạo một yêu cầu
POST
đến URI /upload của phương thức bằng tham số truy vấn làuploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Thêm dữ liệu của tệp vào phần nội dung yêu cầu.
Thêm các tiêu đề HTTP sau:
Content-Type
. Đặt thành loại nội dung đa phương tiện MIME của đối tượng đang được tải lên.Content-Length
. Đặt thành số byte mà bạn tải lên. Nếu bạn sử dụng mã hoá chuyển dữ liệu chia nhỏ, thì tiêu đề này là không bắt buộc.
Gửi yêu cầu. Nếu yêu cầu thành công, máy chủ sẽ trả về mã trạng thái
HTTP 200 OK
cùng với siêu dữ liệu của tệp. {HTTP}
Khi bạn thực hiện một lượt tải lên đơn giản, siêu dữ liệu cơ bản sẽ được tạo và một số thuộc tính sẽ được suy ra từ tệp, chẳng hạn như loại MIME hoặc modifiedTime
. Bạn có thể sử dụng tính năng tải lên đơn giản trong trường hợp có các tệp nhỏ và siêu dữ liệu tệp không quan trọng.
Thực hiện tải lên nhiều phần
Yêu cầu tải lên nhiều phần cho phép bạn tải siêu dữ liệu và dữ liệu lên trong cùng một yêu cầu. Sử dụng tuỳ chọn này nếu dữ liệu bạn gửi đủ nhỏ để tải lên lại (toàn bộ) nếu không kết nối được.
Để tải nhiều phần lên, hãy sử dụng phương thức files.create
với uploadType=multipart
.
Sau đây là cách thực hiện một quá trình tải lên nhiều phần:
Java
Python
Node.js
PHP
.NET
HTTP
Tạo yêu cầu
POST
đến URI /upload của phương thức bằng tham số truy vấnuploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Tạo nội dung của yêu cầu. Định dạng phần nội dung theo loại nội dung nhiều phần/có liên quan RFC 2387, chứa hai phần:
- Siêu dữ liệu. Siêu dữ liệu phải đứng trước và phải có tiêu đề
Content-Type
được đặt thànhapplication/json;
charset=UTF-8
. Thêm siêu dữ liệu của tệp ở định dạng JSON. - Nội dung nghe nhìn. Nội dung nghe nhìn phải đứng thứ hai và phải có tiêu đề
Content-Type
thuộc bất kỳ loại MIME nào. Thêm dữ liệu của tệp vào phần nội dung nghe nhìn.
Xác định từng phần bằng một chuỗi ranh giới, trước đó là hai dấu gạch nối. Ngoài ra, hãy thêm hai dấu gạch nối sau chuỗi ranh giới cuối cùng.
- Siêu dữ liệu. Siêu dữ liệu phải đứng trước và phải có tiêu đề
Thêm các tiêu đề HTTP cấp cao nhất sau:
Content-Type
. Đặt thànhmultipart/related
và chứa chuỗi ranh giới mà bạn sử dụng để xác định các phần của yêu cầu. Ví dụ:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Đặt thành tổng số byte trong nội dung của yêu cầu.
Gửi yêu cầu.
Để chỉ tạo hoặc cập nhật phần siêu dữ liệu mà không phải tải dữ liệu liên kết lên, hãy gửi yêu cầu POST
hoặc PATCH
đến điểm cuối của tài nguyên chuẩn: https://www.googleapis.com/drive/v3/files
Nếu yêu cầu thành công, máy chủ sẽ trả về mã trạng thái HTTP 200 OK
cùng với siêu dữ liệu của tệp.
Khi tạo tệp, bạn phải chỉ định một đuôi tệp trong trường name
của tệp. Ví dụ: khi tạo tệp JPEG ảnh, bạn có thể chỉ định một giá trị như "name": "photo.jpg"
trong siêu dữ liệu. Các lệnh gọi tiếp theo đến files.get
sẽ trả về thuộc tính fileExtension
chỉ có thể đọc chứa tiện ích được chỉ định ban đầu trong trường name
.
Tải lên tiếp nối
Quá trình tải lên tiếp nối cho phép bạn tiếp tục hoạt động tải lên sau khi một sự cố giao tiếp làm gián đoạn luồng dữ liệu. Vì bạn không phải bắt đầu lại quá trình tải lên tệp lớn từ đầu, nên tính năng tải lên có thể tiếp tục cũng có thể làm giảm mức sử dụng băng thông nếu có sự cố mạng.
Tính năng tải lên tiếp nối rất hữu ích khi kích thước tệp của bạn có thể thay đổi đáng kể hoặc khi có giới hạn thời gian cố định cho các yêu cầu (chẳng hạn như các tác vụ ở chế độ nền trên hệ điều hành thiết bị di động và một số yêu cầu nhất định của App Engine). Bạn cũng có thể sử dụng tính năng tải lên tiếp nối trong trường hợp muốn hiển thị thanh tiến trình tải lên.
Quá trình tải lên tiếp nối bao gồm một số bước cấp cao:
- Gửi yêu cầu ban đầu và truy xuất URI phiên có thể tiếp tục.
- Tải dữ liệu lên và theo dõi trạng thái tải lên.
- (không bắt buộc) Nếu quá trình tải lên bị gián đoạn, hãy tiếp tục tải lên.
Gửi yêu cầu ban đầu
Để bắt đầu tải lên tiếp nối, hãy sử dụng phương thức files.create
với uploadType=resumable
.
HTTP
Tạo yêu cầu
POST
đến URI /upload của phương thức bằng tham số truy vấnuploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Nếu yêu cầu khởi tạo thành công, phản hồi sẽ bao gồm mã trạng thái HTTP
200 OK
. Ngoài ra, tệp này còn chứa tiêu đềLocation
chỉ định URI phiên có thể tiếp tục:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Lưu URI phiên có thể tiếp tục để bạn có thể tải dữ liệu tệp lên và truy vấn trạng thái tải lên. URI phiên có thể tiếp tục sẽ hết hạn sau một tuần.
Nếu bạn có siêu dữ liệu cho tệp, hãy thêm siêu dữ liệu vào nội dung yêu cầu ở định dạng JSON. Nếu không, hãy để trống nội dung yêu cầu.
Thêm các tiêu đề HTTP sau:
X-Upload-Content-Type
. Không bắt buộc. Đặt thành loại MIME của dữ liệu tệp được truyền trong các yêu cầu tiếp theo. Nếu loại MIME của dữ liệu không được chỉ định trong siêu dữ liệu hoặc thông qua tiêu đề này, thì đối tượng sẽ được phân phát dưới dạngapplication/octet-stream.
X-Upload-Content-Length
. Không bắt buộc. Đặt thành số byte tương ứng của dữ liệu tệp sẽ được truyền trong các yêu cầu tiếp theo.Content-Type
. Bắt buộc nếu bạn có siêu dữ liệu cho tệp. Đặt thànhapplication/json;
charset=UTF-8
.Content-Length
. Bắt buộc trừ phi bạn sử dụng phương thức mã hoá chuyển dữ liệu chia nhỏ. Đặt thành số byte trong nội dung của yêu cầu ban đầu này.
Gửi yêu cầu. Nếu yêu cầu khởi tạo phiên thành công, phản hồi sẽ bao gồm mã trạng thái
200 OK HTTP
. Ngoài ra, phản hồi còn bao gồm tiêu đềLocation
chỉ định URI phiên có thể tiếp tục. Sử dụng URI phiên có thể tiếp nối để tải dữ liệu tệp lên và truy vấn trạng thái tải lên. URI phiên có thể tiếp tục sẽ hết hạn sau một tuần.Sao chép và lưu URL của phiên hoạt động có thể tiếp tục.
Tiếp tục Tải nội dung lên.
Tải nội dung lên
Có hai cách để tải tệp lên bằng phiên có thể tiếp nối:
- Tải nội dung lên trong một yêu cầu: Sử dụng phương pháp này khi có thể tải tệp lên trong một yêu cầu, nếu không có giới hạn thời gian cố định cho bất kỳ yêu cầu nào hoặc bạn không cần hiển thị chỉ báo tiến trình tải lên. Phương pháp này là tốt nhất vì yêu cầu ít yêu cầu hơn và mang lại hiệu suất tốt hơn.
Tải nội dung lên theo nhiều phần: Sử dụng phương pháp này nếu bạn phải giảm lượng dữ liệu được chuyển trong một yêu cầu bất kỳ. Bạn có thể cần giảm lượng dữ liệu được truyền khi có giới hạn thời gian cố định cho từng yêu cầu riêng lẻ, cũng như đối với một số yêu cầu nhất định của App Engine. Phương pháp này cũng hữu ích nếu bạn phải cung cấp một chỉ báo tuỳ chỉnh để cho thấy tiến trình tải lên.
HTTP – yêu cầu đơn
- Tạo yêu cầu
PUT
đến URI phiên có thể tiếp tục. - Thêm dữ liệu của tệp vào phần nội dung yêu cầu.
- Thêm tiêu đề HTTP có độ dài nội dung, đặt thành số byte trong tệp.
- Gửi yêu cầu. Nếu yêu cầu tải lên bị gián đoạn hoặc nếu bạn nhận được phản hồi
5xx
, hãy làm theo quy trình trong phần Tiếp tục quá trình tải lên bị gián đoạn.
HTTP – nhiều yêu cầu
Tạo yêu cầu
PUT
đến URI phiên có thể tiếp tục.Thêm dữ liệu của đoạn vào phần nội dung yêu cầu. Tạo các phần có kích thước là bội số của 256 KB (256 x 1024 byte), ngoại trừ phần dữ liệu cuối cùng đã hoàn tất thao tác tải lên. Giữ kích thước dữ liệu càng lớn càng tốt để đảm bảo hiệu quả tải lên.
Thêm các tiêu đề HTTP sau:
Content-Length
. Đặt thành số byte trong đoạn hiện tại.Content-Range
. Đặt để hiển thị số byte trong tệp bạn tải lên. Ví dụ:Content-Range: bytes 0-524287/2000000
cho thấy bạn tải 524.288 byte đầu tiên (256 x 1024 x 2) lên trong tệp chứa 2.000.000 byte.
Gửi yêu cầu và xử lý phản hồi. Nếu yêu cầu tải lên bị gián đoạn hoặc nếu bạn nhận được phản hồi
5xx
, hãy làm theo quy trình trong phần Tiếp tục quá trình tải lên bị gián đoạn.Lặp lại các bước từ 1 đến 4 cho từng phần còn lại trong tệp. Sử dụng tiêu đề
Range
trong phản hồi để xác định vị trí bắt đầu phần tiếp theo. Đừng giả định rằng máy chủ đã nhận được toàn bộ số byte đã gửi trong yêu cầu trước đó.
Khi toàn bộ quá trình tải tệp lên hoàn tất, bạn sẽ nhận được phản hồi 200 OK
hoặc 201 Created
, cùng với mọi siêu dữ liệu được liên kết với tài nguyên.
Tiếp tục quá trình tải lên bị gián đoạn
Nếu yêu cầu tải lên bị chấm dứt trước khi nhận được phản hồi, hoặc nếu bạn nhận được phản hồi 503
Service Unavailable
, thì bạn phải tiếp tục quá trình tải lên bị gián đoạn.
HTTP
Để yêu cầu trạng thái tải lên, hãy tạo một yêu cầu
PUT
trống cho URI phiên có thể tiếp tục.Thêm tiêu đề
Content-Range
để cho biết vị trí hiện tại trong tệp là không xác định. Ví dụ: hãy đặtContent-Range
thành*/2000000
nếu tổng chiều dài tệp của bạn là 2.000.000 byte. Nếu bạn không biết kích thước đầy đủ của tệp, hãy đặtContent-Range
thành*/*
.Gửi yêu cầu.
Xử lý phản hồi:
- Phản hồi
200 OK
hoặc201 Created
cho biết quá trình tải lên đã hoàn tất và bạn không cần làm gì thêm. - Phản hồi
308 Resume Incomplete
cho biết bạn phải tiếp tục tải tệp lên. - Phản hồi
404 Not Found
cho biết phiên tải lên đã hết hạn và quá trình tải lên phải được bắt đầu lại từ đầu.
- Phản hồi
Nếu bạn nhận được phản hồi
308 Resume Incomplete
, hãy xử lý tiêu đềRange
của phản hồi để xác định những byte mà máy chủ đã nhận được. Nếu phản hồi không có tiêu đềRange
, thì hệ thống sẽ không nhận được byte nào. Ví dụ: tiêu đềRange
củabytes=0-42
cho biết rằng 43 byte đầu tiên của tệp đã được nhận và đoạn tiếp theo cần tải lên sẽ bắt đầu bằng byte 44.Giờ thì bạn đã biết vị trí để tiếp tục tải lên, hãy tiếp tục tải tệp lên bắt đầu từ byte tiếp theo. Thêm tiêu đề
Content-Range
để cho biết phần nào của tệp bạn gửi. Ví dụ:Content-Range: bytes 43-1999999
cho biết bạn gửi các byte từ 44 đến 2.000.000.
Xử lý lỗi tải nội dung nghe nhìn lên
Khi tải nội dung nghe nhìn lên, hãy làm theo các phương pháp hay nhất sau đây để xử lý lỗi:
- Đối với lỗi
5xx
, hãy tiếp tục hoặc thử tải lại các lần tải không thành công do gián đoạn kết nối. Để biết thêm thông tin về cách xử lý lỗi5xx
, hãy tham khảo bài viết Lỗi 500, 502, 503, 504. - Đối với lỗi
403 rate limit
, hãy thử tải lên lại. Để biết thêm thông tin về cách xử lý lỗi403 rate limit
, hãy tham khảo bài viết Lỗi 403:rateLimitExceeded
. - Đối với mọi lỗi
4xx
(bao gồm cả403
) trong quá trình tải lên có thể tiếp tục, hãy bắt đầu lại quá trình tải lên. Những lỗi này cho biết phiên tải lên đã hết hạn và bạn phải bắt đầu lại bằng cách yêu cầu một URI phiên mới. Các phiên tải lên cũng hết hạn sau một tuần không hoạt động.
Các loại tệp có thể nhập vào Google Tài liệu
Khi tạo một tệp trong Drive, bạn có thể muốn chuyển đổi tệp đó thành một loại tệp Google Workspace, chẳng hạn như Google Tài liệu hoặc Trang tính. Ví dụ: có thể bạn muốn chuyển đổi một tài liệu từ trình xử lý văn bản mà bạn yêu thích sang Tài liệu để tận dụng các tính năng của Tài liệu.
Để chuyển đổi tệp sang một loại tệp Google Workspace cụ thể, hãy chỉ định mimeType
Google Workspace khi tạo tệp.
Sau đây là cách chuyển đổi tệp CSV sang trang tính Google Workspace:
Java
Python
Node.js
PHP
.NET
Để xem có thể chuyển đổi hay không, hãy kiểm tra mảng importFormats
của tài nguyên about
trước khi tạo tệp.
Các lượt chuyển đổi được hỗ trợ sẽ có sẵn một cách linh động trong mảng này. Một số định dạng nhập phổ biến là:
Từ | Đến |
---|---|
Microsoft Word, Văn bản OpenDocument, HTML, RTF, văn bản thuần tuý | Google Tài liệu |
Microsoft Excel, Bảng tính OpenDocument, CSV, TSV, văn bản thuần tuý | Google Trang tính |
Microsoft PowerPoint, Bản trình bày OpenDocument | Google Trang trình bày |
JPEG, PNG, GIF, BMP, PDF | Google Tài liệu (nhúng hình ảnh vào Tài liệu) |
Văn bản thuần tuý (loại MIME đặc biệt), JSON | Google Apps Script |
Khi bạn tải lên và chuyển đổi nội dung nghe nhìn trong một yêu cầu update
thành tệp Tài liệu, Trang tính hoặc Trang trình bày, toàn bộ nội dung của tài liệu sẽ được thay thế.
Khi bạn chuyển đổi hình ảnh sang Tài liệu, Drive sẽ sử dụng tính năng Nhận dạng ký tự quang học (OCR) để chuyển đổi hình ảnh thành văn bản. Bạn có thể cải thiện chất lượng của thuật toán OCR bằng cách chỉ định mã ngôn ngữ BCP 47 hiện hành trong tham số ocrLanguage
. Văn bản đã trích xuất sẽ xuất hiện trong Doc cùng với hình ảnh được nhúng.
Sử dụng mã nhận dạng được tạo sẵn để tải tệp lên
API Drive cho phép bạn truy xuất danh sách mã tệp được tạo sẵn dùng để tải lên và tạo tài nguyên. Các yêu cầu tải lên và tạo tệp có thể dùng những mã nhận dạng được tạo trước này. Đặt trường id
trong siêu dữ liệu của tệp.
Để tạo mã nhận dạng được tạo sẵn, hãy gọi files.generateIds
với số lượng mã nhận dạng cần tạo.
Bạn có thể thử lại việc tải lên một cách an toàn bằng mã nhận dạng được tạo sẵn nếu xảy ra lỗi máy chủ không xác định hoặc hết thời gian chờ. Nếu tệp được tạo thành công, các lần thử lại tiếp theo sẽ trả về lỗi HTTP 409
và không tạo tệp trùng lặp.
Xác định văn bản có thể lập chỉ mục cho các loại tệp không xác định
Người dùng có thể sử dụng giao diện người dùng của Drive để tìm nội dung tài liệu. Bạn cũng có thể sử dụng files.list
và trường fullText
để tìm kiếm nội dung trong ứng dụng. Để biết thêm thông tin, hãy xem phần Tìm kiếm tệp và thư 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.
Để biết thêm thông tin về văn bản có thể lập chỉ mục, hãy xem phần Quản lý siêu dữ liệu của tệp.