API Google Drive cho phép bạn tải dữ liệu tệp lên khi bạn tạo hoặc cập nhật
File
. Để biết thông tin về cách tạo
tệp chỉ có siêu dữ liệu, chẳng hạn như thư mục, hãy xem Tạo tệp chỉ siêu dữ liệu.
Có ba kiểu tải lên mà bạn có thể thực hiệ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 đa phương tiệ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 tải lên đơn giản, hãy tham khảo Thực hiện 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ả trong một yêu cầu duy nhất. Để tải nhiều phần lên, hãy tham khảo phần Thực hiện tải nhiều phần lên.Tải lên tiếp nối (
uploadType=resumable
): Sử dụng loại tệp 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 mạng gián đoạn, chẳng hạn như khi tạo tệp từ ứng dụng di động. Có thể tiếp tục tải lên cũng là lựa chọn tốt cho hầu hết các ứng dụng vì chúng 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ượt 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 quy trình tải lên tiếp nối tải lên.
Thư viện ứng dụng API của Google triển khai ít nhất một trong các loại video tải lên. Tham khảo thư viện ứng dụng tài liệu này để biết thêm thông tin chi tiết về cách và sử dụng từng loại.
Sử dụng PATCH
so với PUT
Hãy ôn lại kiến thức, độ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ể đưa ra các thay đổi có thể gây lỗi khi thêm 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 sử dụng 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 một lượt tải lên tiếp nối hoặc cho yêu cầu duy nhất của một lượt 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 đối với quá trình tải lên tiếp nối sau khi đã bắt đầu. Các yêu cầu này đang tải nội dung lên bất kể đang được gọi.
Thực hiện việc tải lên đơn giản
Để thực hiện một tệp 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 truy vấn tham số củauploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Thêm dữ liệu của tệp vào 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 nghe nhìn MIME của đối tượng đang được đã tải lên.Content-Length
. Đặt thành số byte bạn tải lên. Nếu bạn sử dụng mã hoá chuyển phân đoạn, 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 tải một tệp 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
được suy ra từ tệp, chẳng hạn như loại MIME hay modifiedTime
. Bạn có thể sử dụng
để tải lên một cách đơn giản trong trường hợp bạn có các tệp nhỏ và siêu dữ liệu của tệp không phải
rất 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 lên siêu dữ liệu và dữ liệu trong cùng một yêu cầu của bạn. Sử dụng tùy chọn này nếu dữ liệu bạn gửi đủ nhỏ để tải lên lại, nếu không kết nối được.
Để tải lên nhiều phần, hãy sử dụng phương thức
Phương thức files.create
với
uploadType=multipart
.
Sau đây là ví dụ về cách tải nhiều phần lên:
Java
Python
Node.js
PHP
.NET
HTTP
Tạo một yêu cầu
POST
đến URI /upload của phương thức bằng truy vấn tham số củauploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Tạo phần nội dung của yêu cầu. Định dạng nội dung theo loại nội dung nhiều phần/có liên quan RFC 2387, trong đó có hai phần:
- Siêu dữ liệu. Siêu dữ liệu phải xuất hiện trước và phải có
Content-Type
được đặt tiêu đề 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.
Hãy xác định từng phần bằng một chuỗi ranh giới, đứng sau hai dấu gạch nối. Ngang bằng 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 xuất hiện trước và phải có
Thêm các tiêu đề HTTP cấp cao nhất sau đây:
Content-Type
. Đặt thànhmultipart/related
và bao gồm ranh giới mà bạn đang sử dụng để xác định các phần khác nhau của yêu cầu. Cho ví dụ:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Đặt thành tổng số byte trong nội dung 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 có dữ liệu liên quan,
gửi yêu cầu POST
hoặc PATCH
đến điểm cuối 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.
Khi tạo tệp, họ nên chỉ định đuôi tệp trong name
của tệp
. Ví dụ: khi tạo một tệp ảnh JPEG, bạn có thể chỉ định một số thông tin
như "name": "photo.jpg"
trong siêu dữ liệu. Các lệnh gọi tiếp theo tới 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
.
Thực hiện quá trình tải lên tiếp nối
Quy trình tải lên tiếp nối giúp bạn tiếp tục hoạt động tải lên sau khi kết nối làm gián đoạn luồng dữ liệu. Vì bạn không phải khởi động lại trên quy mô lớn tải tệp lên ngay từ đầu, quá trình tải lên tiếp nối cũng có thể làm giảm băng thông của bạn nếu có lỗi 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 đối với các yêu cầu (chẳng hạn như các tác vụ trong 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 cho khi bạn 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 quá trình tải lên.
Gửi yêu cầu ban đầu
Để bắt đầu quá trình 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 một yêu cầu
POST
đến URI /upload của phương thức bằng truy vấn tham số củauploadType=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ột
200 OK
Mã trạng thái HTTP. Ngoài ra, đoạn mã này còn có một 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 phần 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 tệp và dữ liệu sẽ được chuyể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, đối tượng được cung cấp dưới dạngapplication/octet-stream.
X-Upload-Content-Length
. Không bắt buộc. Đặt thành số byte của và dữ liệu tệp sẽ được chuyể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 phân đoạn. Đặt thành số byte trong phần 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 bao gồm mã trạng thái
200 OK HTTP
. Ngoài ra, câu trả lời 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 tục để 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 có phiên hoạt động có thể tiếp tục lên:
- Tải nội dung lên trong một yêu cầu duy nhất: Sử dụng phương pháp này khi tệp có thể được tải 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ỳ hoặc bạn không cần hiển thị chỉ báo tiến trình tải lên. Chiến dịch này là phương pháp hiệu quả nhất vì cần ít yêu cầu hơn và mang lại kết quả tốt hơn hiệu suất.
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 bất kỳ yêu cầu nào. Có thể bạn cần để giảm dữ liệu được chuyển khi có giới hạn thời gian cố định cho mỗi người dùng các yêu cầu, như trường hợp đối với một số lớp 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 để hiển thị tiến trình tải lên.
HTTP – yêu cầu duy nhất
- 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 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 bài viết 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 phân đoạn vào nội dung yêu cầu. Tạo phân đoạn theo bội số của Kích thước 256 KB (256 x 1024 byte), ngoại trừ đoạn cuối cùng đã hoàn thành phần tải lên. Giữ kích thước phân đoạn lớn nhất có thể để tệp tải lên một cách hiệu quả.
Thêm các tiêu đề HTTP sau:
Content-Length
. Đặt thành số byte trong phân đoạn hiện tại.Content-Range
. Đặt để hiển thị số byte trong tệp bạn tải lên. Cho Ví dụ:Content-Range: bytes 0-524287/2000000
cho biết rằng bạn tải 524.288 byte đầu tiên (256 x 1024 x 2) trong tệp 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 là 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 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 đoạn vẫn còn trong tệp. Sử dụng Tiêu đề
Range
trong phản hồi để xác định vị trí bắt đầu phân đoạn tiếp theo. Đừng giả định rằng máy chủ đã nhận được tất cả các 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 một 200 OK
hoặc
Phản hồi 201 Created
, cùng với mọi siêu dữ liệu 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 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 phương thức URI phiên có thể tiếp tục.Thêm tiêu đề
Content-Range
để cho biết rằng vị trí hiện tại trong tệp không xác định. Ví dụ: đặtContent-Range
thành*/2000000
nếu tổng chiều dài tệp là 2.000.000 byte. Nếu bạn không biết kích thước đầy đủ của 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 tệp tải lên đã đã hoàn tất và không cần thực hiện thêm hành động nào. - Phản hồi
308 Resume Incomplete
cho biết rằng bạn phải tiếp tục để tải tệp lên. - Phản hồi của
404 Not Found
cho biết phiên tải lên đã hết hạn và phải bắt đầu lại quá trình tải lên 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 các byte mà máy chủ đã nhận được. Nếu phản hồi không có tiêu đềRange
, chưa nhận được byte nào. Ví dụ: tiêu đềRange
củabytes=0-42
cho biết rằng URL đầu tiên Đã nhận được 43 byte của tệp và đoạn tiếp theo sẽ tải lên sẽ bắt đầu bằng byte 44.Giờ bạn đã biết vị trí bắt đầu tải lên, hãy tiếp tục tải tệp lên bắt đầu với byte tiếp theo. Bao gồm Tiêu đề
Content-Range
để cho biết phần nào của tệp mà bạn gửi. Cho Ví dụ:Content-Range: bytes 43-1999999
cho biết rằng 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 bạn 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
5xx
lỗi, hãy tiếp tục hoặc thử tải lên lại nhưng không tải lên được do kết nối gián đoạn. Để biết thêm thông tin về cách xử lý lỗi5xx
, hãy tham khảo Lỗi 500, 502, 503, 504. - Đối với
403 rate limit
lỗi, hãy thử tải lên lại. Để biết thêm thông tin về đang xử lý403 rate limit
lỗi, hãy tham khảo 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 tiếp nối, hãy khởi động lại phần tải lên. Các lỗi này cho biết phiên tải lên đã hết hạn và bạn phải đã khởi động lại bằng cách yêu cầu một URI phiên mới. Tải phiên lên cũng sẽ hết hạn sau một tuần không hoạt động.
Nhập các loại 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 thành một loại tệp của Google Workspace, chẳng hạn như tệp Google Tài liệu hoặc Trang tính. Ví dụ: có thể bạn muốn chuyển đổi tài liệu từ trình xử lý văn bản mà mình yêu thích vào Tài liệu để tận dụng các tính năng AI mới.
Để chuyển đổi một tệp thành một loại tệp cụ thể trong Google Workspace, hãy chỉ định phương thức
mimeType
của Google Workspace khi tạo tệp.
Phần sau đây trình bày cách chuyển đổi tệp CSV thành trang tính trên Google Workspace:
Java
Python
Node.js
PHP
.NET
Để xem có lượt chuyển đổi nào 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ố hành vi phổ biến
định dạng nhập là:
Từ | Đến |
---|---|
Microsoft Word, OpenDocument Text, 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 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 được thay thế.
Khi bạn chuyển đổi hình ảnh sang Tài liệu, Drive sẽ sử dụ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 thuật toán OCR bằng cách chỉ định BCP (BCP) thích hợp
47 mã ngôn ngữ
trong phần
ocrLanguage
. Văn bản được trích xuất sẽ xuất hiện trong Tài liệu cùng với hình ảnh được nhúng.
Sử dụng mã nhận dạng được tạo trước để tải tệp lên
API Drive cho phép bạn truy xuất danh sách mã nhận dạng tệp được tạo trước
được dùng để tải lên và tạo tài nguyên. Yêu cầu tải lên và tạo tệp có thể
sử dụng các mã nhận dạng được tạo trước này. Đặt trường id
trong siêu dữ liệu tệp.
Để tạo mã nhận dạng được tạo trước, hãy gọi
files.generateIds
bằng
số lượng mã nhận dạng cần tạo.
Bạn có thể yên tâm thử tải lên lại bằng mã nhận dạng được tạo trước nếu có giá trị không xác định
lỗi máy chủ hoặc lỗi thời gian chờ. Nếu tệp được tạo thành công,
Các lần thử lại sẽ trả về lỗi HTTP 409
và không tạo ra 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à fullText
để tìm kiếm nội dung từ ứng dụng của bạn. Để 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 loại tệp, bao gồm tài liệu văn bản, 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ẽ,
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.
Để 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ý tệp siêu dữ liệu.