Gestire le approvazioni

Questo documento spiega come gestire le approvazioni nell'API Google Drive.

Gli utenti possono inviare documenti su Google Drive mediante un processo di approvazione formale. Puoi utilizzare questo processo per ottenere l'approvazione per una revisione del contratto o un documento ufficiale prima della pubblicazione. Un'approvazione tiene traccia dello stato della revisione (ad esempio In corso, Approvata o Rifiutata) e dei revisori coinvolti. Le approvazioni sono un ottimo modo per convalidare i contenuti e tenere traccia dei revisori.

Puoi creare e gestire le approvazioni dei contenuti in Drive. L' API Google Drive fornisce la approvals risorsa per lavorare con le approvazioni dei file. I metodi della risorsa approvals funzionano sugli elementi di Drive, Documenti Google e altri editor di Google Workspace. I revisori possono approvare o rifiutare i documenti oppure lasciare un feedback direttamente al loro interno.

Prima di iniziare

Il file deve contenere la canStartApproval funzionalità . Per controllare le funzionalità dei file, chiama il get metodo sulla risorsa files con il fileId parametro del percorso e utilizza il campo della funzionalità canStartApproval in il parametro fields. Per saperne di più, consulta Informazioni sulle funzionalità dei file.

La funzionalità booleana canStartApproval è false quando:
- Le impostazioni dell'amministratore limitano l'accesso alla funzionalità.
- La tua versione di Google Workspace non è idonea.
- Il file è di proprietà di un utente al di fuori del tuo dominio.
- L'utente non dispone dell'autorizzazione role=writer per il file.
Assicurati di condividere manualmente il file di destinazione con i revisori. Drive non esegue questa operazione automaticamente. Se un revisore non ha accesso al file, la richiesta di approvazione andrà a buon fine, ma non riceverà notifiche né potrà visualizzare il file.

Concetti

I seguenti concetti chiave costituiscono la base delle approvazioni.

Stato di approvazione

Quando richiedi l'approvazione di un documento, la procedura di approvazione garantisce che ogni revisore approvi la stessa versione dei contenuti. Se il file viene modificato dopo che un revisore ha approvato la richiesta e prima che la richiesta sia completata, le approvazioni del revisore vengono reimpostate e i revisori devono approvare la nuova versione. Se i contenuti vengono modificati dopo l'approvazione finale, sul documento viene visualizzato un banner che indica che la versione attuale è diversa da quella approvata.

La risorsa approvals include un Status oggetto che descrive in dettaglio lo stato dell'approvazione quando viene richiesta la risorsa. Include anche l' ReviewerResponse oggetto che descrive in dettaglio le risposte a un'approvazione apportata da revisori specifici. La risposta di ogni revisore è rappresentata dall'oggetto Response.

Ogni azione nella procedura di approvazione genera notifiche via email che vengono inviate all'iniziatore (l'utente che richiede l'approvazione) e a tutti i revisori. Viene anche aggiunto al log delle attività di approvazione.

Tutti i revisori devono approvare un'approvazione. Se un revisore rifiuta un'approvazione, lo stato completato viene impostato su DECLINED.

Una volta completata un'approvazione (lo stato è APPROVED, CANCELLED o DECLINED), rimane nello stato completato e l'iniziatore o i revisori non possono interagire con essa. Puoi aggiungere commenti a un'approvazione completata a condizione che non esista un'approvazione in corso su un file con stato IN_PROGRESS.

Ciclo di vita di un'approvazione

Un'approvazione passa attraverso diversi stati durante il suo ciclo di vita. La figura 1 mostra i passaggi di alto livello del ciclo di vita di un'approvazione:

Avvia l'approvazione. Chiama start per avviare la richiesta di approvazione. Lo status viene quindi impostato su IN_PROGRESS.
L'approvazione è in attesa. Mentre l'approvazione è in attesa (status è impostato su IN_PROGRESS), sia l'iniziatore sia i revisori possono interagire con essa. Possono aggiungere un comment, l'iniziatore può reassign i revisori e uno o più revisori possono approve la richiesta.
L'approvazione è nello stato completato. Un'approvazione entra nello stato completato (status è impostato su APPROVED, CANCELLED o DECLINED) quando tutti i revisori approvano la richiesta, l'iniziatore sceglie di cancel la richiesta o se un revisore sceglie di decline la richiesta.

Utilizzare il parametro fields

Se vuoi specificare i campi da restituire nella risposta, puoi impostare il fields parametro di sistema con qualsiasi metodo della ris3/} risorsa.approvals Se ometti il parametro fields, il server restituisce un insieme predefinito di campi specifici per il metodo. Per restituire campi diversi, consulta Restituire campi specifici.

Avviare e amministrare le approvazioni

La risorsa approvals può essere utilizzata per avviare e gestire le approvazioni utilizzando l'API Drive. Questi metodi funzionano con uno qualsiasi degli ambiti dell'API Drive OAuth 2.0 esistenti che consentono di scrivere i metadati dei file. Per saperne di più, consulta Scegliere gli ambiti dell'API Google Drive.

Avviare l'approvazione

Per avviare una nuova approvazione su un file, utilizza il start metodo sulla approvals risorsa e includi il fileId parametro del percorso.

Il corpo della richiesta è costituito da un campo obbligatorio reviewerEmails, ovvero un array di stringhe contenente gli indirizzi email dei revisori assegnati alla revisione del file. Ogni indirizzo email del revisore deve essere associato a un Account Google, altrimenti la richiesta non andrà a buon fine. Inoltre, vengono offerti tre campi facoltativi:

dueTime: la scadenza per l'approvazione in formato RFC 3339.
lockFile: un valore booleano che indica se bloccare il file all'avvio dell'approvazione. In questo modo, gli utenti non possono modificare il file durante la procedura di approvazione. Qualsiasi utente con l'autorizzazione role=writer può rimuovere questo blocco.
message: un messaggio personalizzato inviato ai revisori.

Il corpo della risposta contiene un'istanza della risorsa approvals e include il initiator campo che è l'utente che ha richiesto l'approvazione. Lo Status dell'approvazione è impostato su IN_PROGRESS.

Se è presente un'approvazione esistente con Status IN_PROGRESS, il metodo start non va a buon fine. Puoi avviare un'approvazione solo se non esiste un'approvazione sul file o se l'approvazione esistente è nello stato completato (lo stato è APPROVED, CANCELLED o 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."
 }'

Sostituisci quanto segue:

FILE_ID: l'ID del file su cui è presente l'approvazione.
ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Commentare l'approvazione

Per commentare un'approvazione, utilizza il comment metodo sulla risorsa approvals e includi i parametri del percorso fileId e approvalId.

Il corpo della richiesta è costituito da un campo obbligatorio message, ovvero una stringa contenente il commento che vuoi aggiungere all'approvazione.

Il corpo della risposta contiene un'istanza della risorsa approvals. Il messaggio viene inviato all'iniziatore e ai revisori dell'approvazione come notifica e viene incluso anche nel log delle attività di approvazione.

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."
 }'

Sostituisci quanto segue:

FILE_ID: l'ID del file su cui è presente l'approvazione.
APPROVAL_ID: l'ID dell'approvazione.
ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Riassegnare i revisori all'approvazione

Per riassegnare i revisori a un'approvazione, utilizza il reassign metodo sulla approvals risorsa e includi i fileId e approvalId parametri del percorso.

Il metodo reassign consente all'iniziatore dell'approvazione (o a un utente con l' role=writer autorizzazione) di aggiungere o sostituire i revisori nell' ReviewerResponse oggetto di la risorsa approvals. Un utente con l'autorizzazione role=reader può riassegnare solo un'approvazione assegnata a se stesso. In questo modo, l'utente può riassegnare una richiesta a un altro revisore più competente.

I revisori possono essere riassegnati solo se lo Status è IN_PROGRESS e il campo response del revisore riassegnato è impostato su NO_RESPONSE.

Tieni presente che non puoi rimuovere un revisore da un'approvazione. Se devi rimuovere un revisore, devi annullare l'approvazione e avviarne una nuova.

Il corpo della richiesta è costituito dai campi facoltativi addReviewers e replaceReviewers. Ogni campo ha un oggetto ripetuto per AddReviewer e ReplaceReviewer ognuno dei quali contiene un singolo revisore da aggiungere o una coppia di revisori da sostituire. Puoi anche aggiungere il campo facoltativo message contenente il commento che vuoi inviare ai nuovi revisori.

Il corpo della risposta contiene un'istanza della risorsa approvals. Il messaggio viene inviato ai nuovi revisori come notifica e viene incluso anche nel log delle attività di approvazione.

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."
 }'

Sostituisci quanto segue:

FILE_ID: l'ID del file su cui è presente l'approvazione.
APPROVAL_ID: l'ID dell'approvazione.
ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Annullare l'approvazione

Per annullare un'approvazione, utilizza il cancel metodo sulla risorsa approvals e includi i parametri del percorso fileId e approvalId.

Il metodo cancel può essere chiamato solo dall'iniziatore dell'approvazione (o da un utente con l'autorizzazione role=writer) mentre l'approvazione Status è IN_PROGRESS.

Il corpo della richiesta è costituito da un campo facoltativo message, ovvero una stringa contenente il messaggio da accompagnare all'annullamento dell'approvazione.

Il corpo della risposta contiene un'istanza della risorsa approvals. Il messaggio viene inviato come notifica e viene incluso anche nel log delle attività di approvazione. Lo Status dell'approvazione è impostato su CANCELLED ed è nello stato completato.

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."
 }'

Sostituisci quanto segue:

FILE_ID: l'ID del file su cui è presente l'approvazione.
APPROVAL_ID: l'ID dell'approvazione.
ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Rifiutare l'approvazione

Per rifiutare un'approvazione, utilizza il decline metodo sulla approvals risorsa e includi i fileId e approvalId parametri del percorso.

Il metodo decline può essere chiamato solo se lo Status dell'approvazione è IN_PROGRESS.

Il corpo della richiesta è costituito da un campo facoltativo message, ovvero una stringa contenente il messaggio da accompagnare al rifiuto dell'approvazione.

Il corpo della risposta contiene un'istanza della risorsa approvals. Il messaggio viene inviato come notifica e viene incluso anche nel log delle attività di approvazione. Il response campo dell'ReviewerResponse oggetto dell'utente richiedente è impostato su DECLINED. Inoltre, lo Status dell'approvazione è impostato su DECLINED ed è nello stato completato.

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."
 }'

Sostituisci quanto segue:

FILE_ID: l'ID del file su cui è presente l'approvazione.
APPROVAL_ID: l'ID dell'approvazione.
ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Approvare l'approvazione

Per approvare un'approvazione, utilizza il approve metodo sulla risorsa approvals e includi i parametri del percorso fileId e approvalId.

Il metodo approve può essere chiamato solo se lo Status dell'approvazione è IN_PROGRESS.

Il corpo della richiesta è costituito da un campo facoltativo message, ovvero una stringa contenente il messaggio da accompagnare all'approvazione.

Il corpo della risposta contiene un'istanza della risorsa approvals. Il messaggio viene inviato come notifica e viene incluso anche nel log delle attività di approvazione. Il response campo dell'ReviewerResponse oggetto dell'utente richiedente è impostato su APPROVED. Inoltre, se questa è l'ultima risposta del revisore richiesta, lo Status dell'approvazione viene impostato su APPROVED ed è nello stato completato.

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."
 }'

Sostituisci quanto segue:

FILE_ID: l'ID del file su cui è presente l'approvazione.
APPROVAL_ID: l'ID dell'approvazione.
ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Individuare le approvazioni esistenti

La risorsa approvals può essere utilizzata anche per ottenere ed elencare lo stato delle approvazioni utilizzando l'API Drive.

Per visualizzare le approvazioni su un file, devi disporre dell'autorizzazione per leggere i metadati del file. Per saperne di più, consulta Ruoli e autorizzazioni.

Ottenere l'approvazione

Per ottenere un'approvazione su un file, utilizza il get metodo sulla risorsa approvals con i parametri del percorso fileId e approvalId. Se non conosci l'ID dell'approvazione, puoi elencare le approvazioni utilizzando il metodo list.

Il corpo della risposta contiene un'istanza della risorsa 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'

Sostituisci quanto segue:

FILE_ID: l'ID del file su cui è presente l'approvazione.
APPROVAL_ID: l'ID dell'approvazione.
ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Elencare le approvazioni

Per elencare le approvazioni su un file, chiama il list metodo sulla risorsa approvals e includi il parametro del percorso fileId.

Il corpo della risposta è costituito da un elenco di approvazioni sul file. Il campo items include informazioni su ogni approvazione sotto forma di risorsa approvals.

Puoi anche passare i seguenti parametri di query per personalizzare la paginazione o filtrare le approvazioni:

pageSize: il numero massimo di approvazioni da restituire per pagina. Se non imposti pageSize, il server restituisce fino a 100 approvazioni.
pageToken: un token di pagina ricevuto da una precedente chiamata dell'elenco. Questo token viene utilizzato per recuperare la pagina successiva. Deve essere impostato sul valore di nextPageToken di una risposta precedente.

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'

Sostituisci quanto segue:

FILE_ID: l'ID del file su cui è presente l'approvazione.
ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Gestire le approvazioni Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Concetti

Stato di approvazione

Ciclo di vita di un'approvazione

Utilizzare il parametro fields

Avviare e amministrare le approvazioni

Avviare l'approvazione

curl

Commentare l'approvazione

curl

Riassegnare i revisori all'approvazione

curl

Annullare l'approvazione

curl

Rifiutare l'approvazione

curl

Approvare l'approvazione

curl

Individuare le approvazioni esistenti

Ottenere l'approvazione

curl

Elencare le approvazioni

curl

Argomenti correlati

Gestire le approvazioni