Mengelola persetujuan

Dokumen ini menjelaskan cara mengelola persetujuan di Google Drive API.

Pengguna dapat mengirim dokumen di Google Drive melalui proses persetujuan formal. Anda dapat menggunakan proses ini untuk mendapatkan persetujuan terkait peninjauan kontrak atau dokumen resmi sebelum dipublikasikan. Persetujuan melacak status peninjauan (seperti Dalam Proses, Disetujui, atau Ditolak) dan peninjau yang terlibat. Persetujuan adalah cara yang sangat baik untuk memvalidasi konten dan menyimpan catatan peninjau.

Anda dapat membuat dan mengelola persetujuan konten di Drive. Google Drive API menyediakan resource approvals untuk menggunakan persetujuan file. Metode resource approvals berfungsi pada item dalam Drive, Google Dokumen, dan editor Google Workspace lainnya. Peninjau dapat menyetujui, menolak, atau memberikan masukan pada dokumen secara langsung.

Sebelum memulai

File Anda harus berisi kemampuan canStartApproval . Untuk memeriksa kemampuan file, panggil metode get pada resource files dengan parameter jalur fileId dan gunakan kolom kemampuan canStartApproval dalam parameter fields. Untuk mengetahui informasi selengkapnya, lihat Memahami kemampuan file.

Kemampuan boolean canStartApproval adalah false jika:
- Setelan administrator membatasi akses ke fitur.
- Edisi Google Workspace Anda tidak memenuhi syarat.
- File dimiliki oleh pengguna di luar domain Anda.
- Pengguna tidak memiliki izin role=writer pada file.
Pastikan Anda membagikan file target secara manual kepada peninjau. Drive tidak melakukannya secara otomatis. Jika peninjau tidak memiliki akses file, permintaan persetujuan akan berhasil, tetapi mereka tidak akan menerima notifikasi atau dapat melihat file.

Konsep

Konsep utama berikut membentuk dasar persetujuan.

Status persetujuan

Saat Anda meminta persetujuan dokumen, proses persetujuan memastikan setiap peninjau menyetujui konten versi yang sama. Jika file diedit setelah peninjau menyetujui permintaan, dan sebelum permintaan selesai, persetujuan peninjau akan direset dan peninjau harus menyetujui versi baru. Jika konten diedit setelah persetujuan akhir, banner akan muncul di dokumen yang menunjukkan bahwa versi saat ini berbeda dengan versi yang disetujui.

Resource approvals mencakup objek Status yang menjelaskan status persetujuan saat resource diminta. Objek ini juga mencakup objek ReviewerResponse yang menjelaskan respons terhadap persetujuan yang dibuat oleh peninjau tertentu. Setiap respons pengulas diwakili oleh objek Response.

Setiap tindakan dalam proses persetujuan akan menghasilkan notifikasi email yang dikirim kepada pemrakarsa (pengguna yang meminta persetujuan) dan semua peninjau. Persetujuan ini juga ditambahkan ke log aktivitas persetujuan.

Semua peninjau harus menyetujui persetujuan. Setiap peninjau yang menolak persetujuan akan menetapkan status selesai ke DECLINED.

Setelah persetujuan selesai (statusnya APPROVED, CANCELLED, atau DECLINED), persetujuan akan tetap dalam status selesai dan tidak dapat diinteraksi oleh pemrakarsa atau peninjau. Anda dapat menambahkan komentar ke persetujuan yang telah diselesaikan selama tidak ada persetujuan yang sudah ada pada file dengan status IN_PROGRESS.

Siklus proses persetujuan

Persetujuan melalui beberapa status selama siklus prosesnya. Gambar 1 menunjukkan langkah-langkah tingkat tinggi siklus proses persetujuan:

Mulai persetujuan. Panggil start untuk memulai permintaan persetujuan. status kemudian disetel ke IN_PROGRESS.
Persetujuan tertunda. Selama persetujuan tertunda (status ditetapkan ke IN_PROGRESS), pemrakarsa dan peninjau dapat berinteraksi dengannya. Mereka dapat menambahkan comment, pemrakarsa dapat reassign peninjau, dan satu atau beberapa peninjau dapat approve permintaan.
Persetujuan dalam status selesai. Persetujuan memasuki status selesai (status disetel ke APPROVED, CANCELLED, atau DECLINED) saat semua peninjau menyetujui permintaan, pemrakarsa memilih untuk cancel permintaan, atau jika ada peninjau yang memilih untuk decline permintaan.

Menggunakan parameter kolom

Jika ingin menentukan kolom yang akan ditampilkan dalam respons, Anda dapat menyetel parameter sistem fields dengan metode apa pun dari resource approvals. Jika Anda menghapus parameter fields, server akan menampilkan kumpulan kolom default yang khusus untuk metode tersebut. Untuk menampilkan kolom yang berbeda, lihat Menampilkan kolom tertentu.

Memulai dan mengelola persetujuan

Resource approvals dapat digunakan untuk memulai dan mengelola persetujuan menggunakan Drive API. Metode ini berfungsi dengan cakupan Drive API OAuth 2.0 yang ada dan memungkinkan penulisan metadata file. Untuk mengetahui informasi selengkapnya, lihat Memilih cakupan Google Drive API.

Mulai persetujuan

Untuk memulai persetujuan baru pada file, gunakan metode start pada resource approvals dan sertakan parameter jalur fileId.

Isi permintaan terdiri dari kolom reviewerEmails wajib diisi yang merupakan array string yang berisi alamat email peninjau yang ditugaskan untuk meninjau file. Setiap alamat email peninjau harus dikaitkan dengan Akun Google atau permintaan akan gagal. Selain itu, tiga kolom opsional ditawarkan:

dueTime: Batas waktu untuk persetujuan dalam format RFC 3339.
lockFile: Boolean yang menunjukkan apakah file akan dikunci saat memulai persetujuan. Tindakan ini akan mencegah pengguna mengubah file selama proses persetujuan. Setiap pengguna dengan izin role=writer dapat menghapus kunci ini.
message: Pesan kustom yang dikirim ke pengulas.

Isi respons berisi instance resource approvals dan menyertakan kolom initiator yang merupakan pengguna yang meminta persetujuan. Persetujuan Status disetel ke IN_PROGRESS.

Jika ada persetujuan yang sudah ada dengan Status IN_PROGRESS, metode start akan gagal. Anda hanya dapat memulai persetujuan jika tidak ada persetujuan yang ada pada file atau jika persetujuan yang ada dalam status selesai (statusnya APPROVED, CANCELLED, atau DECLINED).

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals:start' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "reviewerEmails": [
     "reviewer1@example.com",
     "reviewer2@example.com"
    ],
    "dueTime": "2026-04-01T15:01:23Z",
    "lockFile": true,
    "message": "Please review this file for approval."
 }'

Ganti kode berikut:

FILE_ID: ID file yang memerlukan persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Memberi komentar pada persetujuan

Untuk mengomentari persetujuan, gunakan metode comment pada resource approvals dan sertakan parameter jalur fileId dan approvalId.

Isi permintaan terdiri dari kolom message wajib diisi yang berupa string berisi komentar yang ingin Anda tambahkan ke persetujuan.

Isi respons berisi instance resource approvals. Pesan dikirim ke pemrakarsa dan peninjau persetujuan sebagai notifikasi, dan juga disertakan dalam log aktivitas persetujuan.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:comment' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The required comment on the approval."
 }'

Ganti kode berikut:

FILE_ID: ID file yang memerlukan persetujuan.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Menetapkan ulang peninjau saat persetujuan

Untuk menetapkan ulang peninjau pada persetujuan, gunakan metode reassign pada resource approvals dan sertakan parameter jalur fileId dan approvalId.

Metode reassign memungkinkan inisiator persetujuan (atau pengguna dengan izin role=writer) untuk menambahkan atau mengganti peninjau dalam objek ReviewerResponse dari resource approvals. Pengguna dengan izin role=reader hanya dapat menetapkan ulang persetujuan yang ditetapkan untuk dirinya sendiri. Hal ini memungkinkan pengguna menetapkan ulang permintaan kepada orang lain yang merupakan peninjau yang lebih kompeten.

Peninjau hanya dapat ditetapkan ulang saat Status adalah IN_PROGRESS dan kolom response untuk peninjau yang ditetapkan ulang disetel ke NO_RESPONSE.

Perhatikan bahwa Anda tidak dapat menghapus peninjau pada persetujuan. Jika Anda perlu menghapus peninjau, Anda harus membatalkan persetujuan dan memulai yang baru.

Isi permintaan terdiri dari kolom addReviewers dan replaceReviewers opsional. Setiap kolom memiliki objek berulang untuk AddReviewer dan ReplaceReviewer yang masing-masing berisi satu peninjau untuk ditambahkan atau sepasang peninjau untuk diganti. Anda juga dapat menambahkan kolom message opsional yang berisi komentar yang ingin Anda kirim kepada peninjau baru.

Isi respons berisi instance resource approvals. Pesan dikirim ke peninjau baru sebagai notifikasi, dan juga disertakan dalam log aktivitas persetujuan.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:reassign' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "addReviewers": [
    {
        "addedReviewerEmail": "new_reviewer@example.com"
    }
    ],
    "replaceReviewers": [
    {
        "addedReviewerEmail": "replacement_reviewer@example.com",
        "removedReviewerEmail": "old_reviewer@example.com"
    }
    ],
    "message": "Reassigning reviewers for this approval request."
 }'

Ganti kode berikut:

FILE_ID: ID file yang memerlukan persetujuan.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Membatalkan persetujuan

Untuk membatalkan persetujuan, gunakan metode cancel pada resource approvals dan sertakan parameter jalur fileId dan approvalId.

Metode cancel hanya dapat dipanggil oleh pemrakarsa persetujuan (atau pengguna dengan izin role=writer) saat Status persetujuan IN_PROGRESS.

Isi permintaan terdiri dari kolom message opsional yang merupakan string berisi pesan yang menyertai pembatalan persetujuan.

Isi respons berisi instance resource approvals. Pesan dikirim sebagai notifikasi, dan juga disertakan dalam log aktivitas persetujuan. Persetujuan Status ditetapkan ke CANCELLED dan berada dalam status selesai.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:cancel' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for cancelling this approval request."
 }'

Ganti kode berikut:

FILE_ID: ID file yang memerlukan persetujuan.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Menolak persetujuan

Untuk menolak persetujuan, gunakan metode decline pada resource approvals dan sertakan parameter jalur fileId dan approvalId.

Metode decline hanya dapat dipanggil saat persetujuan Status adalah IN_PROGRESS.

Isi permintaan terdiri dari kolom message opsional yang merupakan string berisi pesan yang menyertai penolakan persetujuan.

Isi respons berisi instance resource approvals. Pesan dikirim sebagai notifikasi, dan juga disertakan dalam log aktivitas persetujuan. Kolom response objek ReviewerResponse pengguna yang meminta ditetapkan ke DECLINED. Selain itu, persetujuan Status ditetapkan ke DECLINED dan dalam status selesai.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:decline' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for declining this approval request."
 }'

Ganti kode berikut:

FILE_ID: ID file yang memerlukan persetujuan.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Menyetujui persetujuan

Untuk menyetujui persetujuan, gunakan metode approve pada resource approvals dan sertakan parameter jalur fileId dan approvalId.

Metode approve hanya dapat dipanggil saat persetujuan Status adalah IN_PROGRESS.

Isi permintaan terdiri dari kolom message opsional yang merupakan string berisi pesan yang akan menyertai persetujuan.

Isi respons berisi instance resource approvals. Pesan dikirim sebagai notifikasi, dan juga disertakan dalam log aktivitas persetujuan. Kolom response objek ReviewerResponse pengguna yang meminta ditetapkan ke APPROVED. Selain itu, jika ini adalah respons peninjau terakhir yang diperlukan, persetujuan Status ditetapkan ke APPROVED dan statusnya selesai.

curl

curl -X POST 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID:approve' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Content-Type: application/json' \
 -d '{
    "message": "The optional reason for approving this approval request."
 }'

Ganti kode berikut:

FILE_ID: ID file yang memerlukan persetujuan.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Menemukan persetujuan yang ada

Resource approvals juga dapat digunakan untuk mendapatkan dan mencantumkan status persetujuan Anda menggunakan Drive API.

Untuk melihat persetujuan pada file, Anda harus memiliki izin untuk membaca metadata file. Untuk mengetahui informasi selengkapnya, lihat Peran dan izin.

Mendapatkan persetujuan

Untuk mendapatkan persetujuan pada file, gunakan metode get pada resource approvals dengan parameter jalur fileId dan approvalId. Jika tidak mengetahui ID persetujuan, Anda dapat mencantumkan persetujuan menggunakan metode list.

Isi respons berisi instance resource approvals.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals/APPROVAL_ID' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Ganti kode berikut:

FILE_ID: ID file yang memerlukan persetujuan.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Mencantumkan persetujuan

Untuk mencantumkan persetujuan pada file, panggil metode list pada resource approvals dan sertakan parameter jalur fileId.

Isi respons terdiri dari daftar persetujuan pada file. Kolom items mencakup informasi tentang setiap persetujuan dalam bentuk resource approvals.

Anda juga dapat meneruskan parameter kueri berikut untuk menyesuaikan penomoran halaman atau memfilter persetujuan:

pageSize: Jumlah maksimum persetujuan yang akan ditampilkan per halaman. Jika Anda tidak menetapkan pageSize, server akan menampilkan hingga 100 persetujuan.
pageToken: Token halaman, yang diterima dari panggilan daftar sebelumnya. Token ini digunakan untuk mengambil halaman berikutnya. Nilai ini harus ditetapkan ke nilai nextPageToken dari respons sebelumnya.

curl

curl -X GET 'https://www.googleapis.com/drive/v3/files/FILE_ID/approvals?pageSize=10' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'Accept: application/json'

Ganti kode berikut:

FILE_ID: ID file yang memerlukan persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Mengelola persetujuan Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Konsep

Status persetujuan

Siklus proses persetujuan

Menggunakan parameter kolom

Memulai dan mengelola persetujuan

Mulai persetujuan

curl

Memberi komentar pada persetujuan

curl

Menetapkan ulang peninjau saat persetujuan

curl

Membatalkan persetujuan

curl

Menolak persetujuan

curl

Menyetujui persetujuan

curl

Menemukan persetujuan yang ada

Mendapatkan persetujuan

curl

Mencantumkan persetujuan

curl

Topik terkait

Mengelola persetujuan