Ce guide explique comment utiliser la ressource revisions pour gérer les révisions de fichiers, par exemple pour obtenir une révision de fichier et publier une révision Google Workspace. L'API Google Drive vous permet également de télécharger des révisions. Pour en savoir plus sur la terminologie des révisions, consultez Présentation des modifications et des révisions.
Pour accéder à l'historique des révisions, un utilisateur doit disposer du role owner, organizer, fileOrganizer ou writer.
Pour 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 revisions. Si vous omettez le paramètre, le serveur renvoie un ensemble de champs par défaut. Par exemple, la méthode revisions.list ne renvoie que les champs id, mimeType, kind et modifiedTime. Pour renvoyer différents champs, consultez Renvoyer des champs spécifiques.
Spécifier les révisions à enregistrer pour éviter la suppression automatique
Google Drive supprime automatiquement les anciennes révisions qui ne présentent plus d'intérêt pour l'utilisateur.
Une révision de fichier blob peut être définie sur "Conserver indéfiniment", ce qui signifie qu'elle ne peut pas être supprimée automatiquement. Vous pouvez définir jusqu'à 200 révisions sur "Conserver indéfiniment". Elles sont comptabilisées dans votre limite de stockage. La révision principale n'est jamais supprimée automatiquement.
Toute révision de fichier blob, autre que la révision principale, qui n'est pas désignée comme "Conserver indéfiniment" peut être supprimée. Les révisions supprimables sont généralement conservées pendant 30 jours, mais peuvent être supprimées plus tôt si un fichier comporte 100 révisions qui ne sont pas désignées comme "À conserver indéfiniment " et qu'une nouvelle révision est importée.
Vous pouvez définir le champ booléen keepForever de la ressource revisions sur true pour marquer les révisions que vous ne souhaitez pas que Drive supprime. Une fois qu'une révision de fichier blob est définie sur "Conserver indéfiniment", elle ne peut être que téléchargée ou supprimée. Pour en savoir plus, consultez Télécharger une révision ou Supprimer une révision.
Si vous utilisez l'ancienne API Drive v2, utilisez le champ pinned de la ressource revisions au lieu de keepForever.
Obtenir une révision de fichier
Pour obtenir les métadonnées ou le contenu d'une révision de fichier, utilisez la méthode get sur la ressource revisions avec les paramètres de chemin d'accès fileId et revisionId. Si vous ne connaissez pas l'ID de révision, vous pouvez lister toutes les révisions d'un fichier à l'aide de la méthode list.
La méthode renvoie les métadonnées de la révision sous la forme d'une instance de ressource revisions.
Pour reconnaître le risque de télécharger des logiciels malveillants connus ou d'autres fichiers abusifs, définissez le paramètre de requête acknowledgeAbuse sur true. Ce champ ne s'applique que lorsque le paramètre alt=media est défini et que l'utilisateur est le propriétaire du fichier ou un organisateur du Drive partagé dans lequel se trouve le fichier.
Lister les révisions d'un fichier
Pour lister les révisions d'un fichier, utilisez la méthode list sur la ressource revisions avec le paramètre de chemin d'accès fileId. La méthode renvoie une liste des révisions du fichier.
Transmettez les paramètres de requête suivants pour personnaliser la pagination ou filtrer les révisions :
pageSize: nombre maximal de révisions à renvoyer par page.pageToken: jeton de page reçu d'un appel de liste précédent. Fournissez ce jeton pour récupérer la page suivante.
Mettre à jour une révision de fichier
Pour mettre à jour une révision d'un fichier, utilisez la méthode update sur la ressource revisions avec les paramètres de chemin d'accès fileId et revisionId.
La méthode renvoie une instance d'une ressource revisions.
Télécharger une révision
Vous ne pouvez télécharger que les révisions de contenu de fichier blob marquées comme "Conserver indéfiniment". Si vous souhaitez télécharger une révision, assurez-vous d'abord de la définir sur "Conserver indéfiniment". Pour en savoir plus, consultez Spécifier les révisions à enregistrer pour éviter la suppression automatique.
Pour télécharger une révision du contenu d'un fichier blob ou exporter une révision du contenu d'un document Google Workspace, consultez Télécharger et exporter des fichiers.
Supprimer une révision de fichier
Pour supprimer définitivement une révision de fichier, utilisez la méthode delete sur la ressource revisions avec les paramètres de chemin d'accès fileId et revisionId.
Vous ne pouvez supprimer que les révisions des fichiers blob avec du contenu binaire dans Drive, comme les images, les vidéos et les PDF. Vous pouvez supprimer une révision de fichier blob lorsqu'elle est marquée comme "Conserver indéfiniment". Les révisions d'autres fichiers, comme un fichier Google Docs ou Sheets, et la dernière révision restante du fichier binaire ne peuvent pas être supprimées.
Publier une révision
Pour publier une révision Google Docs, Google Sheets ou Google Slides, définissez la propriété published pour ce fichier dans la ressource revisions. Cette propriété ne peut pas être définie pour les révisions Google Sites à l'aide de l'API Drive.
Les révisions publiées ne reflètent pas les modifications apportées à un fichier, sauf si la propriété publishAuto est définie. Si la propriété est définie sur true, les révisions plus récentes d'un fichier sont automatiquement publiées, ce qui remplace les précédentes.
Seuls Slides et Drawings sont compatibles avec la republication automatique. Ils nécessitent que la propriété publishAuto soit définie sur true. Pour les fichiers Sites, publishAuto est toujours false.
Si le fichier est créé dans un domaine Google Workspace, la propriété publishedOutsideDomain indique si la révision est accessible à tous ou si elle est réservée aux utilisateurs du domaine. Pour les fichiers Sites, cette propriété indique si une autorisation type=anyone existe. Pour en savoir plus, consultez le champ type de la ressource permissions.
La publication automatique est également contrôlée par la case à cocher "Republier automatiquement après chaque modification" dans l'interface utilisateur de Docs et Sheets. Pour en savoir plus, consultez Rendre Google Docs, Sheets, Slides et Forms publics.