Mengelola operasi yang berjalan lama

Operasi yang berjalan lama (LRO) adalah metode API yang memerlukan waktu lebih lama untuk selesai daripada yang sesuai untuk respons API. Biasanya, Anda tidak ingin mempertahankan thread panggilan terbuka saat tugas berjalan karena menawarkan pengalaman pengguna yang buruk. Sebagai gantinya, sebaiknya tampilkan beberapa jenis janji kepada pengguna dan izinkan mereka memeriksa kembali nanti.

Google Drive API menampilkan LRO setiap kali Anda memanggil metode download() pada resource files untuk mendownload konten file melalui Drive API atau library klien-nya.

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: Baik metode files.download() maupun metode operations.get() menggunakan kuota Drive API normal. Untuk mengetahui informasi selengkapnya, lihat Batas penggunaan.

Ringkasan proses

Diagram berikut menunjukkan langkah-langkah tingkat tinggi terkait 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 akan meluncurkan permintaan download Drive API untuk file. Untuk mengetahui informasi selengkapnya, lihat Mendownload file.

2. Meminta izin: Permintaan tersebut mengirimkan kredensial autentikasi ke Drive API. Jika aplikasi Anda memerlukan panggilan Drive API menggunakan autentikasi pengguna yang belum diberikan, aplikasi akan meminta pengguna 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 dilakukan ke Google Vids atau beberapa konten Google Workspace lainnya.

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

5. Menampilkan 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 tertunda beserta status tertunda awal done=null. Hal ini menunjukkan bahwa file belum siap didownload dan status operasinya tertunda.

7. Memanggil operations.get dan memverifikasi hasilnya: 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, lakukan 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, ini menunjukkan bahwa file siap didownload dan bahwa status operasi sudah selesai.

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

Mendownload file

Untuk mendownload konten dalam operasi yang berjalan lama, gunakan metode download() pada 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. Data 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 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 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 informasi selengkapnya, lihat Mengakses file Drive yang dibagikan 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	{i>.json<i}
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	{i>.pptx<i}
Google Vids	MP4	aplikasi/mp4	.mp4
Jamboard	PDF	application/pdf	.pdf

Respons download

Saat memanggil metode download(), isi respons terdiri dari resource yang mewakili 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 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 jika mendownload konten file blob.

Mendapatkan detail tentang operasi yang berjalan lama

Operasi yang berjalan lama adalah panggilan metode yang mungkin memerlukan banyak waktu untuk diselesaikan. Biasanya, operasi download yang baru dibuat awalnya akan ditampilkan dalam status tertunda (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. Jika tidak, permintaan akan gagal.

Polling operasi yang berjalan lama

Untuk melakukan polling 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 antar-jenis file. Setelah masa berlaku resource berakhir, permintaan metode download() baru diperlukan.

Setiap permintaan ke get() harus menggunakan kunci resource. Untuk informasi selengkapnya, lihat Mengakses file Drive bersama dengan 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 mewakili operasi yang berjalan lama. Untuk informasi selengkapnya, lihat Respons download.

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 akan 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 di resource files sebelum mencoba akses.

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 Video tidak dapat didownload menggunakan metode get() dengan URL alt=media . Jika tidak, error fileNotDownloadable akan dihasilkan.

Parameter URL alt=media adalah parameter sistem yang tersedia di semua REST API Google. 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 menggunakan Drive API v2 versi lama, Anda harus mengirim permintaan GET yang diotorisasi ke properti downloadUrl-nya. Google Drive membuat URL berumur pendek ini saat Anda meminta revisi, tetapi jangan mengandalkannya untuk penggunaan di lain waktu. Anda juga dapat mengekspor revisi dalam salah satu format yang didukung dengan memeriksa properti exportLinks.

Revisi Google Dokumen, Gambar, dan Slide akan menambahkan angka revisi secara otomatis. Namun, rangkaian angka mungkin memiliki celah jika revisi dihapus, jadi Anda tidak boleh mengandalkan nomor 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 lagi permintaan menggunakan backoff eksponensial.

Anda dapat membaca lebih lanjut 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 tersebut.
2	UNKNOWN	Error ini mungkin ditampilkan jika nilai Status yang diterima dari ruang alamat lain berada dalam ruang error yang tidak diketahui di ruang alamat ini. Jika error API tidak menampilkan informasi yang memadai, 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 statusnya di dalam sistem, seperti nama file yang salah format.	Jangan mencoba lagi tanpa memperbaiki masalah.
4	DEADLINE_EXCEEDED	Batas waktu berakhir sebelum operasi selesai. Untuk operasi yang mengubah status sistem, error ini mungkin ditampilkan, meskipun operasi tersebut telah selesai. Misalnya, respons yang berhasil dari server dapat tertunda untuk waktu yang cukup lama hingga batas waktu berakhir.	Coba lagi dengan backoff eksponensial.
5	NOT_FOUND	Beberapa entitas yang diminta, seperti resource FHIR, tidak ditemukan.	Jangan mencoba lagi tanpa memperbaiki masalah.
6	ALREADY_EXISTS	Entitas yang coba dibuat oleh klien, seperti instance DICOM, sudah ada.	Jangan mencoba 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 mencoba 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 status yang diperlukan untuk menjalankan operasi. Misalnya, direktori yang akan dihapus tidak kosong, atau operasi rmdir diterapkan ke non-direktori.	Jangan mencoba lagi tanpa memperbaiki masalah.
10	ABORTED	Operasi dibatalkan, biasanya karena masalah serentak 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 atau membaca melampaui akhir file. Tidak seperti INVALID_ARGUMENT, error ini menunjukkan masalah yang dapat diperbaiki jika status sistem berubah.	Jangan mencoba lagi tanpa memperbaiki masalah.
12	UNIMPLEMENTED	Operasi tidak diterapkan atau tidak didukung/diaktifkan di Drive API.	Jangan coba lagi.
13	INTERNAL	Error internal. Pesan ini menunjukkan bahwa terjadi error tak terduga dalam pemrosesan pada 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. Perhatikan bahwa tidak selalu aman untuk mencoba kembali operasi non-idempoten.	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 mencoba lagi tanpa memperbaiki masalah.

Topik terkait

• Mendownload dan mengekspor file
• Mengelola revisi file