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 promise 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.

Ringkasan proses

Diagram berikut menunjukkan langkah-langkah tingkat tinggi tentang cara kerja 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 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. 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 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.

Jenis MIME default

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

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.

{
  "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 waktu lama untuk diselesaikan. Biasanya, operasi download yang baru dibuat awalnya 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.

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 yang dibagikan dengan link menggunakan kunci resource.

Protokol permintaan ditampilkan di sini.

operations.get(name='NAME');

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

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.

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.

Revisi Google Dokumen, Gambar, dan Slide akan otomatis menambahkan nomor revisi. Namun, deretan 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 model error ini dan cara penanganannya di Panduan Desain API.

Topik terkait

• Mendownload dan mengekspor file
• Mengelola revisi file