Google Drive API memungkinkan Anda mengupload data file saat membuat atau memperbarui
File
Untuk mengetahui informasi tentang cara membuat
file khusus metadata, seperti folder, lihat Membuat file khusus metadata.
Ada tiga jenis upload yang dapat Anda lakukan:
Upload sederhana (
uploadType=media
): Gunakan jenis upload ini untuk mentransfer file media berukuran kecil (5 MB atau kurang) tanpa menyediakan metadata. Untuk melakukan upload sederhana, lihat Melakukan upload sederhana.Upload multibagian (
uploadType=multipart
): "Gunakan jenis upload ini untuk mentransfer file kecil (5 MB atau kurang) bersama dengan {i>metadata<i} yang menjelaskan file, dalam satu permintaan. Untuk melakukan upload multibagian, lihat Melakukan upload multibagian.Upload yang dapat dilanjutkan (
uploadType=resumable
): Gunakan jenis upload ini untuk file besar (lebih dari 5 MB) dan jika ada peluang jaringan gangguan, seperti saat membuat file dari aplikasi seluler. Dapat dilanjutkan upload juga merupakan pilihan bagus bagi sebagian besar aplikasi karena juga berfungsi untuk file kecil dengan biaya minimal satu permintaan HTTP tambahan per upload. Untuk melakukan upload yang dapat dilanjutkan, lihat Melakukan upload yang dapat dilanjutkan upload.
Library klien Google API mengimplementasikan setidaknya satu dari jenis upload video. Lihat pustaka klien untuk detail tambahan tentang cara menggunakan masing-masing jenis.
Gunakan PATCH
vs. PUT
Sebagai penyegaran, kata kerja HTTP PATCH
mendukung update resource file parsial
sedangkan kata kerja HTTP PUT
mendukung penggantian resource sepenuhnya. Perhatikan bahwa PUT
dapat menyebabkan perubahan yang dapat menyebabkan gangguan saat menambahkan isian baru ke resource yang ada.
Saat mengupload resource file, gunakan panduan berikut:
- Gunakan kata kerja HTTP yang didokumentasikan dalam referensi API untuk permintaan awal dari upload yang dapat dilanjutkan atau satu-satunya permintaan upload sederhana atau multibagian.
- Gunakan
PUT
untuk semua permintaan berikutnya bagi upload yang dapat dilanjutkan setelah telah dimulai. Permintaan ini akan mengupload konten, terlepas dari metode yang dipanggil.
Melakukan upload sederhana
Untuk melakukan upload sederhana, gunakan
Metode files.create
dengan
uploadType=media
.
Berikut cara melakukan upload sederhana:
HTTP
Buat permintaan
POST
ke URI /upload metode dengan kueri parameter dariuploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
Tambahkan data file ke isi permintaan.
Tambahkan header HTTP ini:
Content-Type
. Tetapkan ke jenis media MIME objek yang sedang diupload.Content-Length
. Setel ke jumlah byte yang Anda upload. Jika Anda menggunakan potongan encoding transfer, {i>header<i} ini tidak diperlukan.
Kirim permintaan. Jika permintaan berhasil, server menampilkan kode status
HTTP 200 OK
beserta metadata file. {HTTP}
Saat Anda melakukan upload sederhana, metadata dasar akan dibuat dan beberapa atribut
disimpulkan dari file, seperti jenis MIME atau modifiedTime
. Anda dapat menggunakan
upload sederhana jika Anda memiliki file kecil dan metadata file tidak
sangatlah penting.
Melakukan upload multibagian
Dengan permintaan upload multibagian, Anda dapat mengupload metadata dan data permintaan. Gunakan opsi ini jika data yang Anda kirim cukup kecil untuk diupload lagi, secara keseluruhan, jika koneksi itu gagal.
Untuk melakukan upload multibagian, gunakan
Metode files.create
dengan
uploadType=multipart
.
Berikut cara melakukan upload multibagian:
Java
Python
Node.js
PHP
.NET
HTTP
Buat permintaan
POST
ke URI /upload metode dengan kueri parameter dariuploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Buat isi permintaan. Format isi sesuai dengan jenis konten multibagian/terkait RFC 2387, yang berisi dua bagian:
- Metadata. Metadata harus didahulukan dan harus memiliki
Content-Type
header ditetapkan keapplication/json;
charset=UTF-8
. Menambahkan metadata file dalam format JSON saya. - Media. Media harus ada di urutan kedua dan harus memiliki header
Content-Type
semua jenis MIME. Tambahkan data file ke bagian media.
Identifikasi setiap bagian dengan string batas, yang diawali dengan dua tanda hubung. Di beberapa selain itu, tambahkan dua tanda hubung setelah {i>string<i} batas akhir.
- Metadata. Metadata harus didahulukan dan harus memiliki
Tambahkan header HTTP tingkat atas ini:
Content-Type
. Tetapkan kemultipart/related
dan sertakan batas yang Anda gunakan untuk mengidentifikasi bagian berbeda dari permintaan. Sebagai contoh:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. Setel ke jumlah total byte dalam isi permintaan.
Kirim permintaan.
Untuk membuat atau memperbarui bagian metadata saja dan tanpa data terkait,
kirim permintaan POST
atau PATCH
ke endpoint resource standar:
https://www.googleapis.com/drive/v3/files
Jika permintaan berhasil,
server akan menampilkan kode status HTTP 200 OK
beserta
{i>metadata<i}.
Saat membuat file, mereka harus menentukan ekstensi file di name
file
kolom tersebut. Misalnya, saat membuat file JPEG foto, Anda mungkin menentukan sesuatu
seperti "name": "photo.jpg"
dalam metadata. Panggilan berikutnya ke files.get
akan menampilkan properti fileExtension
hanya baca
berisi ekstensi yang awalnya ditentukan di kolom name
.
Lakukan upload yang dapat dilanjutkan
Upload yang dapat dilanjutkan memungkinkan Anda melanjutkan operasi upload setelah komunikasi jika terjadi kegagalan, maka akan mengganggu aliran data. Karena Anda tidak perlu memulai ulang perangkat upload file dari awal, unggahan yang dapat dilanjutkan juga dapat mengurangi bandwidth jika terjadi kegagalan jaringan.
Unggahan yang dapat dilanjutkan berguna saat ukuran file Anda sangat bervariasi atau ketika ada batas waktu tetap untuk permintaan (seperti tugas latar belakang OS seluler dan permintaan App Engine tertentu). Anda mungkin juga menggunakan {i>upload<i} yang dapat dilanjutkan untuk situasi saat Anda ingin menampilkan status progres upload.
Upload yang dapat dilanjutkan terdiri dari beberapa langkah tingkat tinggi:
- Kirim permintaan awal dan ambil URI sesi yang dapat dilanjutkan.
- Upload data dan pantau status upload.
- (opsional) Jika upload terganggu, lanjutkan upload.
Kirim permintaan awal
Untuk memulai upload yang dapat dilanjutkan, gunakan
Metode files.create
dengan
uploadType=resumable
.
HTTP
Buat permintaan
POST
ke URI /upload metode dengan kueri parameter dariuploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
Jika permintaan inisiasi berhasil, responsnya akan menyertakan
200 OK
Kode status HTTP. Selain itu, terdapat juga headerLocation
yang menentukan URI sesi yang dapat dilanjutkan:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
Simpan URI sesi yang dapat dilanjutkan sehingga Anda dapat mengupload data dan kueri file mengetahui status upload. URI sesi yang dapat dilanjutkan akan berakhir setelah satu minggu.
Jika Anda memiliki metadata untuk file, tambahkan metadata ke isi permintaan dalam format JSON saya. Jika tidak, kosongkan isi permintaan.
Tambahkan header HTTP ini:
X-Upload-Content-Type
. Opsional. Tetapkan ke jenis MIME file data, yang ditransfer dalam permintaan berikutnya. Jika jenis MIME data tidak ditentukan dalam metadata atau melalui {i>header<i} ini, objek ditayangkan sebagaiapplication/octet-stream.
X-Upload-Content-Length
. Opsional. Ditetapkan ke jumlah byte data file, yang ditransfer dalam permintaan berikutnya.Content-Type
. Diperlukan jika Anda memiliki metadata untuk file. Tetapkan keapplication/json;
charset=UTF-8
.Content-Length
. Wajib, kecuali jika Anda menggunakan bagian encoding transfer. Setel ke jumlah byte dalam isi permintaan awal ini.
Kirim permintaan. Jika permintaan untuk memulai sesi berhasil, menyertakan kode status
200 OK HTTP
. Selain itu, respons menyertakan headerLocation
yang menentukan URI sesi yang dapat dilanjutkan. Gunakan URI sesi yang dapat dilanjutkan untuk mengupload data file dan melakukan kueri status upload. URI sesi yang dapat dilanjutkan akan berakhir setelah satu minggu.Salin dan simpan URL sesi yang dapat dilanjutkan.
Lanjutkan ke Upload konten.
Upload konten
Ada dua cara untuk mengupload file dengan sesi yang dapat dilanjutkan:
- Mengupload konten dalam satu permintaan: Gunakan pendekatan ini saat file dapat diupload dalam satu permintaan, jika tidak ada batas waktu tetap untuk satu permintaan, atau Anda tidak perlu menampilkan indikator progres upload. Ini adalah pendekatan terbaik karena memerlukan lebih sedikit permintaan dan menghasilkan tingkat tinggi.
Mengupload konten dalam beberapa bagian: Gunakan pendekatan ini jika Anda harus mengurangi jumlah data yang ditransfer dalam satu permintaan. Anda mungkin perlu untuk mengurangi data yang ditransfer ketika ada batas waktu tetap untuk setiap lainnya, seperti yang terjadi untuk class tertentu dari permintaan App Engine. Pendekatan ini juga berguna jika Anda harus memberikan indikator yang disesuaikan untuk menunjukkan progres upload.
HTTP - permintaan tunggal
- Buat permintaan
PUT
ke URI sesi yang dapat dilanjutkan. - Tambahkan data file ke isi permintaan.
- Tambahkan header HTTP Content-Length, setel ke jumlah byte dalam file.
- Kirim permintaan. Jika permintaan upload terganggu, atau jika Anda menerima
Respons
5xx
, ikuti prosedur di Melanjutkan upload yang terhenti.
HTTP - beberapa permintaan
Buat permintaan
PUT
ke URI sesi yang dapat dilanjutkan.Tambahkan data potongan tersebut ke isi permintaan. Membuat potongan menjadi beberapa Berukuran 256 KB (256 x 1024 byte), kecuali untuk potongan terakhir yang selesai file yang diupload. Pertahankan ukuran potongan sebesar mungkin sehingga file yang diupload efisien.
Tambahkan header HTTP ini:
Content-Length
. Setel ke jumlah byte dalam potongan saat ini.Content-Range
. Setel untuk menampilkan byte mana dalam file yang Anda upload. Sebagai contoh,Content-Range: bytes 0-524287/2000000
menunjukkan bahwa Anda mengupload 524.288 byte pertama (256 x 1024 x 2) dalam file 2.000.000 byte.
Kirim permintaan, dan proses respons. Jika permintaan upload adalah terganggu, atau jika Anda menerima respons
5xx
, ikuti prosedur di Melanjutkan upload yang terhenti.Ulangi langkah 1 sampai 4 untuk setiap bagian yang tersisa dalam {i>file<i}. Gunakan
Range
dalam respons untuk menentukan tempat memulai potongan berikutnya. Jangan berasumsi bahwa server menerima semua byte yang dikirim dalam permintaan sebelumnya.
Setelah seluruh upload file selesai, Anda akan menerima 200 OK
atau
Respons 201 Created
, beserta metadata apa pun yang terkait dengan resource tersebut.
Melanjutkan upload yang terhenti
Jika permintaan upload dihentikan sebelum respons diberikan, atau jika Anda menerima respons 503
Service Unavailable
, Anda harus melanjutkan upload yang terhenti.
HTTP
Untuk meminta status upload, buat permintaan
PUT
kosong ke URI sesi yang dapat dilanjutkan.Tambahkan header
Content-Range
untuk menunjukkan bahwa posisi saat ini di file tidak diketahui. Misalnya, setelContent-Range
ke*/2000000
jika total panjang file adalah 2.000.000 byte. Jika Anda tidak tahu ukuran penuh tetapkanContent-Range
ke*/*
.Kirim permintaan.
Proses respons:
- Respons
200 OK
atau201 Created
menunjukkan bahwa upload telah selesai, dan tidak perlu tindakan lebih lanjut. - Respons
308 Resume Incomplete
menunjukkan bahwa Anda harus melanjutkan untuk mengunggah file. - Respons
404 Not Found
menunjukkan bahwa sesi upload telah berakhir dan upload harus dimulai ulang dari awal.
- Respons
Jika Anda menerima respons
308 Resume Incomplete
, prosesRange
respons untuk menentukan byte mana yang diterima server. Jika respons tidak memiliki headerRange
, tidak ada byte yang diterima. Misalnya, headerRange
daribytes=0-42
menunjukkan bahwa header pertama 43 byte file diterima dan potongan berikutnya yang akan diunggah, dimulai dengan byte 44.Setelah Anda mengetahui tempat untuk melanjutkan upload, lanjutkan untuk mengupload file dimulai dengan byte berikutnya. Sertakan Header
Content-Range
untuk menunjukkan bagian file yang Anda kirim. Sebagai contoh,Content-Range: bytes 43-1999999
menunjukkan bahwa Anda mengirim {i>byte<i} 44 hingga 2.000.000.
Menangani error upload media
Saat Anda mengupload media, ikuti praktik terbaik berikut untuk menangani error:
- Untuk error
5xx
, lanjutkan atau coba lagi upload yang gagal karena koneksi internet interupsi. Untuk informasi lebih lanjut tentang penanganan error5xx
, lihat Error 500, 502, 503, 504. - Untuk error
403 rate limit
, coba upload lagi. Untuk informasi selengkapnya tentang menangani error403 rate limit
, lihat error 403:rateLimitExceeded
. - Untuk error
4xx
apa pun (termasuk403
) selama upload yang dapat dilanjutkan, mulai ulang file yang diupload. Error ini menunjukkan bahwa sesi upload telah berakhir dan harus dimulai ulang dengan meminta URI sesi baru. Upload sesi juga akan berakhir setelah satu minggu tidak aktif.
Impor ke jenis Google Dokumen
Saat membuat file di Drive, Anda mungkin ingin mengonversi ke jenis file Google Workspace, seperti Google Dokumen atau Spreadsheet. Misalnya, mungkin Anda ingin mengubah dokumen dari pengolah kata favorit Anda ke dalam Dokumen untuk memanfaatkan baru.
Untuk mengonversi file ke jenis file Google Workspace tertentu, tentukan
Google Workspace mimeType
saat membuat file.
Berikut cara mengonversi file CSV ke sheet Google Workspace:
Java
Python
Node.js
PHP
.NET
Untuk melihat apakah konversi tersedia, periksa array importFormats
resource about
sebelum membuat file.
Konversi yang didukung tersedia secara dinamis dalam array ini. Beberapa hal yang umum
format impor adalah:
From | Menjadi |
---|---|
Microsoft Word, Teks OpenDocument, HTML, RTF, teks biasa | Google Dokumen |
Microsoft Excel, Spreadsheet OpenDocument, CSV, TSV, teks biasa | Google Spreadsheet |
Microsoft PowerPoint, Presentasi OpenDocument | Google Slide |
JPEG, PNG, GIF, BMP, PDF | Google Dokumen (menyematkan gambar di Dokumen) |
Teks biasa (jenis MIME khusus), JSON | Google Apps Script |
Saat Anda mengupload dan mengonversi media selama permintaan update
ke
File Dokumen, Spreadsheet, atau Slide,
isi lengkap dokumen akan diganti.
Saat Anda mengonversi gambar ke Dokumen, Drive menggunakan
Pengenalan Karakter Optik (OCR) untuk mengonversi gambar ke teks. Anda dapat
meningkatkan kualitas algoritma OCR dengan menentukan atribut BCP
47 kode bahasa
di
ocrLanguage
. Teks yang diekstrak akan muncul di Dokumen bersama dengan gambar tersemat.
Gunakan ID yang telah dibuat sebelumnya untuk mengupload file
Drive API memungkinkan Anda mengambil daftar ID file siap pakai yang
digunakan untuk mengunggah
dan membuat sumber daya. Permintaan upload dan pembuatan file dapat
menggunakan ID yang telah dibuat sebelumnya. Tetapkan kolom id
dalam metadata file.
Untuk membuat ID yang telah dibuat sebelumnya, panggil
files.generateIds
dengan
jumlah ID yang akan dibuat.
Anda dapat mencoba ulang upload dengan ID yang telah dibuat secara aman jika ada
error server atau waktu habis. Jika file berhasil dibuat, langkah selanjutnya
percobaan ulang menampilkan error HTTP 409
dan tidak menghasilkan file duplikat.
Menentukan teks yang dapat diindeks untuk jenis file yang tidak dikenal
Pengguna dapat menggunakan UI Drive untuk menemukan konten dokumen. Anda juga dapat
gunakan files.list
dan fullText
untuk menelusuri konten dari aplikasi Anda. Untuk informasi selengkapnya, lihat Menelusuri
file dan folder.
{i>Drive<i} secara otomatis mengindeks dokumen untuk pencarian ketika
mengenali jenis {i>file<i}, termasuk dokumen teks, PDF, gambar dengan teks, dan
jenis umum lainnya. Jika aplikasi Anda menyimpan jenis file lain (seperti gambar,
video, dan pintasan), Anda dapat meningkatkan
visibilitas dengan menyediakan
teks yang dapat diindeks di kolom contentHints.indexableText
file.
Untuk informasi selengkapnya tentang teks yang dapat diindeks, lihat Mengelola file metadata.