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 membuat thread panggilan tetap terbuka saat tugas berjalan karena hal ini akan memberikan pengalaman pengguna yang buruk. Sebagai gantinya, 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 pada resource files untuk mendownload konten file melalui Drive API atau library kliennya.

Metode ini menampilkan resource operations kepada 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, silakan melihat Operasi yang berjalan lama.

Catatan: Metode files.download dan metode operations.get menggunakan kuota Drive API normal. Untuk 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 akan meluncurkan permintaan download Drive API untuk file tersebut. Untuk mengetahui informasi selengkapnya, lihat Mendownload file.

2. Minta 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 dibuat ke Google Vids atau konten Google Workspace lainnya.

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

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

6. Status awal yang tertunda: Aplikasi Anda menerima operasi yang tertunda beserta status awal yang tertunda done=null. Hal ini menunjukkan bahwa file belum siap untuk didownload dan status operasi 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 done=false yang tertunda 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 yang tertunda: Jika status done=true yang tertunda ditampilkan dari LRO, hal ini menunjukkan bahwa file siap untuk didownload dan status operasi selesai.

9. Tampilkan operasi yang 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 file_id, mime_type, dan revision_id:

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

• Opsional. Parameter kueri mime_type menunjukkan jenis MIME yang harus digunakan metode. Parameter ini hanya tersedia saat mendownload konten media non-blob (seperti dokumen Google Workspace). Untuk daftar lengkap jenis MIME yang didukung, lihat Jenis MIME ekspor 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. Parameter 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. Jika Anda mencoba mengekspor file Google Vids, Anda akan menerima a fileNotExportable error.

Link download yang dibuat untuk Google Dokumen atau Spreadsheet awalnya 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	video/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 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 dan bernilai 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 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, atau 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 antarjenis file. Setelah resource berakhir masa berlakunya, permintaan metode download baru diperlukan.

Setiap 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 menggunakan 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 mengetahui informasi selengkapnya, lihat Download response.

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

Penting: Selalu periksa apakah done=true dalam respons awal sebelum mencoba melakukan polling operasi. Jika operasi selesai dan Anda mencoba melakukan polling name, Anda mungkin mendapatkan error 403 Forbidden dengan status PERMISSION_DENIED. Error ini menandakan bahwa operasi tidak lagi dalam status yang dapat di-polling.

Mendownload revisi

Anda dapat menggunakan nilai dari headRevisionId kolom 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 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 alt parameter sistem. Parameter alt=media memberi tahu server bahwa download konten diminta sebagai format respons alternatif.

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

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

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 yang diotorisasi GET ke properti downloadUrl-nya. Google Drive membuat URL berumur pendek ini saat Anda meminta revisi, tetapi jangan mengandalkannya untuk penggunaan nanti. Anda juga dapat mengekspor revisi dalam salah satu format yang didukung dengan memeriksa properti exportLinks.

Revisi Google Dokumen, Gambar, dan Slide akan otomatis menambah nomor revisi. Namun, rangkaian angka mungkin memiliki celah jika revisi dihapus, sehingga 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 menampilkan setiap kode error, kode status HTTP yang dipetakan, deskripsi, dan rekomendasi cara menangani kode error. Untuk banyak error, tindakan yang direkomendasikan adalah mencoba lagi permintaan menggunakan backoff eksponensial.

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

Kode	Enum	Kode status HTTP	Deskripsi	Tindakan yang disarankan
1	CANCELLED	499 Client Closed Request	Operasi dibatalkan, biasanya oleh pemanggil.	Jalankan kembali operasi.
2	UNKNOWN	500 Internal Server Error	Error ini mungkin 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 mungkin dikonversi menjadi error ini.	Coba lagi dengan backoff eksponensial.
3	INVALID_ARGUMENT	400 Bad Request	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	504 Gateway Timeout	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	404 Not Found	Beberapa entity yang diminta, seperti resource FHIR, tidak ditemukan.	Jangan coba lagi tanpa memperbaiki masalah.
6	ALREADY_EXISTS	409 Conflict	Entitas yang coba dibuat oleh klien, seperti instance DICOM, sudah ada.	Jangan coba lagi tanpa memperbaiki masalah.
7	PERMISSION_DENIED	403 Forbidden	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	429 Too Many Requests	Beberapa resource telah habis, seperti kuota per project.	Coba lagi dengan backoff eksponensial. Kuota mungkin akan tersedia seiring waktu.
9	FAILED_PRECONDITION	400 Bad Request	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	409 Conflict	Operasi dibatalkan, umumnya karena masalah konkurensi seperti kegagalan pemeriksaan pengurut atau pembatalan transaksi.	Coba lagi dengan backoff eksponensial.
11	OUT_OF_RANGE	400 Bad Request	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	501 Not Implemented	Operasi tidak diterapkan atau tidak didukung/diaktifkan dalam Drive API.	Jangan coba lagi.
13	INTERNAL	500 Internal Server Error	Error internal. Hal ini menunjukkan bahwa terjadi error yang tidak terduga dalam pemrosesan pada sistem yang mendasarinya.	Coba lagi dengan backoff eksponensial.
14	UNAVAILABLE	503 Service 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	500 Internal Server Error	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	401 Unauthorized	Permintaan tidak memiliki kredensial autentikasi operasi yang valid.	Jangan coba lagi tanpa memperbaiki masalah.

Topik terkait

• Mendownload dan mengekspor file