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 suit l'état de l'examen (par exemple, "En cours", "Approuvé" ou "Refusé") et les examinateurs impliqués. Les approbations sont un excellent moyen de valider le contenu et de conserver un enregistrement des examinateurs.

Vous pouvez créer et gérer les 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

Votre fichier doit contenir la canStartApproval fonctionnalité . Pour vérifier les fonctionnalités d'un fichier, appelez la méthode get sur la ressource files avec le paramètre de chemin d'accès fileId et utilisez le champ de fonctionnalité 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 d'administrateur limitent 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.
Assurez-vous de partager manuellement le fichier cible avec les examinateurs. Drive n'effectue pas cette opération automatiquement. Si un examinateur n'a pas accès au fichier, la demande d'approbation aboutira, mais il ne recevra pas de notifications et ne pourra pas afficher 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 ne soit terminé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 Status objet qui détaille l'état de l'approbation lorsque la ressource est demandée. Elle inclut également l'objet ReviewerResponse qui détaille les réponses à une approbation effectuée par des examinateurs spécifiques. La réponse de chaque examinateur 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 examinateurs. Elle est également ajoutée au journal d'activité d'approbation.

Tous les examinateurs doivent approuver une approbation. Tout examinateur qui refuse une approbation définit l'état terminé sur DECLINED.

Une fois l'approbation terminée (l'état est APPROVED, CANCELLED ou DECLINED), elle reste dans l'état terminé 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 aucune approbation sur un fichier dont l'état est IN_PROGRESS.

Cycle de vie d'une approbation

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

Démarrer l'approbation. Appelez start pour lancer la demande d'approbation. Le status est ensuite défini sur IN_PROGRESS.
Approbation en attente. Tant que l'approbation est en attente (status est défini sur IN_PROGRESS), l'initiateur et les examinateurs peuvent interagir avec elle. Ils peuvent ajouter un comment, l'initiateur peut reassign des examinateurs, et un ou plusieurs examinateurs peuvent approve la demande.
L'approbation est dans l'état terminé. Une approbation passe à l'état terminé (status défini sur APPROVED, CANCELLED ou DECLINED) lorsque tous les examinateurs approuvent la demande, que l'initiateur choisit d'cancel la demande ou qu'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 fields paramètre système avec n'importe quelle méthode de la res3source.approvals Si vous omettez le paramètre fields, le serveur renvoie un ensemble de champs par défaut spécifique à 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 n'importe quelle autorisation OAuth 2.0 de l'API Drive existante qui autorise l'écriture de métadonnées de fichier. Pour en savoir plus, consultez Choisir les autorisations de l'API Google Drive.

Démarrer l'approbation

Pour démarrer une nouvelle approbation sur un fichier, utilisez la start méthode 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 examinateurs chargés d'examiner le fichier. Chaque adresse e-mail d'examinateur doit être associée à un compte Google, sinon la requête échoue. De plus, trois champs facultatifs sont proposés :

dueTime : date limite de l'approbation au format RFC 3339.
lockFile: valeur booléenne indiquant s'il faut verrouiller le fichier 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 examinateurs.

Le corps de la réponse contient une instance de la ressource approvals et inclut le initiator champ qui correspond à l'utilisateur qui a 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 start méthode échoue. Vous ne pouvez démarrer une approbation que s'il n'existe aucune approbation sur le fichier ou si l'approbation existante est dans l'état terminé (l'état est 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 l'approbation

Pour commenter une approbation, utilisez la comment méthode 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é à l'initiateur et aux examinateurs de l'approbation sous forme de notification. Il est également inclus dans le journal d'activité d'approbation.

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 à une approbation

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

La méthode reassign permet à l'initiateur de l'approbation (ou à un utilisateur disposant de l' role=writer permission) d'ajouter ou de remplacer des examinateurs dans l' ReviewerResponse objet 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 à une personne plus compétente.

Les examinateurs ne peuvent être réattribués que lorsque le Status est IN_PROGRESS et que le champ response de l'examinateur réattribué est défini sur NO_RESPONSE.

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

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 examinateurs sous forme de notification. Il est également inclus dans le journal d'activité d'approbation.

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 cancel méthode sur la approvals ressource et incluez les fileId et approvalId paramètres de chemin d'accès.

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' Status de l'approbation est IN_PROGRESS.

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

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 decline méthode 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'approbation Status est IN_PROGRESS.

Le corps de la requête se compose d' un champ facultatif message qui est une chaîne contenant le message à joindre au 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. Il est également inclus dans le journal d'activité d'approbation. Le response champ de l'ReviewerResponse objet de l'utilisateur demandeur est défini sur DECLINED. De plus, l'approbation Status est définie sur DECLINED et elle est dans un é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 approve méthode 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'Status de l'approbation est IN_PROGRESS.

Le corps de la requête se compose d'un champ facultatif message 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. Il est également inclus dans le journal d'activité d'approbation. Le response champ de l'ReviewerResponse objet de l'utilisateur demandeur est défini sur APPROVED. De plus, s'il s'agit de la dernière réponse d'examinateur requise, l'approbation Status est définie sur APPROVED et elle est dans un état 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 sur un fichier, vous devez être autorisé à lire les métadonnées du fichier. Pour en savoir plus, consultez Rôles et autorisations.

Obtenir l'approbation

Pour obtenir une approbation sur un fichier, utilisez la get méthode 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 list méthode 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 d'approbations sur le fichier. Le items champ inclut des informations sur chaque approbation sous la forme d'une approvals ressource.

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. Il doit être défini 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.

Gérer les approbations Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Concepts

État d'approbation

Cycle de vie d'une approbation

Utiliser le paramètre "fields"

Démarrer et gérer les approbations

Démarrer l'approbation

curl

Commenter l'approbation

curl

Réattribuer des examinateurs à une approbation

curl

Annuler l'approbation

curl

Refuser l'approbation

curl

Approuver l'approbation

curl

Localiser les approbations existantes

Obtenir l'approbation

curl

Lister les approbations

curl

Articles associés

Gérer les approbations