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 tepat 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 tersebut.
- Edisi Google Workspace Anda tidak memenuhi syarat.
- File tersebut dimiliki oleh pengguna di luar domain Anda.
- Pengguna tidak memiliki izin role=writer pada file tersebut.
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 dapat memberikan masukan pada dokumen.

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.

Perilaku persetujuan saat konten file diubah saat persetujuan Status adalah IN_PROGRESS ditentukan oleh fileContentChangeBehavior kolom dari approvals resource. Perilaku berikut dapat diterapkan:

RESET_APPROVAL: Proses persetujuan memastikan setiap peninjau menyetujui versi konten yang sama. Jika file diedit setelah peninjau menyetujui permintaan, dan sebelum permintaan selesai, persetujuan peninjau akan direset (respons ditetapkan kembali ke NO_RESPONSE), dan peninjau harus menyetujui versi baru. Jika persetujuan memiliki status APPROVED, file akan dikunci untuk mencegah modifikasi lebih lanjut. Pengeditan konten tambahan setelah persetujuan akhir akan menyebabkan banner muncul di dokumen yang menunjukkan bahwa versi saat ini berbeda dengan versi yang disetujui. Ini merupakan perilaku default.
NO_APPROVAL_ACTION: Pengeditan pada konten file tidak mereset keputusan peninjau saat persetujuan tertunda. Selain itu, file tidak dikunci pada persetujuan akhir. Peninjau juga dapat mereset keputusan APPROVED mereka sendiri kembali ke status tertunda (respons ditetapkan kembali ke NO_RESPONSE) kapan saja sebelum persetujuan selesai.

Setelah persetujuan selesai, perilaku ini tidak lagi berlaku.

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 adalah 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 tertunda. Saat 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 saat (status ditetapkan ke APPROVED, CANCELLED atau DECLINED) 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 resource approvals apa pun. 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 yang 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 wajib reviewerEmails 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, empat 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 memblokir pengguna untuk mengubah file selama proses persetujuan. Pengguna yang memiliki izin role=writer dapat menghapus kunci ini.
message: Pesan kustom yang dikirim ke peninjau.
fileContentChangeBehavior: Perilaku persetujuan saat konten file berubah. Nilai yang didukung adalah:
- RESET_APPROVAL: (Default) Mereset respons peninjau APPROVED ke NO_RESPONSE saat konten berubah saat persetujuan sedang berlangsung. File akan dikunci setelah persetujuan selesai dengan status APPROVED.
- NO_APPROVAL_ACTION: Tidak mereset respons peninjau saat konten berubah, dan tidak mengunci file saat persetujuan selesai.

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 adalah 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.",
    "fileContentChangeBehavior": "RESET_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 wajib yang 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