Mengelola operasi yang berjalan lama

Operasi yang berjalan lama (LRO) adalah metode API yang memerlukan waktu lebih lama untuk diselesaikan daripada yang sesuai untuk respons API. Biasanya, Anda tidak ingin membiarkan thread panggilan terbuka saat tugas berjalan karena akan memberikan pengalaman pengguna yang buruk. Sebaiknya, tampilkan beberapa jenis janji kepada pengguna dan izinkan mereka untuk memeriksa kembali nanti.

Google Drive API menampilkan LRO setiap kali Anda memanggil metode download di resource files untuk mendownload konten file baik melalui Drive API maupun library kliennya.

Metode ini menampilkan resource operations ke klien. Anda dapat menggunakan resource operations untuk mengambil status metode API secara asinkron dengan melakukan polling operasi melalui metode get. LRO di Drive API mematuhi pola desain LRO Google Cloud .

Untuk mengetahui informasi selengkapnya, lihat Operasi yang berjalan lama.

Catatan: Metode files.download dan operations.get menggunakan kuota Drive API normal. Untuk mengetahui informasi selengkapnya, lihat Batas penggunaan.

Ringkasan proses

Diagram berikut menunjukkan langkah-langkah tingkat tinggi tentang cara kerja metode file.download.

Gambar 1. Langkah-langkah tingkat tinggi untuk metode file.download.

1. Panggil files.download: Saat aplikasi Anda memanggil metode download, aplikasi tersebut meluncurkan permintaan download Drive API untuk file. Untuk mengetahui informasi selengkapnya, lihat Mendownload file.

2. Meminta izin: Permintaan mengirimkan kredensial autentikasi ke Drive API. Jika aplikasi Anda memerlukan panggilan Drive API menggunakan autentikasi pengguna yang belum diberikan, pengguna akan diminta untuk login. Aplikasi Anda juga meminta akses dengan cakupan yang Anda tentukan saat menyiapkan autentikasi.

3. Mulai download: Permintaan Drive API dibuat untuk memulai download file. Permintaan dapat diajukan ke Google Vids atau konten Google Workspace lainnya.

4. Mulai LRO: Operasi yang berjalan lama dimulai dan mengelola proses download.

5. Mengembalikan operasi yang tertunda: Drive API menampilkan operasi yang tertunda yang berisi informasi tentang pengguna yang membuat permintaan dan beberapa kolom metadata file.

6. Status tertunda awal: Aplikasi Anda menerima operasi yang tertunda bersama dengan status tertunda awal done=null. Hal ini menunjukkan bahwa file belum siap untuk didownload dan status operasinya tertunda.

7. Panggil operations.get dan verifikasi hasil: Aplikasi Anda memanggil get pada interval yang direkomendasikan untuk melakukan polling hasil operasi dan mendapatkan status terbaru dari operasi yang berjalan lama. Jika status tertunda done=false ditampilkan, aplikasi Anda harus terus melakukan polling hingga operasi menampilkan status selesai (done=true). Untuk file besar, Anda harus melakukan polling beberapa kali. Untuk mengetahui informasi selengkapnya, lihat Mendapatkan detail tentang operasi yang berjalan lama.

8. Periksa status tertunda: Jika status tertunda done=true ditampilkan dari LRO, hal ini menunjukkan bahwa file siap didownload dan status operasi selesai.

9. Menampilkan operasi yang telah selesai dengan URI download: Setelah LRO selesai, Drive API akan menampilkan URI download dan file kini tersedia bagi pengguna.

Mendownload file

Untuk mendownload konten dalam operasi yang berjalan lama, gunakan metode download di resource files. Metode ini menggunakan parameter kueri file_id, mime_type, dan revision_id:

• Wajib. Parameter kueri file_id adalah ID file yang akan didownload.

• Opsional. Parameter kueri mime_type menunjukkan jenis MIME yang harus digunakan metode. Fitur ini hanya tersedia saat mendownload konten media non-blob (seperti dokumen Google Workspace). Untuk mengetahui daftar lengkap jenis MIME yang didukung, lihat Mengekspor jenis MIME untuk dokumen Google Workspace.

  Jika jenis MIME tidak ditetapkan, dokumen Google Workspace akan didownload dengan jenis MIME default. Untuk mengetahui informasi selengkapnya, lihat Jenis MIME default.

• Opsional. Parameter kueri revision_id adalah ID revisi file yang akan didownload. Fitur ini hanya tersedia saat mendownload file blob, Google Dokumen, dan Google Spreadsheet. Menampilkan kode error INVALID_ARGUMENT saat mendownload revisi tertentu pada file yang tidak didukung.

Metode download adalah satu-satunya cara untuk mendownload file Vids dalam format MP4 dan biasanya paling cocok untuk mendownload sebagian besar file video.

Link download yang dibuat untuk Google Dokumen atau Spreadsheet pada awalnya akan menampilkan pengalihan. Klik link baru untuk mendownload file.

Permintaan ke metode download yang memulai LRO, dan permintaan untuk mengambil URI download akhir, harus menggunakan kunci resource. Untuk mengetahui informasi selengkapnya, lihat Mengakses file Drive yang dibagikan melalui link menggunakan kunci resource.

Protokol permintaan ditampilkan di sini.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

Ganti FILE_ID dengan fileId file yang ingin Anda download.

Catatan: Metode download hanya tersedia di Drive API v3.

Jenis MIME default

Jika jenis MIME tidak ditetapkan saat mendownload konten non-blob, jenis MIME default berikut akan ditetapkan:

Jenis Dokumen	Format	jenis MIME	Ekstensi File
Google Apps Script	JSON	application/vnd.google-apps.script+json	.json
Google Dokumen	Microsoft Word	application/vnd.openxmlformats-officedocument.wordprocessingml.document	.docx
Google Gambar	PNG	image/png	.png
Google Formulir	ZIP	application/zip	.zip
Google Spreadsheet	Microsoft Excel	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	.xlsx
Google Sites	Teks Mentah	text/raw	.txt
Google Slide	Microsoft PowerPoint	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx
Google Vids	MP4	application/mp4	.mp4
Jamboard	PDF	application/pdf	.pdf

Respons download

Saat memanggil metode download, isi respons terdiri dari resource yang merepresentasikan operasi yang berjalan lama. Metode ini biasanya menampilkan link untuk mendownload konten file.

Tips: Simpan nilai kolom name karena Anda akan memerlukannya untuk melakukan polling LRO.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

Output ini mencakup nilai-nilai berikut:

• RESOURCE_KEY: Kunci resource membantu melindungi file Anda dari akses yang tidak diinginkan. Untuk mengetahui informasi selengkapnya, lihat Mengakses file Drive yang dibagikan melalui link menggunakan kunci resource.

• NAME: Nama yang ditetapkan server.

• DOWNLOAD_URI: URI download akhir untuk file.

Perhatikan bahwa kolom partialDownloadAllowed menunjukkan apakah download sebagian diizinkan. Benar (True) saat mendownload konten file blob.

Mendapatkan detail tentang operasi yang berjalan lama

Operasi yang berjalan lama adalah panggilan metode yang mungkin memerlukan waktu lama untuk diselesaikan. Biasanya, operasi download yang baru dibuat awalnya ditampilkan dalam status menunggu proses (done=null), terutama untuk file Vids.

Anda dapat menggunakan resource operations yang disediakan Drive API untuk memeriksa status LRO pemrosesan dengan menyertakan nama unik yang ditetapkan server.

Metode get mendapatkan status terbaru dari operasi yang berjalan lama secara asinkron. Klien dapat menggunakan metode ini untuk melakukan polling hasil operasi pada interval seperti yang direkomendasikan oleh layanan API.

Catatan: Pengguna yang membuat permintaan metode get harus cocok dengan pengguna yang memulai permintaan metode download yang berdekatan, atau permintaan akan gagal.

Polling operasi yang berjalan lama

Untuk melakukan polling pada LRO yang tersedia, panggil metode get berulang kali hingga operasi selesai. Gunakan backoff eksponensial di antara setiap permintaan polling, seperti 10 detik.

LRO tetap tersedia selama minimal 12 jam, tetapi dalam beberapa kasus dapat bertahan lebih lama. Durasi ini dapat berubah dan dapat berbeda di antara jenis file. Setelah masa berlaku resource habis, permintaan metode download baru diperlukan.

Semua permintaan ke get harus menggunakan kunci resource. Untuk mengetahui informasi selengkapnya, lihat Mengakses file Drive yang dibagikan melalui link menggunakan kunci resource.

Protokol permintaan ditampilkan di sini.

Panggilan metode

operations.get(name='NAME');

Ganti NAME dengan nama yang ditetapkan server untuk operasi seperti yang ditampilkan dalam respons terhadap permintaan metode download.

curl

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI dengan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI . Anda dapat memeriksa akun aktif dengan menjalankan gcloud auth list.

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

Ganti NAME dengan nama yang ditetapkan server untuk operasi seperti yang ditampilkan dalam respons terhadap permintaan metode download.

Perintah ini menggunakan jalur /drive/v3/operations/NAME.

Perhatikan bahwa name hanya ditampilkan dalam respons terhadap permintaan download. Tidak ada cara lain untuk mengambilnya karena Drive API tidak mendukung metode List. Jika nilai name hilang, Anda harus membuat respons baru dengan memanggil permintaan metode download lagi.

Respons dari permintaan get terdiri dari resource yang merepresentasikan operasi yang berjalan lama. Untuk mengetahui informasi selengkapnya, lihat Mendownload respons.

Jika respons berisi status selesai (done=true), operasi yang berjalan lama telah selesai.

Mendownload revisi

Anda dapat menggunakan nilai kolom headRevisionId dari resource files untuk mendownload revisi terbaru. Tindakan ini mengambil revisi yang sesuai dengan metadata file yang sebelumnya Anda ambil. Untuk mendownload data untuk semua revisi file sebelumnya yang masih disimpan di cloud, Anda dapat memanggil metode list pada resource revisions dengan parameter fileId. Tindakan ini akan menampilkan semua revisionIds dalam file.

Catatan: Akses ke revisi historis dibatasi berdasarkan peran. Periksa kolom capabilities.canReadRevisions pada resource files sebelum mencoba mengakses.

Untuk mendownload konten revisi file blob, Anda harus memanggil metode get pada resource revisions dengan ID file yang akan didownload, ID revisi, dan parameter URL alt=media. Parameter URL alt=media memberi tahu server bahwa download konten sedang diminta sebagai format respons alternatif.

Revisi untuk Google Dokumen, Spreadsheet, Slide, dan Vids tidak dapat didownload menggunakan metode get dengan URL alt=media . Jika tidak, error fileNotDownloadable akan terjadi.

Parameter URL alt=media adalah parameter sistem yang tersedia di semua Google REST API. Jika menggunakan library klien untuk Drive API, Anda tidak perlu menetapkan parameter ini secara eksplisit.

Protokol permintaan ditampilkan di sini.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

Ganti kode berikut:

• FILE_ID: fileId file yang ingin Anda download.
• REVISION_ID: revisionId revisi yang ingin Anda download.

Catatan: Jika Anda menggunakan Drive API v2 yang lebih lama, Anda harus mengirim permintaan GET yang sah ke properti downloadUrl-nya. Google Drive membuat URL singkat yang berumur pendek ini saat Anda meminta revisi, tetapi jangan mengandalkannya untuk penggunaan di kemudian hari. Anda juga dapat mengekspor revisi dalam salah satu format yang didukung dengan memeriksa properti exportLinks.

Revisi Google Dokumen, Gambar, dan Slide secara otomatis menambah nomor revisi. Namun, rangkaian angka mungkin memiliki kesenjangan jika revisi dihapus, jadi Anda tidak boleh mengandalkan angka berurutan untuk mengambil revisi.

Memecahkan masalah LRO

Jika LRO gagal, responsnya akan menyertakan kode error Google Cloud kanonis.

Tabel berikut memberikan penjelasan tentang penyebab setiap kode dan rekomendasi cara menangani kode tersebut. Untuk banyak error, tindakan yang direkomendasikan adalah mencoba permintaan lagi menggunakan backoff eksponensial.

Anda dapat membaca lebih lanjut tentang model error ini dan cara penanganannya di Panduan Desain API.

Kode	Enum	Deskripsi	Tindakan yang disarankan
1	CANCELLED	Operasi dibatalkan, biasanya oleh pemanggil.	Jalankan kembali operasi.
2	UNKNOWN	Error ini dapat ditampilkan jika nilai Status yang diterima dari ruang alamat lain berada di ruang error yang tidak diketahui di ruang alamat ini. Jika error API tidak menampilkan informasi yang cukup, error tersebut dapat dikonversi menjadi error ini.	Coba lagi dengan backoff eksponensial.
3	INVALID_ARGUMENT	Klien menetapkan argumen yang tidak valid. Error ini berbeda dengan FAILED_PRECONDITION. INVALID_ARGUMENT menunjukkan argumen yang bermasalah, terlepas dari status sistem, seperti nama file yang salah format.	Jangan coba lagi tanpa memperbaiki masalah.
4	DEADLINE_EXCEEDED	Batas waktu berakhir sebelum operasi selesai. Untuk operasi yang mengubah keadaan sistem, error ini mungkin ditampilkan, bahkan jika, operasi tersebut telah selesai. Sebagai contoh, respons berhasil dari suatu server dapat tertunda selama waktu yang cukup lama hingga tenggat waktu berakhir.	Coba lagi dengan backoff eksponensial.
5	NOT_FOUND	Beberapa entitas yang diminta, seperti resource FHIR, tidak ditemukan.	Jangan coba lagi tanpa memperbaiki masalah.
6	ALREADY_EXISTS	Entitas yang coba dibuat oleh klien, seperti instance DICOM, sudah ada.	Jangan coba lagi tanpa memperbaiki masalah.
7	PERMISSION_DENIED	Pemanggil tidak memiliki izin untuk menjalankan operasi yang ditentukan. Kode error ini tidak menyatakan bahwa suatu permintaan valid, entitas yang diminta ada, atau memenuhi prakondisi lainnya.	Jangan coba lagi tanpa memperbaiki masalah.
8	RESOURCE_EXHAUSTED	Beberapa resource telah habis, seperti kuota per project.	Coba lagi dengan backoff eksponensial. Kuota mungkin tersedia dari waktu ke waktu.
9	FAILED_PRECONDITION	Operasi tersebut ditolak karena sistem tidak dalam keadaan dibutuhkan untuk menjalankan operasi. Misalnya, direktori yang akan dihapus tidak kosong, atau operasi rmdir diterapkan pada non-direktori.	Jangan coba lagi tanpa memperbaiki masalah.
10	ABORTED	Operasi dibatalkan, umumnya karena masalah konkurensi seperti kegagalan pemeriksaan pengurut atau pembatalan transaksi.	Coba lagi dengan backoff eksponensial.
11	OUT_OF_RANGE	Upaya operasi dilakukan melampaui rentang yang valid, seperti mencari tahu atau membaca melampaui akhir file. Tidak seperti INVALID_ARGUMENT, error ini menunjukkan masalah yang dapat diperbaiki jika status sistem berubah.	Jangan coba lagi tanpa memperbaiki masalah.
12	UNIMPLEMENTED	Operasi tidak diterapkan atau tidak didukung/diaktifkan di Drive API.	Jangan coba lagi.
13	INTERNAL	Error internal. Error ini menunjukkan bahwa terjadi error tak terduga dalam pemrosesan di sistem pokok.	Coba lagi dengan backoff eksponensial.
14	UNAVAILABLE	Drive API tidak tersedia. Kemungkinan besar ini hanya kondisi sementara, yang dapat diperbaiki dengan mencoba kembali menggunakan backoff eksponensial. Perlu diketahui bahwa mencoba kembali operasi non-idempoten tidak selalu aman.	Coba lagi dengan backoff eksponensial.
15	DATA_LOSS	Data hilang atau rusak yang tidak dapat dipulihkan.	Hubungi administrator sistem Anda. Administrator sistem mungkin ingin menghubungi perwakilan dukungan jika terjadi kehilangan atau kerusakan data.
16	UNAUTHENTICATED	Permintaan tidak memiliki kredensial autentikasi operasi yang valid.	Jangan coba lagi tanpa memperbaiki masalah.

Topik terkait

• Mendownload dan mengekspor file