Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 atas 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. The Google Drive API menyediakan approvals resource untuk menangani 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 di 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 akan memastikan setiap peninjau menyetujui versi konten 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 menyertakan objek Status yang menjelaskan status persetujuan saat resource diminta. Resource ini juga menyertakan objek ReviewerResponse yang menjelaskan respons terhadap persetujuan yang dibuat oleh peninjau tertentu. Respons setiap peninjau diwakili oleh objek Response.

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

Semua peninjau harus menyetujui persetujuan. 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 diinteraksikan oleh pemrakarsa atau peninjau. Anda dapat menambahkan komentar ke persetujuan yang telah selesai selama tidak ada persetujuan yang ada pada file dengan status IN_PROGRESS.

Siklus proses persetujuan

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

Memulai persetujuan. Panggil start untuk memulai permintaan persetujuan. status kemudian ditetapkan ke IN_PROGRESS.
Persetujuan menunggu keputusan. Saat persetujuan menunggu keputusan (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 akan memasuki status selesai saat (status ditetapkan ke APPROVED, CANCELLED atau DECLINED) saat semua peninjau menyetujui permintaan, pemrakarsa memilih untuk cancel permintaan, atau jika peninjau memilih untuk decline permintaan.

Menggunakan parameter kolom

Jika ingin menentukan kolom yang akan ditampilkan dalam respons, Anda dapat menetapkan fields parameter sistem 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.

Memulai persetujuan

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

Isi permintaan terdiri dari kolom reviewerEmails yang wajib dan 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 persetujuan dalam format RFC 3339.
lockFile: Boolean yang menunjukkan apakah akan mengunci file saat memulai persetujuan. Tindakan ini akan mencegah pengguna mengubah file selama proses persetujuan. Pengguna yang memiliki izin role=writer dapat menghapus kunci ini.
message: Pesan kustom yang dikirim ke peninjau.

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

Jika persetujuan yang ada memiliki 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 disetujui.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Memberikan komentar pada persetujuan

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

Isi permintaan terdiri dari kolom message yang wajib dan merupakan string yang 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 disetujui.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Menetapkan ulang peninjau pada persetujuan

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

Metode reassign memungkinkan pemrakarsa 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 response kolom untuk peninjau yang ditetapkan ulang ditetapkan ke NO_RESPONSE.

Perhatikan bahwa Anda tidak dapat menghapus peninjau pada persetujuan. Jika 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 untukAddReviewerdanReplaceRevieweryang 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 ke 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 disetujui.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Membatalkan persetujuan

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

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

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

Isi respons berisi instance resource approvals. Pesan dikirim sebagai notifikasi, dan juga disertakan dalam log aktivitas persetujuan. Status persetujuan ditetapkan ke CANCELLED dan 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 disetujui.
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 Status persetujuan adalah IN_PROGRESS.

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

Isi respons berisi instance resource approvals. Pesan dikirim sebagai notifikasi, dan juga disertakan dalam log aktivitas persetujuan. Kolom response dari objek ReviewerResponse pengguna yang meminta ditetapkan ke DECLINED. Selain itu, Status persetujuan 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 disetujui.
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 Status persetujuan adalah IN_PROGRESS.

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

Isi respons berisi instance resource approvals. Pesan dikirim sebagai notifikasi, dan juga disertakan dalam log aktivitas persetujuan. Kolom response dari objek ReviewerResponse pengguna yang meminta ditetapkan ke APPROVED. Selain itu, jika ini adalah respons peninjau terakhir yang diperlukan, Status persetujuan ditetapkan ke APPROVED dan dalam status 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 disetujui.
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 get metode 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 disetujui.
APPROVAL_ID: ID persetujuan.
ACCESS_TOKEN: Token OAuth 2.0 aplikasi Anda.

Mencantumkan persetujuan

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

Isi respons terdiri dari daftar persetujuan pada file. Kolom items menyertakan 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. Token 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 disetujui.
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

Memulai persetujuan

curl

Memberikan komentar pada persetujuan

curl

Menetapkan ulang peninjau pada 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