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 la revisione di un contratto o per un documento ufficiale prima della pubblicazione. Un'approvazione tiene traccia dello stato della revisione (ad esempio In corso, Approvato o Rifiutato) 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 risorsa approvals per lavorare con le approvazioni dei file. I metodi della risorsa approvals funzionano su elementi all'interno di Drive, Google Docs e altri editor di Google Workspace. I revisori possono approvare o rifiutare i documenti oppure lasciare un feedback direttamente.

Prima di iniziare

  1. Il file deve contenere la funzionalità canStartApproval . Per controllare le funzionalità del file, chiama il metodo get sulla risorsa files con il parametro di percorso fileId e utilizza il campo della funzionalità canStartApproval nel parametro fields. Per saperne di più, vedi 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 esterno al tuo dominio.
    • L'utente non dispone dell'autorizzazione role=writer per il file.

  2. Assicurati di condividere manualmente il file di destinazione con i revisori. Drive non compie automaticamente questa operazione. Se un revisore non ha accesso al file, la richiesta di approvazione andrà a buon fine, ma non riceverà notifiche e non 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 approva la richiesta e prima che la richiesta venga 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 oggetto Status che descrive in dettaglio lo stato dell'approvazione quando viene richiesta la risorsa. Include anche l'oggetto ReviewerResponse che descrive in dettaglio le risposte a un'approvazione effettuata 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 inoltre aggiunto al log delle attività di approvazione.

Tutti i revisori devono approvare un'approvazione. Qualsiasi revisore che rifiuta un'approvazione imposta lo stato completato su DECLINED.

Una volta completata un'approvazione (lo stato è APPROVED, CANCELLED o DECLINED), rimane nello stato completato e non può essere modificata dall'iniziatore o dai revisori. Puoi aggiungere commenti a un'approvazione completata, a condizione che non esista un'approvazione su un file con stato IN_PROGRESS.

Ciclo di vita di un'approvazione

Il ciclo di vita di un'approvazione.
Figura 1. Il 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 di un ciclo di vita di approvazione:

  1. Avvia l'approvazione. Chiama il numero start per avviare la richiesta di approvazione. status viene quindi impostato su IN_PROGRESS.

  2. L'approvazione è in attesa. Mentre l'approvazione è in attesa (status è impostato su IN_PROGRESS), sia l'iniziatore sia i revisori possono interagire con essa. Può aggiungere un comment, l'iniziatore può reassign i revisori e uno o più revisori possono approve la richiesta.

  3. L'approvazione è nello stato Completata. Un'approvazione entra nello stato completato (status è impostato su APPROVED, CANCELLED o DECLINED) quando tutti i revisori approvano la richiesta, il richiedente 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 risorsa approvals. Se ometti il parametro fields, il server restituisce un insieme predefinito di campi specifici per il metodo. Per restituire campi diversi, vedi 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 qualsiasi ambito dell'API Drive OAuth 2.0 esistente che consente di scrivere metadati dei file. Per saperne di più, vedi Scegliere gli ambiti dell'API Google Drive.

Avvia approvazione

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

Il corpo della richiesta è costituito da un campo reviewerEmails obbligatorio che è un array di stringhe contenente gli indirizzi email dei revisori incaricati di esaminare il 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 nel 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 campo initiator, ovvero l'utente che ha richiesto l'approvazione. L'approvazione Status è impostata su IN_PROGRESS.

Se è presente un'approvazione esistente con un Status di IN_PROGRESS, il metodo start non va a buon fine. Puoi avviare un'approvazione solo se non esiste un'approvazione esistente 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 si basa l'approvazione.
  • ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Commento sull'approvazione

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

Il corpo della richiesta è costituito da un campo message obbligatorio che è 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 dell'approvazione e ai revisori come notifica ed è anche incluso nel log 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 si basa 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 metodo reassign sulla risorsa approvals e includi i parametri di percorso fileId e approvalId.

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

I revisori possono essere riassegnati solo se lo stato Status è IN_PROGRESS e il campo response per il revisore che viene 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 iniziarne una nuova.

Il corpo della richiesta è composto dai campi facoltativi addReviewers e replaceReviewers. Ogni campo ha un oggetto ripetuto per AddReviewer e ReplaceReviewer, che contengono 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 ed è 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 si basa l'approvazione.
  • APPROVAL_ID: l'ID dell'approvazione.
  • ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Annulla approvazione

Per annullare un'approvazione, utilizza il metodo cancel nella risorsa approvals e includi i parametri di 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 message facoltativo che è una stringa contenente il messaggio da allegare all'annullamento dell'approvazione.

Il corpo della risposta contiene un'istanza della risorsa approvals. Il messaggio viene inviato come notifica ed è incluso anche nel log attività di approvazione. L'approvazione Status è impostata su CANCELLED e si trova 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 si basa l'approvazione.
  • APPROVAL_ID: l'ID dell'approvazione.
  • ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Rifiuta approvazione

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

Il metodo decline può essere chiamato solo mentre l'approvazione Status è IN_PROGRESS.

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

Il corpo della risposta contiene un'istanza della risorsa approvals. Il messaggio viene inviato come notifica ed è incluso anche nel log attività di approvazione. Il campo response dell'oggetto ReviewerResponse dell'utente richiedente è impostato su DECLINED. Inoltre, l'approvazione Status è impostata su DECLINED ed è in 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 si basa l'approvazione.
  • APPROVAL_ID: l'ID dell'approvazione.
  • ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Approva approvazione

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

Il metodo approve può essere chiamato solo mentre l'approvazione Status è IN_PROGRESS.

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

Il corpo della risposta contiene un'istanza della risorsa approvals. Il messaggio viene inviato come notifica ed è incluso anche nel log attività di approvazione. Il campo response dell'oggetto ReviewerResponse dell'utente richiedente è impostato su APPROVED. Inoltre, se questa è l'ultima risposta richiesta del revisore, l'approvazione Status viene impostata su APPROVED e si trova 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 si basa 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 e elencare lo stato delle tue approvazioni utilizzando l'API Drive.

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

Ottenere l'approvazione

Per ottenere un'approvazione per un file, utilizza il metodo get sulla risorsa approvals con i parametri di percorso fileId e approvalId. Se non conosci l'ID 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 si basa l'approvazione.
  • APPROVAL_ID: l'ID dell'approvazione.
  • ACCESS_TOKEN: il token OAuth 2.0 della tua app.

Elenco approvazioni

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

Il corpo della risposta è costituito da un elenco di approvazioni del 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 si basa l'approvazione.
  • ACCESS_TOKEN: il token OAuth 2.0 della tua app.