Gérer les approbations

Ce document explique comment gérer les approbations dans l'API Google Drive.

Les utilisateurs peuvent envoyer des documents dans Google Drive via un processus d'approbation officiel. Vous pouvez suivre cette procédure pour obtenir l'approbation d'un examen de contrat ou d'un document officiel avant sa publication. Une approbation permet de suivre l'état de l'examen (par exemple, "En cours", "Approuvé" ou "Refusé") et les examinateurs concernés. Les approbations sont un excellent moyen de valider le contenu et de conserver un enregistrement des réviseurs.

Vous pouvez créer et gérer des approbations de contenu dans Drive. L'API Google Drive fournit la ressource approvals pour gérer les approbations de fichiers. Les méthodes de la ressource approvals fonctionnent sur les éléments de Drive, Google Docs et d'autres éditeurs Google Workspace. Les examinateurs peuvent approuver ou rejeter des documents, ou y laisser des commentaires directement.

Avant de commencer

  1. Votre fichier doit contenir la fonctionnalité canStartApproval . Pour vérifier les capacités d'un fichier, appelez la méthode get sur la ressource files avec le paramètre de chemin d'accès fileId, puis utilisez le champ de capacité canStartApproval dans le paramètre fields. Pour en savoir plus, consultez Comprendre les fonctionnalités des fichiers.

    La fonctionnalité booléenne canStartApproval est false lorsque :

    • Les paramètres administrateur restreignent l'accès à la fonctionnalité.
    • Votre édition Google Workspace n'est pas éligible.
    • Le fichier appartient à un utilisateur extérieur à votre domaine.
    • L'utilisateur ne dispose pas de l'autorisation role=writer sur le fichier.

  2. Assurez-vous de partager manuellement le fichier cible avec les réviseurs. Drive n'effectue pas cette opération automatiquement. Si un examinateur n'a pas accès au fichier, la demande d'approbation sera acceptée, mais il ne recevra pas de notifications et ne pourra pas consulter le fichier.

Concepts

Les concepts clés suivants constituent la base des approbations.

État d'approbation

Lorsque vous demandez l'approbation d'un document, le processus d'approbation garantit que chaque examinateur approuve la même version du contenu. Si le fichier est modifié après qu'un examinateur a approuvé la demande, et avant qu'elle soit traitée, les approbations de l'examinateur sont réinitialisées et les examinateurs doivent approuver la nouvelle version. Si le contenu est modifié après l'approbation finale, une bannière s'affiche sur le document pour indiquer que la version actuelle diffère de celle approuvée.

La ressource approvals inclut un objet Status qui détaille l'état de l'approbation lorsque la ressource est demandée. Il inclut également l'objet ReviewerResponse qui détaille les réponses à une approbation effectuée par des réviseurs spécifiques. La réponse de chaque réviseur est représentée par l'objet Response.

Chaque action du processus d'approbation génère des notifications par e-mail qui sont envoyées à l'initiateur (l'utilisateur qui demande l'approbation) et à tous les réviseurs. Elle est également ajoutée au journal d'activité d'approbation.

Tous les examinateurs doivent approuver une approbation. Si un examinateur refuse une approbation, l'état de la tâche passe à DECLINED.

Une fois une approbation terminée (état APPROVED, CANCELLED ou DECLINED), elle reste dans cet état et l'initiateur ou les examinateurs ne peuvent plus interagir avec elle. Vous pouvez ajouter des commentaires à une approbation terminée tant qu'il n'existe pas d'approbation pour un fichier dont l'état est IN_PROGRESS.

Cycle de vie d'une approbation

Cycle de vie d'une approbation.
Figure 1. Cycle de vie d'une approbation

Une approbation passe par plusieurs états au cours de son cycle de vie. La figure 1 montre les étapes générales d'un cycle de vie d'approbation :

  1. Démarrez l'approbation. Appelez start pour lancer la demande d'approbation. status est ensuite défini sur IN_PROGRESS.

  2. L'approbation est en attente. Tant que l'approbation est en attente (status défini sur IN_PROGRESS), l'initiateur et les réviseurs peuvent interagir avec elle. Ils peuvent ajouter un comment, l'initiateur peut reassign des examinateurs, et un ou plusieurs examinateurs peuvent approve la demande.

  3. L'approbation est à l'état "Terminée". Une approbation passe à l'état "Terminé" (status est défini sur APPROVED, CANCELLED ou DECLINED) lorsque tous les examinateurs approuvent la demande, que l'initiateur choisit de cancel la demande ou si un examinateur choisit de decline la demande.

Utiliser le paramètre "fields"

Si vous souhaitez spécifier les champs à renvoyer dans la réponse, vous pouvez définir le paramètre système fields avec n'importe quelle méthode de la ressource approvals. Si vous omettez le paramètre fields, le serveur renvoie un ensemble de champs par défaut spécifiques à la méthode. Pour renvoyer différents champs, consultez Renvoyer des champs spécifiques.

Démarrer et gérer les approbations

La ressource approvals peut être utilisée pour démarrer et gérer les approbations à l'aide de l'API Drive. Ces méthodes fonctionnent avec tous les champs d'application de l'API Drive OAuth 2.0 existants qui permettent d'écrire des métadonnées de fichier. Pour en savoir plus, consultez Choisir les habilitations de l'API Google Drive.

Démarrer une approbation

Pour démarrer une nouvelle approbation sur un fichier, utilisez la méthode start sur la ressource approvals et incluez le paramètre de chemin d'accès fileId.

Le corps de la requête se compose d'un champ reviewerEmails obligatoire, qui est un tableau de chaînes contenant les adresses e-mail des réviseurs chargés d'examiner le fichier. Chaque adresse e-mail de réviseur doit être associée à un compte Google, sans quoi la demande échouera. Trois champs facultatifs sont également proposés :

  • dueTime : date limite d'approbation au format RFC 3339.
  • lockFile : valeur booléenne indiquant si le fichier doit être verrouillé au début de l'approbation. Cela empêche les utilisateurs de modifier le fichier pendant le processus d'approbation. Tout utilisateur disposant de l'autorisation role=writer peut supprimer ce verrou.
  • message : message personnalisé envoyé aux réviseurs.

Le corps de la réponse contient une instance de la ressource approvals et inclut le champ initiator, qui correspond à l'utilisateur ayant demandé l'approbation. L'approbation Status est définie sur IN_PROGRESS.

Si une approbation existante est présente avec un Status de IN_PROGRESS, la méthode start échoue. Vous ne pouvez lancer une approbation que si aucune approbation n'existe déjà pour le fichier ou si l'approbation existante est terminée (état APPROVED, CANCELLED ou 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."
 }'

Remplacez les éléments suivants :

  • FILE_ID : ID du fichier sur lequel porte l'approbation.
  • ACCESS_TOKEN : jeton OAuth 2.0 de votre application.

Commenter une approbation

Pour commenter une approbation, utilisez la méthode comment sur la ressource approvals et incluez les paramètres de chemin d'accès fileId et approvalId.

Le corps de la requête se compose d'un champ message obligatoire qui est une chaîne contenant le commentaire que vous souhaitez ajouter à l'approbation.

Le corps de la réponse contient une instance de la ressource approvals. Le message est envoyé au demandeur et aux réviseurs sous forme de notification. Il est également inclus dans le journal d'activité des approbations.

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

Remplacez les éléments suivants :

  • FILE_ID : ID du fichier sur lequel porte l'approbation.
  • APPROVAL_ID : ID de l'approbation.
  • ACCESS_TOKEN : jeton OAuth 2.0 de votre application.

Réattribuer des examinateurs lors de l'approbation

Pour réattribuer des réviseurs à une approbation, utilisez la méthode reassign sur la ressource approvals et incluez les paramètres de chemin d'accès fileId et approvalId.

La méthode reassign permet à l'initiateur de l'approbation (ou à un utilisateur disposant de l'autorisation role=writer) d'ajouter ou de remplacer des réviseurs dans l'objet ReviewerResponse de la ressource approvals. Un utilisateur disposant de l'autorisation role=reader ne peut réattribuer qu'une approbation qui lui est attribuée. Cela permet à l'utilisateur de réattribuer une demande à un autre examinateur plus compétent.

Les réviseurs ne peuvent être réaffectés que lorsque l'Status est défini sur IN_PROGRESS et que le champ response du réviseur réaffecté est défini sur NO_RESPONSE.

Notez que vous ne pouvez pas supprimer un réviseur d'une approbation. Si vous devez supprimer un réviseur, vous devez annuler l'approbation et en démarrer une nouvelle.

Le corps de la requête se compose des champs facultatifs addReviewers et replaceReviewers. Chaque champ comporte un objet répété pour AddReviewer et ReplaceReviewer, qui contiennent chacun un seul examinateur à ajouter ou une paire d'examinateurs à remplacer. Vous pouvez également ajouter le champ facultatif message contenant le commentaire que vous souhaitez envoyer aux nouveaux examinateurs.

Le corps de la réponse contient une instance de la ressource approvals. Le message est envoyé aux nouveaux réviseurs sous forme de notification. Il est également inclus dans le journal d'activité des approbations.

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

Remplacez les éléments suivants :

  • FILE_ID : ID du fichier sur lequel porte l'approbation.
  • APPROVAL_ID : ID de l'approbation.
  • ACCESS_TOKEN : jeton OAuth 2.0 de votre application.

Annuler l'approbation

Pour annuler une approbation, utilisez la méthode cancel sur la ressource approvals et incluez les paramètres de chemin d'accès fileId et approvalId.

La méthode cancel ne peut être appelée que par l'initiateur de l'approbation (ou un utilisateur disposant de l'autorisation role=writer) lorsque l'approbation Status est IN_PROGRESS.

Le corps de la requête se compose d'un champ message facultatif qui est une chaîne contenant le message accompagnant l'annulation de l'approbation.

Le corps de la réponse contient une instance de la ressource approvals. Le message est envoyé sous forme de notification et est également inclus dans le journal d'activité des approbations. L'approbation Status est définie sur CANCELLED et son état est "Terminé".

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

Remplacez les éléments suivants :

  • FILE_ID : ID du fichier sur lequel porte l'approbation.
  • APPROVAL_ID : ID de l'approbation.
  • ACCESS_TOKEN : jeton OAuth 2.0 de votre application.

Refuser l'approbation

Pour refuser une approbation, utilisez la méthode decline sur la ressource approvals et incluez les paramètres de chemin d'accès fileId et approvalId.

La méthode decline ne peut être appelée que lorsque l'état de l'approbation Status est IN_PROGRESS.

Le corps de la requête se compose d'un champ message facultatif qui est une chaîne contenant le message accompagnant le refus de l'approbation.

Le corps de la réponse contient une instance de la ressource approvals. Le message est envoyé sous forme de notification et est également inclus dans le journal d'activité des approbations. Le champ response de l'objet ReviewerResponse de l'utilisateur qui effectue la demande est défini sur DECLINED. De plus, l'approbation Status est définie sur DECLINED et est à l'état "Terminé".

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

Remplacez les éléments suivants :

  • FILE_ID : ID du fichier sur lequel porte l'approbation.
  • APPROVAL_ID : ID de l'approbation.
  • ACCESS_TOKEN : jeton OAuth 2.0 de votre application.

Approuver l'approbation

Pour approuver une approbation, utilisez la méthode approve sur la ressource approvals et incluez les paramètres de chemin d'accès fileId et approvalId.

La méthode approve ne peut être appelée que lorsque l'état de l'approbation Status est IN_PROGRESS.

Le corps de la requête se compose d'un champ message facultatif qui est une chaîne contenant le message à joindre à l'approbation.

Le corps de la réponse contient une instance de la ressource approvals. Le message est envoyé sous forme de notification et est également inclus dans le journal d'activité des approbations. Le champ response de l'objet ReviewerResponse de l'utilisateur qui effectue la demande est défini sur APPROVED. De plus, s'il s'agit de la dernière réponse requise de l'examinateur, l'approbation Status est définie sur APPROVED et l'état est "Terminé".

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

Remplacez les éléments suivants :

  • FILE_ID : ID du fichier sur lequel porte l'approbation.
  • APPROVAL_ID : ID de l'approbation.
  • ACCESS_TOKEN : jeton OAuth 2.0 de votre application.

Localiser les approbations existantes

La ressource approvals peut également être utilisée pour obtenir et lister l'état de vos approbations à l'aide de l'API Drive.

Pour afficher les approbations d'un fichier, vous devez être autorisé à lire ses métadonnées. Pour en savoir plus, consultez Rôles et autorisations.

Obtenir l'approbation

Pour obtenir une approbation sur un fichier, utilisez la méthode get sur la ressource approvals avec les paramètres de chemin d'accès fileId et approvalId. Si vous ne connaissez pas l'ID d'approbation, vous pouvez lister les approbations à l'aide de la méthode list.

Le corps de la réponse contient une instance de la ressource 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'

Remplacez les éléments suivants :

  • FILE_ID : ID du fichier sur lequel porte l'approbation.
  • APPROVAL_ID : ID de l'approbation.
  • ACCESS_TOKEN : jeton OAuth 2.0 de votre application.

Lister les approbations

Pour lister les approbations sur un fichier, appelez la méthode list sur la ressource approvals et incluez le paramètre de chemin d'accès fileId.

Le corps de la réponse se compose d'une liste des approbations du fichier. Le champ items inclut des informations sur chaque approbation sous la forme d'une ressource approvals.

Vous pouvez également transmettre les paramètres de requête suivants pour personnaliser la pagination ou filtrer les approbations :

  • pageSize : nombre maximal d'approbations à renvoyer par page. Si vous ne définissez pas pageSize, le serveur renvoie jusqu'à 100 approbations.

  • pageToken : jeton de page reçu d'un appel de liste précédent. Ce jeton permet de récupérer la page suivante. Elle doit être définie sur la valeur de nextPageToken d'une réponse précédente.

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'

Remplacez les éléments suivants :

  • FILE_ID : ID du fichier sur lequel porte l'approbation.
  • ACCESS_TOKEN : jeton OAuth 2.0 de votre application.